3.3.4.2 S_DSGetPropsEx (Opnum 1)

  • Article

The S_DSGetPropsEx method returns the properties associated with the object specified by a directory service pathname. This method differs from S_DSGetProps (section 3.1.4.7) in that it supports a restricted set of properties that pertain only to queue or machine object security.

 HRESULT S_DSGetPropsEx(
   [in] handle_t hBind,
   [in, range(1, 58)] DWORD dwObjectType,
   [in] const wchar_t* pwcsPathName,
   [in, range(1,128)] DWORD cp,
   [in, size_is(cp)] PROPID aProp[],
   [in, out, size_is(cp)] PROPVARIANT apVar[],
   [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.

dwObjectType:  Specifies the type of object for which properties are to be retrieved. MUST be set to one of the object types, as specified in section 2.2.8.

pwcsPathName: MUST be set by the client to a pointer to a NULL-terminated 16-bit Unicode string that contains the directory service pathname, as specified in section 2.2.9, of the object in the Directory Service from which to retrieve the properties.

cp:  MUST be set to the size (in elements) of the arrays aProp and apVar, which for this method MUST be one (0x00000001). The arrays aProp and apVar MUST have an identical number of elements, and MUST each contain exactly one element.

aProp:  An array of identifiers of properties to retrieve from the object. Each element MUST specify a value from the property identifiers table for the object type specified in dwObjectType. Each element MUST specify the property identifier for the corresponding property value at the same element index in apVar. The array MUST contain exactly one element.

apVar:  MUST be set by the client to an array that holds the property values retrieved from the object. Each element MUST be set by the server to the property value for the corresponding property identifier at the same element index in aProp. The array MUST contain exactly one element.

phServerAuth:  A PCONTEXT_HANDLE_SERVER_AUTH_TYPE 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: A buffer that contains a signed hash over the returned property values. See the pbServerSignature parameter description in section 3.1.4.7.

pdwServerSignatureSize: A DWORD that contains the maximum length of the server signature in bytes to return.

Return Values:  If the method succeeds, the return value is MQ_OK (0x00000000). 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 protocol, as specified in [MS-RPCE].

When processing this call, the server MUST:

  • Verify that the arrays aProp and apVar contain at least one element. If not, the server SHOULD<155> return an error.

  • Verify that dwObjectType is either MQDS_QUEUE or MQDS_MACHINE. Verify that the property identifiers supplied in the aProp parameter are a subset of the following identifiers. Return an error when the input is invalid.

  • Let dirObject be a directory object and initialized to NULL.

  • Generate a Get Directory Object (section 3.1.6.12) event with the following arguments:

    • iObjectType := dwObjectType.

    • iPathName := pwcsPathName.

    • iGuid := NULL.

  • If rStatus returned by the event is not 0x00000000, return an error and take no further action; otherwise, set dirObject to the returned rObject.

  • If the dwObjectType is MQDS_QUEUE:

    • And the property identifier supplied in the first element of the aProp parameter is PROPID_Q_OBJ_SECURITY:

      • Set the first element in apVar to dirObject.Security.

  • If the dwObjectType is MQDS_MACHINE:

    For each property identifier in the aProp parameter:

    • If the property identifier is PROPID_QM_OBJ_SECURITY:

      • Set the corresponding element in apVar to dirObject.Security.

    • If the property identifier is PROPID_QM_ENCRYPT_PKS:

      • Set the corresponding element in apVar to dirObject.PublicEncryptionKeyList.

    • If the property identifier is PROPID_QM_SIGN_PKS:

      • Set the corresponding element in apVar to dirObject.PublicSigningKeyList.

  • Set the pdwServerSignatureSize to contain 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).