3.1.4.18 S_DSLookupNext (Opnum 7)

  • Article

This method returns a portion of the data from the result set computed in a previous call to S_DSLookupBegin (section 3.1.4.17) and updates the cursor index to the first directory object that has not yet been returned to the client.

 HRESULT S_DSLookupNext(
   [in] handle_t hBind,
   [in] PCONTEXT_HANDLE_TYPE Handle,
   [in] LPBOUNDED_PROPERTIES dwSize,
   [out] unsigned long* dwOutSize,
   [out, size_is(*dwSize), length_is(*dwOutSize)] 
     PROPVARIANT pbBuffer[],
   [in] PCONTEXT_HANDLE_SERVER_AUTH_TYPE phServerAuth,
   [out, size_is(*pdwServerSignatureSize)] 
     unsigned char* pbServerSignature,
   [in, out] LPBOUNDED_SIGNATURE_SIZE pdwServerSignatureSize
 );

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

Handle: MUST contain an RPC context handle acquired from a previous call to S_DSLookupBegin. The handle MUST NOT have been used in a previous call to S_DSLookupEnd (section 3.1.4.19).

dwSize:  MUST point to an unsigned long that contains the maximum number of elements to be returned in the pbBuffer array. If this parameter is less than the number of elements in the pColumns parameter in the corresponding call to S_DSLookupBegin, the server MUST set the dwOutSize parameter to 0x00000000 and return without retrieving any object properties.

dwOutSize: A pointer to an unsigned LONG that the server MUST set to the number of properties returned in pbBuffer for the set of objects being returned from this invocation of the S_DSLookupNext method. The server MUST return as many completed sets of properties as will fit in the buffer. If no matching objects are found, the server MUST set this parameter to 0 to inform the client that there is no more data.

pbBuffer: MUST point to an array of PROPVARIANT (section 2.2.3) structures to contain the returned properties.

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). The server MUST use this parameter as a key to locate the GSS security context used to compute the signature returned in pbServerSignature. See section 3.1.4.2.

pbServerSignature:  MUST point to the signed hash over the property values returned in pbBuffer. See the pbServerSignature parameter description in section 3.1.4.7.

pdwServerSignatureSize:  MUST be set by the client to point to an unsigned LONG that contains the maximum length in bytes of the server signature to return. MUST be set by the server to the actual length in bytes of the server signature on output. If the server signature is larger than the supplied buffer, the server MUST return MQ_ERROR_USER_BUFFER_TOO_SMALL (0xC00E0028).

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)

MQ_ERROR_USER_BUFFER_TOO_SMALL (0xC00E0028)

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 Lookup Directory Next (section 3.1.6.8) event with the following argument:

    • iLookupDescriptor := the object referenced by the Handle parameter

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

  • If rPropertyValue of the event is empty:

    • Set dwOutSize to 0x00000000

  • Else:

    • Set dwOutSize to the number of elements in rPropertyValue.

    • Set pbBuffer to rPropertyValue

  • Return MQ_OK.