Share via

3.1.4.1 I_nsi_lookup_begin (Opnum 0)

  • Article

The I_nsi_lookup_begin method is invoked by a client locator to enumerate the binding information for a set of RPC servers that satisfy a given set of criteria. The Microsoft Interface Definition Language (MIDL) syntax of the method is specified as follows.

 void I_nsi_lookup_begin(
   [in] handle_t hrpcPrimaryLocatorHndl,
   [in] unsigned long entry_name_syntax,
   [in] STRING_T entry_name,
   [in, unique] RPC_SYNTAX_IDENTIFIER* interfaceid,
   [in, unique] RPC_SYNTAX_IDENTIFIER* xfersyntax,
   [in] NSI_UUID_P_T obj_uuid,
   [in] unsigned long binding_max_count,
   [in] unsigned long MaxCacheAge,
   [out] NSI_NS_HANDLE_T* import_context,
   [out] unsigned short* status
 );

hrpcPrimaryLocatorHndl: An RPC server binding handle, as specified in [C706] Part 2, "Binding Handle". A client creates this handle by binding to the locator server using the UUID specified in section 1.9 and endpoint specified in section 2.1. A client can create the binding handle using the rpc_string_binding_compose and rpc_binding_from_string_binding APIs (as specified in [C706] the "rpc_string_binding_compose" section) or equivalent on the client systems' implementation of RPC. When all operations using this handle are completed, use the equivalent of rpc_binding_free to free the handle resources.

entry_name_syntax: An identifier that represents the syntax used for entry_name. The value MUST be RPC_C_NS_SYNTAX_DCE.<8>

entry_name: A Unicode [UNICODE] string optionally specifying the entry name of the name service entry, using the syntax identified by the entry_name_syntax parameter, as specified in section 2.2.2. This parameter can optionally be null or an empty string.

interfaceid: An optional interface specification. Specified to request only bindings for server entries that have advertised interfaces compatible with this parameter. The client sets interfaceid to NULL to indicate that this parameter is not specified. Interface compatibility is specified in section 3.4.1.5.1.

xfersyntax: An optional transfer syntax specification. Specified to request only bindings for server entries that have advertised interfaces compatible with this parameter. The client sets xfersyntax to NULL to indicate that this parameter is not specified. Interface compatibility is specified in section 3.4.1.5.1.

obj_uuid: An optional pointer to an object UUID specification. Specified to request only bindings for the server entries that export this object UUID. If the parameter is NULL or if it contains a null GUID, the parameter is ignored.

binding_max_count: The maximum number of elements allowed in the binding vector returned from the I_nsi_lookup_next method. If 0 is specified, an appropriate implementation-specific default maximum MUST be used.<9>

MaxCacheAge: Specifies the maximum number of seconds that any results returned from a cache might have been present in the cache without being refreshed. This information is as specified in [C706] Part 2, Name Service Caching.

import_context: On successful completion of this method, returns a context handle for enumerating binding vectors by using the I_nsi_lookup_next method. This context handle MUST be closed by using the I_nsi_lookup_done method.

status: A 16-bit value that indicates the results of the method call. In case of success, the value MUST be NSI_S_OK. The value MUST be a nonzero value on failure. All failures MUST be treated identically as failure of the whole enumeration process.

Return Values: This method does not return any values. RPC exceptions might be thrown from this method.

Exceptions Thrown

No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].