NAME

rpc_ns_binding_import_next - Returns a binding handle of a compatible server (if found) from the name service database

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

Output

bindingReturns a compatible server binding handle. 

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_import_next routine returns one compatible (to the client) server binding handle.  The server offers the interface and object UUID specified by the respective if_handle and obj_uuid arguments in the rpc_ns_binding_import_begin routine. 

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

The rpc_ns_binding_import_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 a random order. 

       •The search operation returns members of a profile with the same priority in a random order. 

The returned compatible binding handle always contains an object UUID.  Its value depends on the value specified in argument obj_uuid 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.  The import-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.

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 the rpc_ns_binding_import_next routine, the routine returns another server binding handle. The returned binding handles 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 argument binding. 

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

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 the rpc_ns_binding_import_done routine if the application wants to start a new search for compatible servers (by calling the rpc_ns_binding_import_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_ns_binding_import_begin(3), rpc_ns_binding_import_done(3), rpc_ns_binding_inq_entry_name(3), rpc_ns_binding_lookup_begin(3), rpc_ns_binding_lookup_done(3), rpc_ns_binding_lookup_next(3), rpc_ns_binding_select(3)