RpcNsBindingImportNext

The RpcNsBindingImportNext function looks up an interface, and optionally an object from a name-service database, and returns a binding handle of a compatible server (if found).

#include <rpc.h>
RPC_STATUS RPC_ENTRY RpcNsBindingImportNext( 
  RPC_NS_HANDLE  ImportContext,   
  RPC_BINDING_HANDLE *  Binding  
);
 

Parameters

ImportContext

Specifies a name-service handle returned from the RpcNsBindingImportBegin routine.

Binding

Returns a pointer to a client-compatible server binding handle for a server.

Return Values

Remarks

The RpcNsBindingImportNext routine returns one client-compatible server binding handle for a server offering the interface and object UUID specified by the IfSpec and ObjUuid arguments in the RpcNsBindingImportBegin routine. The RpcNsBindingImportNext routine communicates only with the name-service database, not directly with servers.

Effective with version 5.0 of Windows NT, the RPC environment uses the Active Directory as its name service database and the order in which the runtime environment performs the lookup is as follows:

• Lookup in the local cache. If there is no entry,
• Lookup in the Active Directory. If there is no entry,
• Send broadcast requests to all other Directory Services in the domain.
  Note that if the entry exists in the Active Directory, but there is no information associated with the entry, the runtime will not issue this broadcast request.

The returned compatible binding handle always contains an object UUID. Its value depends on the ObjUuid argument value specified in the RpcNsBindingImportBegin routine as follows:

• If a non-nil object UUID was specified, the returned binding handle contains that object UUID.
• If a nil object UUID or null value was specified, 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 non-deterministic fashion. As a result, a different object UUID can be returned for each compatible binding handle from a single server entry.

The RpcNsBindingImportNext routine selects and returns one server binding handle from the compatible binding handles found. The client application can use that binding handle to attempt to make a remote procedure call to the server. If the client fails to establish a relationship with the server, it can call the RpcNsBindingImportNext routine again.

Each time the client calls the RpcNsBindingImportNext routine, the routine returns another server binding handle. The returned binding handles are unordered.

A client application calls the RpcNsBindingInqEntryName routine to obtain the name-service database in the entry name from which the binding handle came.

When the search reaches the end of the name-service database, the routine returns a status of RPC_S_NO_MORE_BINDINGS and returns a binding argument value of NULL.

The RpcNsBindingImportNext routine allocates storage for the data referenced by the returned Binding argument. When a client application finishes with the binding handle, it must call the RpcBindingFree routine to deallocate the storage. Each call to the RpcNsBindingImportNext routine requires a corresponding call to the RpcBindingFree routine.

The client is responsible for calling the RpcNsBindingImportDone routine. RpcNsBindingImportDone deletes the import context. The client also calls the RpcNsBindingImportDone routine if the application wants to start a new search for compatible servers (by calling the RpcNsBindingImportBegin routine). The order of binding handles returned is different for each new search. This means the order in which binding handles are returned to an application can be different each time the application is run.

QuickInfo

  Windows NT: Yes
  Windows CE: Unsupported.
  Header: Declared in rpcnsi.h.
  Import Library: Link with rpcns4.lib.

See Also

RpcBindingFree, RpcNsBindingImportBegin, RpcNsBindingImportDone, RpcNsBindingInqEntryName, RpcNsBindingLookupBegin, RpcNsBindingLookupDone, RpcNsBindingLookupNext, RpcNsBindingSelect