rpc_ns_binding_select(3rpc)

Used by client applications.

Synopsis

#include <dce/rpc.h>

void rpc_ns_binding_select(

rpc_binding_vector_t *binding_vec,

rpc_binding_handle_t *binding,

unsigned32 *status);

Parameters

Input/Output

binding_vec
Specifies the vector of compatible server binding handles from which a binding handle is selected. The returned binding vector no longer references the selected binding handle (returned separately in the binding parameter).

Output

binding
Returns a selected server binding handle.

status
Returns the status code from this routine, which indicates whether the routine completed successfully or, if not, why not.

Description
The rpc_ns_binding_select( ) routine randomly chooses and returns a server binding handle from a vector of server binding handles.

Each time the client calls rpc_ns_binding_select( ), the routine returns another binding handle from the vector.

When all of the binding handles are returned from the vector, the routine returns a status code of rpc_s_no_more_bindings and returns the value NULL in binding.

The select operation allocates storage for the data referenced by the returned binding parameter. When a client finishes with the binding handle, it calls rpc_binding_free( ) to deallocate the storage. Each call to the rpc_ns_binding_select( ) routine requires a corresponding call to rpc_binding_free( ).

Instead of using this routine, client applications can select a binding handle according to their specific needs. In this case the rpc_binding_to_string_binding( ) and rpc_string_binding_parse( ) routines are useful to the applications since the routines work together to extract the individual fields of a binding handle for examination.

Permissions Required
No permissions are required.

Return Values
No value is returned.

Errors

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

rpc_s_ok
Success.

rpc_s_no_more_bindings
No more bindings.

Related Information
Functions: rpc_binding_free(3rpc)

rpc_binding_to_string_binding(3rpc)

rpc_ns_binding_lookup_next(3rpc)

rpc_string_binding_parse(3rpc)