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_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.
The possible status codes and their meanings are as follows:
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.
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.
RELATED INFORMATION
Functions: rpc_binding_to_string_binding
rpc_binding_vector_free
rpc_ns_binding_import_next
rpc_ns_binding_inq_entry_name
rpc_ns_binding_lookup_begin
rpc_ns_binding_lookup_done
rpc_ns_binding_select
rpc_string_binding_parse