This method returns the properties associated with a directory object specified by a directory service pathname.
HRESULT S_DSGetProps( [in] handle_t hBind, [in, range(1,58)] unsigned long dwObjectType, [in] const wchar_t* pwcsPathName, [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 to be retrieved. MUST be set to one of the object types specified in section 2.2.8.
pwcsPathName: Pointer to a NULL-terminated 16-bit Unicode string that MUST contain the directory service pathname, as specified in section 2.2.9, to the object in the directory service.
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 property identifiers specifying the set of object properties to be returned. 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 pbServerSignature. See section 3.1.4.2.
pbServerSignature: Contains a signed hash over the returned property values.
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<38> 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.
Return an error code if the property identifier is not valid for the object type specified in dwObjectType.
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 := pwcsPathName.
iGuid := NULL.
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 of the apVar array whose vt field is VT_NULL, set the vt field to the appropriate VARTYPE for the corresponding property identifier at the same element index in the aProp array.
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.<39> If no properties are specified in aProp, the server SHOULD<40> 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 |
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).