Share via

3.3.4.1 S_DSGetComputerSites (Opnum 0)

  • Article

The S_DSGetComputerSites method returns the site identifier for every site of which the specified computer is a member.

 HRESULT S_DSGetComputerSites(
   [in] handle_t hBind,
   [in, unique] const wchar_t* pwcsPathName,
   [out] DWORD* pdwNumberOfSites,
   [out, size_is(,*pdwNumberOfSites), length_is(,*pdwNumberOfSites)] 
     GUID** ppguidSites,
   [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.

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. The pathname MUST be the pathname of an object of type MQDS_MACHINE.<154>

pdwNumberOfSites: Number of site identifiers returned in the ppguidSites parameter.

ppguidSites: An array of pointers to the GUID site identifiers of the sites of which the computer is a member. Each GUID referenced by the array MUST be the site identifier for a site that the machine object specified by pwcsPathName is a member of. These are obtained from the PROPID_QM_SITE_IDS property of the MQDS_MACHINE object. The array MUST contain the site identifier for every site to which the object specified by pwcsPathName is a member.

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 array of site GUIDs returned in ppguidSites.

pdwServerSignatureSize: 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:

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

    • iObjectType := MQDS_MACHINE.

    • iPathName := pwcsPathName.

    • iGuid := NULL.

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

  • Calculate the pbServerSignature by using the MD5 algorithm (as specified in [RFC1321]) and the GSS security context as specified by the following pseudocode.

    • Initialize an MD5 Hash context.

    • Add to the hash context the DWORD value 0x00000001.

    • Add to the hash value the DWORD value of VT_BLOB.

    • SET cbSize to pdwNumberOfSites times the size in bytes of a GUID.

    • Add to the hash value the DWORD value of cbSize.

    • Add to the hash context the contents of ppGuidSites where the length for the data is cbSize.

    • Call GSS_Wrap using the output context handle from 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.

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