RpcNsBindingLookupNext

The RpcNsBindingLookupNext function returns a list of compatible binding handles for a specified interface and optionally an object.

#include <rpc.h>
RPC_STATUS RPC_ENTRY RpcNsBindingLookupNext( 
  RPC_NS_HANDLE  LookupContext,   
  RPC_BINDING_VECTOR * *  BindingVec  
);
 

Parameters

LookupContext

Specifies the name-service handle returned from the RpcNsBindingLookupBegin routine.

BindingVec

Returns a pointer to a pointer to a vector of client-compatible server binding handles.

Return Values

Remarks

The RpcNsBindingLookupNext routine returns a vector of client-compatible server binding handles for a server offering the interface and object UUID specified by the IfSpec and ObjUuid arguments in the RpcNsBindingLookupBegin routine. (Compare this to RpcNsBindingImportNext, which returns a single compatible server binding handle.)

The RpcNsBindingLookupNext 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 entry not found in local cache, lookup in that machine's Active Directory.
• If entry not found on local machine, send broadcast requests to all other Active 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.

On successive calls, the RpcNsBindingLookupNext routine traverses name-service database entries, collecting client-compatible server binding handles from each entry.

When the Microsoft Active Directory is the name-service database, RpcNsBindingLookupNext traverses the database only if the given entry name is null and the default entry (in the registry) is undefined or empty. Also, since mixed entries are not permitted in the Active Directory, the routine searches for server entry names only, not group or profile names.

When using the DCE Cell Directory Service (CDS) as the name-service database, if the entry at which the search begins (see the EntryName argument in RpcNsBindingLookupBegin) contains binding handles as well as an RPC group and/or a profile, RpcNsBindingLookupNext returns the binding handles from EntryName before searching the group or profile. This means that RpcNsBindingLookupNext can return a partially full vector before processing the members of the group or profile.

Each binding handle in the returned vector always contains an object UUID. Its value depends on the ObjUuid argument value specified in the RpcNsBindingLookupBegin routine as follows:

• If a non-nil object UUID was specified, each returned binding handle contains that object UUID.
• If a nil object UUID or null value was specified, the object UUID returned in each binding handle depends on how the server exported object UUIDs:
  • If the server did not export any object UUIDs, each returned binding handle contains a nil object UUID.
  • If the server exported one object UUID, each returned binding handle contains that object UUID.
  • If the server exported multiple object UUIDs, each binding handle contains one of the object UUIDs. The lookup-next operation selects the returned object UUID in a non-deterministic fashion. For this reason, a different object UUID can be returned for each compatible binding handle from a single server entry.

From the returned vector of server binding handles, the client application can employ its own criteria for selecting individual binding handles, or the application can call the RpcNsBindingSelect routine to select a binding handle. The RpcBindingToStringBinding and RpcStringBindingParse routines will be helpful for a client creating its own selection criteria.

The client application can use the selected 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 select another binding handle from the vector. When all of the binding handles in the vector have been used, the client application calls the RpcNsBindingLookupNext routine again.

Each time the client calls the RpcNsBindingLookupNext routine, the routine returns another vector of binding handles. The binding handles returned in each vector are unordered. The vectors returned from multiple calls to this routine are also unordered.

A client calls the RpcNsBindingInqEntryName routine to obtain the name-service database server entry name that the binding came from.

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

The RpcNsBindingLookupNext routine allocates storage for the data referenced by the returned BindingVec argument. When a client application finishes with the vector, it must call the RpcBindingVectorFree routine to deallocate the storage. Each call to the RpcNsBindingLookupNext routine requires a corresponding call to the RpcBindingVectorFree routine.

The client is responsible for calling the RpcNsBindingLookupDone routine. RpcNsBindingLookupDone deletes the lookup context. The client also calls the RpcNsBindingLookupDone routine if the application wants to start a new search for compatible servers (by calling the RpcNsBindingLookupBegin routine). The order of binding handles returned can be different for each new search.

QuickInfo

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

See Also

RpcBindingToStringBinding, RpcBindingVectorFree, RpcNsBindingInqEntryName, RpcNsBindingLookupBegin, RpcNsBindingLookupDone, RpcStringBindingParse