NAME

rpc_ns_binding_lookup_next - 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_contextSpecifies a name service handle. This handle is returned from the rpc_ns_binding_lookup_begin routine. 

Output

binding_vecReturns a vector of compatible server binding handles. 

statusReturns the status code from this routine.  This status code indicates whether the routine completed successfully or, if not, why not.  The possible status codes and their meanings are as follows:

rpc_s_okSuccess. 

rpc_s_entry_not_foundName service entry not found. 

rpc_s_invalid_ns_handleInvalid name service handle. 

rpc_s_name_service_unavailable
Name service unavailable.

rpc_s_no_more_bindingsNo more bindings. 

rpc_s_no_ns_permissionNo permission for name service operation. 

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 arguments 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.  Search operations obey the following rules for traversing the entries:

       •At each entry visited, the search operations randomly process binding information, then group members, then profile members.  Profile members (but not group 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 argument in routine rpc_ns_binding_lookup_begin) contains binding handles as well as an RPC group and/or a profile, routine rpc_ns_binding_lookup_next returns the binding handles from entry_name before searching the group or profile. This means that routine 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 argument object_uuid of the rpc_ns_binding_lookup_begin routine 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, each returned binding handle contains one of the object UUIDs.  The lookup-next operation selects the returned object UUID in a nondeterministic way.  So, a different object UUID can be returned for each compatible binding handle from a single server entry.

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 the rpc_ns_binding_select routine 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 of the binding handles in the vector are used, the client application calls the rpc_ns_binding_lookup_next routine again. 

Each time the client calls the rpc_ns_binding_lookup_next routine, 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 argument 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 argument binding_vec. 

A client application calls the rpc_ns_binding_inq_entry_name routine 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 argument. When a client application finishes with the vector, it must call the rpc_binding_vector_free routine to deallocate the memory. Each call to the rpc_ns_binding_lookup_next routine requires a corresponding call to the rpc_binding_vector_free routine. 

The client calls the rpc_ns_binding_lookup_done routine.  The rpc_ns_binding_lookup_done routine deletes the lookup context.  The client also calls the rpc_ns_binding_lookup_done routine if the application wants to start a new search for compatible servers (by calling the rpc_ns_binding_lookup_begin routine).  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. 

NOTE:

For this release, the RPC naming service (rpc_ns) routines are not implemented, nor is an independent naming service provided. 

RETURN VALUES

None. 

RELATED INFORMATION

Functions: rpc_binding_to_string_binding(3), rpc_binding_vector_free(3), rpc_ns_binding_import_next(3), rpc_ns_binding_inq_entry_name(3), rpc_ns_binding_lookup_begin(3), rpc_ns_binding_lookup_done(3), rpc_ns_binding_select(3), rpc_string_binding_parse(3)