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

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. The status code indicates whether the routine completed successfully, or if not, why not.

Possible status codes and their meanings include:

rpc_s_ok

Success.

rpc_s_entry_not_found

Name service entry not found.

rpc_s_not_rpc_entry

Not an RPC entry.

rpc_s_class_version_mismatch

Name service entry has incompatible RPC class version.

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.

DESCRIPTION

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_begin for 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 API and 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.

Notes:

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.

Note:

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.

Permissions Required

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.

RETURN VALUE

None.

SEE ALSO

rpc_ns_binding_import_next()

rpc_binding_vector_free()
rpc_binding_to_string_binding()
rpc_ns_binding_lookup_begin()
rpc_ns_binding_lookup_done()
rpc_ns_binding_select()
rpc_ns_binding_inq_entry_name()
rpc_ns_mgmt_set_exp_age()
rpc_string_binding_parse().

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.