Share via

3.1.4.1 RfrGetNewDSA (opnum 0)

  • Article

The RfrGetNewDSA method returns the name of an NSPI server or a server array.

 //opnum 0
 long RfrGetNewDSA(
  [in]                       handle_t          hRpc,
  [in]                       unsigned long     ulFlags,
  [in, string]               unsigned char *   pUserDN,
  [in,out,unique, string]    unsigned char * * ppszUnused,
  [in,out,unique, string]    unsigned char * * ppszServer);

hRpc: A remote procedure call (RPC) binding handle parameter, as specified in [C706] section 2. MUST NOT be NULL.

ulFlags: An unsigned long value, containing a set of bit flags. Unused; SHOULD be set to zero. Other values MUST be ignored by the server.

pUserDN: Optional, a DN indicating the mailbox owned by the client user. The client SHOULD pass this to the server. If supplied, the server SHOULD use that DN to affect which NSPI server is returned to the caller.

ppszUnused: A string. Unused; SHOULD be set to NULL. Other values MUST be ignored by the server.

ppszServer: A string. If the server does not return an error, ppszServer contains the FQDN of an NSPI server or a server array. On failure, the value is undefined.

Return Values: The server returns 0 for a successful execution. An error results in an HRESULT or other nonzero error code.

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

Upon receiving this message, the server MUST process the data from the client using the following constraints. If pUserDN is present and contains the DN of an Address Book object, the server MUST prioritize an NSPI server that contains a writeable copy of that Address Book object over NSPI servers that do not, and return a server array or a server from the user’s mailbox site.<2> The server can take other constraints into account, such as the network location of the NSPI server in comparison to the NSPI referral server or the client. The server MUST prioritize available, responsive NSPI servers over unresponsive ones. The server can consider load balancing of clients when more than one NSPI server has equal priority. After considering these constraints, method SHOULD return one NSPI server name in the ppszServer parameter and a return value of zero. If any errors occur and the method is not able to return the name of an NSPI server, a nonzero value MUST be returned.

Because the goal of the server is to balance load across multiple NSPI servers, clients MUST NOT expect the same NSPI server to be returned from the RfrGetNewDSA method, even if all inputs are the same.

A client SHOULD call the RfrGetNewDSA method and connects to the NSPI server returned from that method. The client SHOULD NOT connect to an NSPI server without first requesting a server name from RfrGetNewDSA.

Note that clients can connect to a messaging server with a co-located NSPI server and no NSPI referral server, as well as a messaging server with an NSPI referral server. When first connecting, the client will not have determined which type of messaging server they are connecting to, and therefore they will try to connect to the messaging server's co-located NSPI server. On subsequent connections to that server, the client will use the NSPI referral server. This is one exception to the protocol documentation that states that clients SHOULD always use the NSPI referral server. Clients written to this protocol documentation have no reason to connect to an NSPI server before using this protocol.

The NSPI server returned in the ppszServer parameter MUST support the same RPC protocol sequence used by the RPC binding handle.