3.1.4.17 S_DSLookupBegin (Opnum 6)

  • Article

This method performs a query over the directory objects and returns an RPC context handle that can be used to retrieve the result set through a subsequent series of calls to S_DSLookupNext (section 3.1.4.18). When the client has no further use of the RPC context handle returned from this method, the client can close the context handle through a call to S_DSLookupEnd (section 3.1.4.19).

 HRESULT S_DSLookupBegin(
   [in] handle_t hBind,
   [out] PPCONTEXT_HANDLE_TYPE pHandle,
   [in, unique] wchar_t* pwcsContext,
   [in, unique] MQRESTRICTION* pRestriction,
   [in, ref] MQCOLUMNSET* pColumns,
   [in, unique] MQSORTSET* pSort,
   [in] PCONTEXT_HANDLE_SERVER_AUTH_TYPE phServerAuth
 );

hBind: MUST specify an RPC binding handle, as specified in [MS-RPCE] section 2.

pHandle:  MUST be set by the server to point to an RPC context handle to be used in subsequent calls to S_DSLookupNext and S_DSLookupEnd.

pwcsContext:  Unicode string that specifies a starting point of the query within the directory service. The client SHOULD set this parameter to NULL, and the server MUST ignore it.

pRestriction: A pointer to an MQRESTRICTION (section 2.2.12) structure specifying a set of constraints over the objects to be returned. The server MUST restrict the query results to include only objects that have properties that satisfy all of the restrictions specified in this parameter. See section 2.2.12.

pColumns: A pointer to an MQCOLUMNSET (section 2.2.13) structure that specifies the object properties to be returned. The server MUST return (in the result set) only the properties specified by this parameter in the order specified by this parameter. See section 2.2.13.

pSort: A pointer to an MQSORTSET (section 2.2.15) structure that defines the sort order of the result set. The server MUST sort the objects in the result set according to this multikey sort order. See section 2.2.15.

phServerAuth: A PCONTEXT_HANDLE_SERVER_AUTH_TYPE (section 2.2.5) RPC context handle acquired from the pphServerAuth parameter in a previous call to S_DSValidateServer (section 3.1.4.2).

Return Values:  If the method succeeds, the return value is 0. If the method fails, the return value is an implementation-specific error code.

MQ_OK (0x00000000)

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

When processing this call, the server MUST:

  • Generate a Begin Directory Lookup (section 3.1.6.7) event with the following arguments:

    • iRestriction := pRestriction

    • iColumnSet := pColumns

    • iSort := pSort

  • If rStatus of the preceding event is not MQ_OK, return rStatus and take no further action.

  • Set pHandle to the reference of rLookupDescriptor returned by the event.

  • Return MQ_OK (0x00000000).