rpc_ns_binding_lookup_next- returns a list of binding handles of one or more compatible servers, if found, from the name service database
void rpc_ns_binding_lookup_next( rpc_ns_handle_t lookup_context, rpc_binding_vector_t **binding_vec, unsigned32 *status);
- Specifies a name service handle. This handle is returned from the rpc_ns_binding_lookup_begin() routine.
- Returns a vector of compatible server binding handles.
- Returns the status code from this routine. The status code indicates whether the routine completed successfully, or if not, why not.
Possible status codes and their meanings include:
Name service entry not found.
Not an RPC entry.
Name service entry has incompatible RPC class version.
Name service unavailable.
No more bindings.
No permission for name service operation.
The rpc_ns_binding_lookup_next() routine returns a vector of compatible exported server binding handles. Compatible binding handles are specified by the import_context argument that the application obtains by calling rpc_ns_binding_lookup_begin(). (See
tagmref_rpc_ns_binding_lookup_beginfor further information on the selection of compatible binding handles.)
A similar routine is rpc_ns_binding_import_next(), which returns one compatible server binding handle.
On successive calls, 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. Successive invocations eventually return all such binding handles from all relevant entries. When there are no further compatible binding handles, the routine returns a status code of rpc_s_no_more_bindings and the value NULL in binding_vec.
The rpc_ns_binding_lookup_next() routine obeys the binding search rules specified in
Introduction to the RPC APIand Name Service Interface.
Each returned compatible binding handle contains an object UUID. Its value depends on the value of the obj_uuid argument to the rpc_ns_binding_lookup_begin() call that returned lookup_context:
- When obj_uuid contains a non-nil object UUID, the returned binding handle contains that object UUID.
- When obj_uuid contains a nil object UUID, the object UUID returned in the binding handle depends on how the servers exported object UUIDs to namespace entries. For a given namespace entry in the traversal path:
- When servers did not export any object UUIDs to the given entry, the returned binding handle contains a nil object UUID.
- When servers exported one object UUID to the given entry, the returned binding handle contains that object UUID.
- When servers exported multiple object UUIDs to the given entry, the returned binding handle contains one of the object UUIDs. rpc_ns_binding_lookup_next() selects the returned object UUID in an unspecified way.
- 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 randomly ordered. The vectors returned from multiple calls to this routine are also randomly ordered.
When looking up compatible binding handles from a profile, the binding handles from entries of equal profile priority are randomly ordered 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 1, 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 0.
If the same compatible binding is encountered more than once in a search, rpc_ns_binding_lookup_next() may choose not to return every instance of the binding.
When the search finishes, the routine returns a status code of rpc_s_no_more_bindings and returns the value NULL in binding_vec.
- The rpc_ns_binding_inq_entry_name() routine is called by an application in order 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 an 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 application calls the rpc_ns_binding_lookup_done() to delete the lookup context when it is done with a search or to begin 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.
The application needs read permission to the specified name service object entry (the starting name service entry) and to any name service object entry in the resulting search path.
Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.