rpc_ns_binding_import_next(3rpc)

Used by client applications.

Synopsis

#include <dce/rpc.h>

void rpc_ns_binding_import_next(

rpc_ns_handle_t import_context,

rpc_binding_handle_t *binding,

unsigned32 *status);

Parameters

Input

import_context
Specifies a name service handle. This handle is returned from the rpc_ns_binding_import_begin( ) routine.

Output

binding
Returns a compatible server binding handle.

status
Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.

Description
The rpc_ns_binding_import_next( ) routine returns one compatible (to the client) server binding handle selected at random from the name service database. The server offers the interface and object UUID specified by the respective if_handle and obj_uuid parameters in rpc_ns_binding_import_begin( ).

A similar routine is rpc_ns_binding_lookup_next( ), which returns a vector of compatible server binding handles for one or more servers.

Note:Routine rpc_ns_binding_import_next( ) calls routine rpc_ns_binding_lookup_next( ) which, in turn, obtains a vector of server binding handles from the name service atabase. Next, routine rpc_ns_binding_import_next( ) randomly selects one of the elements from the vector.

The rpc_ns_binding_import_next( ) routine communicates only with the name service database, not directly with servers.

The returned compatible binding handle always contains an object UUID. Its value depends on the value specified in the obj_uuid parameter of the rpc_ns_binding_import_begin( ) routine, as follows:

· If obj_uuid contains a non-nil object UUID, the returned binding handle contains that object UUID.

· If obj_uuid contains a nil object UUID or NULL, the object UUID returned in the binding handle depends on how the server exported object UUIDs:

- If the server did not export any object UUIDs, the returned binding handle contains a nil object UUID.

- If the server exported one object UUID, the 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 multiple calls to rpc_ns_binding_import_next( ) returning different object UUIDs. In particular, note that each name service entry stores server address information separately from exported object UUIDs. Successive calls to rpc_ns_binding_import_next( ) using the same import context 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

The client application can use the returned binding handle to make a remote procedure call to the server. If the client fails to communicate with the server, it can call the rpc_ns_binding_import_next( ) routine again.

Each time the client calls rpc_ns_binding_import_next( ), the routine returns another server binding handle. The binding handles returned are unordered. Multiple binding handles can refer to different protocol sequences from the same server.

When the search finishes, the routine returns a status code of rpc_s_no_more_bindings and returns the value NULL in binding.

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_import_next( ) routine allocates memory for the returned binding parameter. When a client application finishes with the binding handle, it must call rpc_binding_free( ) to deallocate the memory. Each call to rpc_ns_binding_import_next( ) requires a corresponding call to rpc_binding_free( ).

The client calls the rpc_ns_binding_import_done( ) routine after it has satisfactorily used one or more returned server binding handles. The rpc_ns_binding_import_done( ) routine deletes the import context. The client also calls rpc_ns_binding_import_done( ) if the application wants to start a new search for compatible servers (by calling rpc_ns_binding_import_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_ns_binding_import_begin(3rpc)

rpc_ns_binding_import_done(3rpc)

rpc_ns_binding_inq_entry_name(3rpc)

rpc_ns_binding_lookup_begin(3rpc)

rpc_ns_binding_lookup_done(3rpc)

rpc_ns_binding_lookup_next(3rpc)

rpc_ns_binding_select(3rpc)