3.1.4.20 S_DSCreateServersCache (Opnum 20)

This method returns a list of Backup Site Controllers (BSCs) associated with a specified site. The client calls this method to enumerate the BSCs associated with sites in the configured list of sites in the enterprise.

 HRESULT S_DSCreateServersCache(
   [in] handle_t hBind,
   [in, out] unsigned long* pdwIndex,
   [in, out, ptr, string] wchar_t** lplpSiteServers,
   [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.

pdwIndex:  Pointer to an unsigned long that contains an index into the configured list of sites in the enterprise indicating the site to which the list of BSCs is to be returned.

lplpSiteServers:  Pointer to a pointer to a string that contains the list of servers associated with the indexed site. The string MUST be in Server List String (section 2.2.17) format.

phServerAuth: 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:  MUST be set by the server to a buffer that contains a signed hash over the server list returned in lplpSiteServers. The server MUST construct this signature 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 value 0x00000002
  
 Construct a PROPVARIANT apVar as follows
 SET apVar.vt to VT_UI4
 SET apVar.ulVal to the contents of pdwIndex
  
 Add to the hash context the property value apVar where 
        the length is defined as appropriate for the variant type
        apVar.vt
  
 Construct a PROPVARIANT apVar as follows
 SET apVar.vt to VT_LPWSTR
 SET apVar.pwszVal to the contents of lplpSiteServers
      
 Add to the hash context the property value apVar where 
        the length is defined as appropriate for the variant type 
        apVar.vt
  
 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
  

pdwServerSignatureSize:  MUST be set by the client to point to an unsigned LONG that contains the maximum length in bytes of the server signature to return. MUST be set by the server 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).

Return Values:  If the method succeeds, the return value is 0. If the method fails, the return value is an implementation-specific error code. The server MUST return MQDS_E_NO_MORE_DATA (0xC00E0523), if pdwIndex is an invalid index, into the configured list of sites in the enterprise.

MQ_OK (0x00000000)

MQDS_E_NO_MORE_DATA (0xC00E0523)

MQ_ERROR_USER_BUFFER_TOO_SMALL (0xC00E0028)

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC extension protocol, as specified in [MS-RPCE].

The S_DSCreateServersCache method returns information on Backup Site Controllers (BSCs) associated with sites in the enterprise. The client uses this method to iterate through the list of sites in the enterprise by calling the method repeatedly. Before the first invocation, the client sets the pdwIndex parameter to 0. After each successful invocation, the client increments the pdwIndex parameter by 1 and calls the method again. The client repeats this sequence until the method call returns an error.