Share via

3.1.4.2 I_nsi_lookup_next (Opnum 2)

  • Article

The I_nsi_lookup_next method is invoked to continue an enumeration of binding vectors that satisfy the criteria specified in a call to the I_nsi_lookup_begin method. The number of bindings in the binding_vector is limited by the parameter binding_max_count specified in the call to the I_nsi_lookup_begin method. The MIDL syntax of this method is specified as follows.

 void I_nsi_lookup_next(
   [in] handle_t hrpcPrimaryLocatorHndl,
   [in] NSI_NS_HANDLE_T import_context,
   [out] NSI_BINDING_VECTOR_P_T* binding_vector,
   [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.

import_context: A context handle returned by a preceding call to the I_nsi_lookup_begin method.

binding_vector: On successful completion, returns a vector containing bindings that satisfy the criteria defined in the preceding call to the I_nsi_lookup_begin method. The caller MUST not assume that the bindings are ordered. The client is responsible for freeing the memory allocated for the binding_vector. The memory allocated for the binding_vector does not need to be freed before subsequent calls to I_nsi_lookup_next.

status: A 16-bit value that indicates the result of the method call. Any other values, except those listed as follows, MUST be treated as failures and MUST be treated identically. Failure is typically a serious condition (e.g., host out of memory) and SHOULD abort the current operation and then propagated to the higher-layer caller. In the event of failure, the caller SHOULD invoke I_nsi_lookup_done immediately, although it might fail as well.

Value

Meaning

NSI_S_OK

0x00000000

The call returned successfully and binding vector contains at least one binding. There can be additional bindings that satisfy the criteria.

NSI_S_NO_MORE_BINDINGS

0x00000001

There are no more bindings that satisfy the criteria and binding vector contains no bindings.

Return Values: This method does not return any values.

Exceptions Thrown

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