Share via

3.3.4.3 S_DSGetPropsGuidEx (Opnum 2)

  • Article

This method returns the properties for the object specified by object identifier. This method differs from S_DSGetPropsGuid in that it supports a restricted set of properties that pertain only to queue or machine object security.

 HRESULT S_DSGetPropsGuidEx(
   [in] handle_t hBind,
   [in, range(1, 58)] DWORD dwObjectType,
   [in, unique] const GUID* pGuid,
   [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.

pGuid:  MUST specify a pointer to the object identifier of the object for which properties are to be retrieved.

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 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. 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 extension 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<156> return an error.

  • Verify that dwObjectType is either MQDS_QUEUE or MQDS_MACHINE. Verify that the property identifier supplied in the aProp parameter is one 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 := NULL.

    • iGuid := pGuid.

  • 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 parameter is MQDS_QUEUE:

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

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

  • If the dwObjectType is MQDS_MACHINE:

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

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

    • And the property identifier supplied in the aProp parameter is PROPID_QM_ENCRYPT_PKS:

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

    • And the property identifier supplied in the aProp parameter is PROPID_QM_SIGN_PKS:

  • Set the first 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).