rpc_ns_binding_lookup_next(3rpc)
Returns a list of binding handles of one or more compatible servers (if found) from the name service database
Used by client applications.
Synopsis
#include <dce/rpc.h>
void rpc_ns_binding_lookup_next(
rpc_ns_handle_t lookup_context,
rpc_binding_vector_t **binding_vec,
unsigned32 *status);
Parameters
Input
lookup_context
Specifies a name service handle. This handle is returned from the rpc_ns_binding_lookup_begin( ) routine.
Output
binding_vec
Returns a vector of compatible server binding handles.
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_lookup_next( ) routine returns a vector of compatible (to the client) server binding handles. The servers offer the interface and object
UUID specified by the respective if_handle and object_uuid parameters in rpc_ns_binding_lookup_begin( ). The number of binding handles that
rpc_ns_binding_lookup_next( ) attempts to return is the value of binding_max_count in the rpc_ns_binding_lookup_begin( ) routine.
A similar routine is rpc_ns_binding_import_next( ), which returns one compatible server binding handle.
The rpc_ns_binding_lookup_next( ) routine communicates only with the name service database, not directly with servers.
This routine traverses entries in the name service database, returning compatible server binding handles from each entry. The routine can return multiple binding handles from each entry. The search operation obeys the following rules for traversing the entries:
· At each entry visited, the search operation randomly processes binding information, then group members, then profile members. Profile members with different priorities are returned according to their priorities, highest priority first.
· The search operation returns members of a group in random order.
· The search operation returns members of a profile with the same priority in random order.
If the entry where the search begins (see the entry_name parameter in rpc_ns_binding_lookup_begin( )) contains binding handles as well as an RPC group and/or a profile, rpc_ns_binding_lookup_next( ) returns the binding handles from entry_name before searching the group or profile. This means that rpc_ns_binding_lookup_next( ) can return a partially full vector before processing the members of the group or profile.
Each binding handle in the returned vector always contains an object UUID. Its value depends on the value specified in the object_uuid parameter of rpc_ns_binding_lookup_begin( ) as follows:
· If object_uuid contains a non-nil object UUID, each returned binding handle contains that object UUID.
· If object_uuid contains a nil object UUID or NULL, the object UUID returned in each binding handle depends on how the server exported object UUIDs:
- If the server did not export any object UUIDs, each returned binding handle contains a nil object UUID.
- If the server exported one object UUID, each returned binding handle contains that object UUID.
- If the server exported multiple object UUIDs, the returned binding handle contains one of the object UUIDs, selected in an unspecified way.
Applications should not count on the binding handles returned from a given entry to contain different object UUIDs. In particular, note that each name service entry stores server address information separately from exported object UUIDs. One or more calls to rpc_ns_binding_lookup_next( ) will return exactly one binding for each compatible server address, not the cross product of all compatible server addresses with all exported UUIDs. Each returned binding will contain one of the exported object UUIDs, but applications should not count on any specific selection mechanism for these object UUIDs.
From the returned vector of server binding handles, the client application can employ its own criteria for selecting individual binding handles, or the application can call rpc_ns_binding_select(~) to select a binding handle. The rpc_binding_to_string_binding( ) and rpc_string_binding_parse( ) routines are useful for a client creating its own selection criteria.
The client application can use the selected binding handle to attempt a remote procedure call to the server. If the client fails to communicate with the server, it can select another binding handle from the vector. When all the binding handles in the vector are used, the client application calls rpc_ns_binding_lookup_next( ) again.
Each time the client calls rpc_ns_binding_lookup_next( ), the routine returns another vector of binding handles. The binding handles returned in each vector are unordered, as is the order in which the vectors are returned from multiple calls to this routine.
When looking up compatible binding handles from a profile, the binding handles from entries of equal profile priority are unordered in the returned vector. In addition, the vector returned from a call to rpc_ns_binding_lookup_next( ) contains only compatible binding handles from entries of equal profile priority. This means the returned vector may be partially full.
For example, if the binding_max_count parameter value in rpc_ns_binding_lookup_begin( ) was 5 and rpc_ns_binding_lookup_next( ) finds only three compatible binding handles from profile entries of priority 0 (zero), rpc_ns_binding_lookup_next( ) returns a partially full binding vector (with three binding handles). The next call to rpc_ns_binding_lookup_next( ) creates a new binding vector and begins looking for compatible binding handles from profile entries of priority 1.
When the search finishes, the routine returns a status code of rpc_s_no_more_bindings and returns the value NULL in binding_vec.
A client application calls rpc_ns_binding_inq_entry_name( ) to obtain the name of the entry in the name service database where the binding handle came from.
The rpc_ns_binding_lookup_next( ) routine allocates memory for the returned binding_vec. When a client application finishes with the vector, it must call rpc_binding_vector_free( ) to deallocate the memory. Each call to rpc_ns_binding_lookup_next( ) requires a corresponding call to rpc_binding_vector_free( ).
The client calls rpc_ns_binding_lookup_done( ), which deletes the lookup context. The client also calls rpc_ns_binding_lookup_done( ) if the application wants to start a new search for compatible servers (by calling rpc_ns_binding_lookup_begin( )). The order of binding handles returned can be different for each new search. This means that the order in which binding handles are returned to an application can be different each time the application is run.
Permissions Required
You need read permission to the specified CDS object entry (the starting name service entry) and to any CDS object entry in the resulting search
path.
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_class_version_mismatch
RPC class version mismatch.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_invalid_ns_handle
Invalid name service handle.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_more_bindings
No more bindings.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_not_rpc_entry
Not an RPC entry.
Related Information
Functions: rpc_binding_to_string_binding(3rpc)
rpc_ns_binding_import_next(3rpc)
rpc_ns_binding_inq_entry_name(3rpc)
rpc_ns_binding_lookup_begin(3rpc)
rpc_ns_binding_lookup_done(3rpc)
rpc_string_binding_parse(3rpc)