3.2.4.1.2 EstablishConnection (Opnum 1)

  • Article

The EstablishConnection method establishes an outbound connection, uniquely identified by a replication group ID/connection ID pair, from a client to a server. An outbound connection to the server is required before most other operations can be performed.

 DWORD EstablishConnection(
   [in] FRS_REPLICA_SET_ID replicaSetId,
   [in] FRS_CONNECTION_ID connectionId,
   [in] DWORD downstreamProtocolVersion,
   [in] DWORD downstreamFlags,
   [out] DWORD* upstreamProtocolVersion,
   [out] DWORD* upstreamFlags
 );

replicaSetId: The GUID of the outbound connection's replication group (see the objectGUID attribute specified in section 2.3.5).

connectionId: The GUID of the outbound connection (see the objectGUID attribute specified in section 2.3.11) in the specified replication group.

downstreamProtocolVersion: Identifies the version of the DFS-R protocol implemented by the client. Currently implemented protocol versions are specified in section 2.2.1.1.1.

downstreamFlags: This parameter is unused and SHOULD be set to 0 by the client.  <22>

upstreamProtocolVersion: Receives the version of the DFS-R protocol implemented by the server. Currently implemented protocol versions are specified in section 2.2.1.1.1.

upstreamFlags: A flags bitmask. The server MUST set the TRANSPORT_SUPPORTS_RDC_SIMILARITY bit flag to 1 if the server supports RDC similarity (as specified in [MS-RDC] section 3.1.5.4). Otherwise, the server MUST clear this bitmask (set all bits to 0). The client MUST ignore any bit flags other than TRANSPORT_SUPPORTS_RDC_SIMILARITY.

Return Values: The method MUST return 0 on success or a nonzero error code on failure. For protocol purposes all nonzero values MUST be treated as equivalent failures unless otherwise specified.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The method completed successfully.

0x0000235A

FRS_ERROR_INCOMPATIBLE_VERSION

The client's DFS-R protocol version is not compatible with the server's DFS-R protocol version.

0x00002342

FRS_ERROR_CONNECTION_INVALID

The connection is invalid.

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

Validating the connection request: The server validates the connection request by performing the following checks:

  • If the server is not a member of the specified replication group it MUST fail the call with an implementation-defined failure value.

  • If the specified connection does not exist in the specified replication group's configuration and the replication group's type (see the msDFSR-ReplicationGroupType attribute specified in section 2.3.5) is not SYSVOL, then the server MUST fail the call with FRS_ERROR_CONNECTION_INVALID.

  • If the replication group's type is SYSVOL and the specified connection does not exist in the specified replication group's configuration and there is no Member object in the specified replication group's configuration, the server MUST fail the request with FRS_ERROR_CONNECTION_INVALID.

  • If the replication group's type is SYSVOL and the client is not a domain controller in the same domain as the server, or if the server is not a domain controller, then the server MUST fail the call with FRS_ERROR_CONNECTION_INVALID.

  • If the specified connection is disabled (see the msDFSR-Enabled attribute specified in section 2.3.11) then the server MUST fail the call with FRS_ERROR_CONNECTION_INVALID.

  • If the server is not the specified connection's outbound partner, or the client is not the connection's inbound partner (see the FromServer attribute specified in section 2.3.11) then the server MUST fail the call with FRS_ERROR_CONNECTION_INVALID.

  • If the client's protocol version number is 0x00050001, or if the client's protocol's major version number (see section 2.2.1.1.1) is not equal to the server protocol's major version number, then the server MUST fail the call with the FRS_ERROR_INCOMPATIBLE_VERSION failure value.

Actions Triggered: Upon successfully validating the connection request, the server establishes an outbound connection with the client.

If the specified connection does not exist in the specified replication group's configuration and the replication group's type is SYSVOL and there is a Member object in the specified replication group's configuration, then the server MUST behave as if the replication group's configuration contains an enabled connection in which the server is the connection's outbound partner and the client is the connection's inbound partner.

The server MUST ensure that no more than one outbound connection for a unique replicaSetId / connectionId pair exists with the client at the same time. If an outbound connection with the client already exists for the same unique replicaSetId / connectionId pair, the server MUST replace the pre-existing connection with a new connection. The pre-existing outbound connection MUST be torn down by the server, and all outstanding calls associated with the pre-existing connection MUST be completed with an implementation-defined failure value.