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_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. 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_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 database.
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.
RELATED INFORMATION
Functions: rpc_ns_binding_import_begin
rpc_ns_binding_import_done
rpc_ns_binding_inq_entry_name
rpc_ns_binding_lookup_begin
rpc_ns_binding_lookup_done
rpc_ns_binding_lookup_next
rpc_ns_binding_select