Share via

3.1.4.8 S_DSGetPropsGuid (Opnum 11)

  • Article

This method returns properties associated with a directory object specified by an object identifier.

 HRESULT S_DSGetPropsGuid(
   [in] handle_t hBind,
   [in, range(1,58)] unsigned long dwObjectType,
   [in, unique] const GUID* pGuid,
   [in, range(1,128)] unsigned long cp,
   [in, size_is(cp)] unsigned long 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 retrieved. MUST be set to one of the object types specified in section 2.2.8.

pGuid:  MUST be set by the client to a pointer to the GUID of the object for which properties are retrieved.

cp:  MUST be set to the size (in elements) of the arrays aProp and apVar. The arrays aProp and apVar MUST have an identical number of elements and MUST contain at least one element.

aProp:  An array of identifiers of properties to retrieve from the object designated by pGuid. Each element MUST specify a value from the property identifiers table (defined in section 2.2.10.1) 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 at least one element.

apVar: On input, each element MUST be initialized to the appropriate VARTYPE ([MS-MQMQ] section 2.2.12.1) for the associated property specified by the same element in aProp, or VT_NULL. On success, the server MUST populate the elements of this array with property values for the properties identified by the corresponding elements of aProp. The array MUST contain at least 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 the pbServerSignature parameter. See section 3.1.4.2.

pbServerSignature:  See the pbServerSignature parameter description, as specified in section 3.1.4.7.

pdwServerSignatureSize:  Contains the maximum length in bytes of the server signature to return.

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT. Additionally, if a failure HRESULT is returned, the client MUST disregard all out-parameter values.

MQ_OK (0x00000000)

MQ_ERROR_USER_BUFFER_TOO_SMALL (0xC00E0028)

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

MQ_ERROR_ILLEGAL_PROPID (0xC00E0039)

MQ_ERROR (0xC00E0001)

MQ_ERROR_DS_ERROR (0xC00E0043)

MQDS_OBJECT_NOT_FOUND (0xC00E050F)

E_ADS_PROPERTY_NOT_FOUND (0x8000500D)

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 each of the aProp and apVar arrays contains at least one element. If not, the server SHOULD<41> return an error.

  • Verify for each property identifier in aProp, that the property identifier is valid for the object type specified in dwObjectType as specified in the tables in section 2.2.10.1.

  • Determine if each element of apVar is set to VT_NULL or to the appropriate VARTYPE for the corresponding property identifier at the same element index in aProp. If not, return an error code.

  • 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 rStatus and take no further action; otherwise, set dirObject to the returned rObject.

  • For each element in the aProp array, populate the corresponding element of the apVar array from dirObject according to the rules defined in the following table. If any of the aProp elements is not present in the rules, return an error HRESULT.<42> If no properties are specified in aProp, the server SHOULD<43> return MQ_ERROR_INVALID_PARAMETER (0xC00E0006). If any property in aProp is a private property, the server MUST return MQ_ERROR_ILLEGAL_PROPID (0xC00E0039).

    Value of dwObjectType

    Rules

    MQDS_QUEUE

    See section 3.1.4.21.8.1.4

    MQDS_MACHINE

    See section 3.1.4.21.8.1.1

    MQDS_SITE

    See section 3.1.4.21.8.1.8

    MQDS_CN

    See section 3.1.4.21.8.1.10

    MQDS_ENTERPRISE

    See section 3.1.4.21.8.1.6

    MQDS_ROUTINGLINK

    See section 3.1.4.21.8.1.9

    MQDS_USER

    See section 3.1.4.21.8.1.11

  • Construct the pbServerSignature parameter by creating a hash by using the MD5 algorithm, as specified in [RFC1321], and sealing it, as specified by the following pseudocode:

     Initialize an MD5 hash context
  
 Add to the hash context the DWORD data value representing the count 
 of properties to be returned (from parameter cp).
  
 FOR each property returned in apVar
  
 Add to the hash context the DWORD value of the property 
  identifier (from aProp[])
  
 Add to the hash context the type-specific data value of the 
  property (from apVar[]). The data value and length are 
  defined by the variant type of the property (apVar[].vt)
 ENDFOR
  
 Call GSS_Wrap using the token from output context handle from the 
 GSS security context and the computed MD5 hash
  
 Set pbServerSignature to the wrapped MD5 hash
  
 Set *pdwServerSignatureSize to the size of the wrapped MD5 hash
 

  • MUST set the pdwServerSignatureSize parameter 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).