NAME

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

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. Applications obtain this handle by calling rpc_ns_binding_import_begin().

Output

binding

Returns a compatible server binding handle.

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_import_next() routine returns one compatible, exported server binding handle. Compatible binding handles are specified by the import_context argument that the application obtains by calling rpc_ns_binding_import_begin(). (See tagmref_rpc_ns_binding_import_begin for further information on the selection of compatible binding handles.)

Note:

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

On successive calls, this routine returns a series of compatible bindings, one at a time. Successive invocations eventually return all such bindings from all relevant entries. When there are no further compatible bindings, the routine returns a status code of rpc_s_no_more_bindings and the value NULL in the binding argument.

The rpc_ns_binding_import_next() routine obeys the binding search rules specified in Introduction to the RPC API and Name Service Interface . The order in which bindings are returned to the application depends on the search rules in the following way: when the search encounters a binding attribute containing compatible bindings, successive calls to rpc_ns_binding_import_next() return all compatible bindings from that attribute in random order.

Notes:

Bindings are returned from each binding attribute in random order in order to provide load balancing among bindings.

Implementations may buffer bindings from each binding attribute in an implementation-dependent sized buffer. If the number of compatible bindings from a binding attribute exceeds the buffer size, bindings are returned from the buffer in random order until the buffer is exhausted. Then the buffer is refilled from the same binding attribute. This process is repeated until all the bindings from the binding attribute have been returned. In this case, returned bindings are randomised within a buffer, but not among buffers.

Because of this randomisation, the order in which bindings are returned can be different for each new search beginning with a call to rpc_ns_binding_import_next(). This means that the order in which bindings are returned to an application can be different each time the application is run.

The returned compatible binding contains an object UUID. Its value depends on the value of the obj_uuid argument to the rpc_ns_binding_import_begin() call that returned import_context:

• When obj_uuid contains a non-nil object UUID, the returned binding contains that object UUID.

• When obj_uuid contains a nil object UUID, the object UUID returned in the binding 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 contains a nil object UUID.

  • When servers exported one object UUID to the given entry, the returned binding contains that object UUID.

  • When servers exported multiple object UUIDs to the given entry, the returned binding contains one of the object UUIDs. rpc_ns_binding_import_next() selects the returned object UUID in an unspecified way.

The client application can use the returned compatible binding handle to make a remote procedure calls to the server.

Note:

If the client fails to communicate with the server, it can call rpc_ns_binding_import_next() again.

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

If the same compatible binding is encountered more than once in a search, rpc_ns_binding_import_next() may choose not to return every instance of the binding. 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 application calls the rpc_ns_binding_import_done() routine when it has finished using the import context. This deletes the import context.

Permissions Required

The application needs read permission to the starting name service entry and to any object entry in the resulting traversal path.

RETURN VALUE

None.

SEE ALSO

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()
rpc_ns_binding_export()
rpc_ns_import_ctx_add_eval()
rpc_ns_mgmt_set_exp_age().

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.