Share via

3.2.4.1.3 EstablishSession (Opnum 2)

  • Article

The EstablishSession method is used to establish a replicated folder session between the client and server after the client has successfully established an outbound connection with the server via a call to the EstablishConnection method. A replicated folder session with the server is required before most other operations associated with the specified replicated folder can be performed.

 DWORD EstablishSession(
   [in] FRS_CONNECTION_ID connectionId,
   [in] FRS_CONTENT_SET_ID contentSetId
 );

connectionId: The GUID of an outbound connection (see the objectGUID attribute specified in section 2.3.11) that the client established by a previous call to the EstablishConnection method.

contentSetId: The GUID of the replicated folder (see the objectGUID specified in section 2.3.7) in the specified connection's replication group.

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.

0x00002342

FRS_ERROR_CONNECTION_INVALID

The connection is invalid.

0x00002375

FRS_ERROR_CONTENTSET_READ_ONLY

The replicated folder is read-only.

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

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

  • If an outbound connection for the specified connection is not established between the client and server (see the EstablishConnection method) then the server MUST fail the call with the FRS_ERROR_CONNECTION_INVALID failure value.

  • If the server is not currently participating in the replication of the specified replicated folder, then the server MUST fail the call with an implementation-defined failure value.

  • If the specified replicated folder is read-only (see the msDFSR-ReadOnly attribute specified in section 2.3.3) then the server MUST fail the call with the FRS_ERROR_CONTENTSET_READ_ONLY failure value.

  • If the specified replicated folder is disabled (see the msDFSR-Enabled attribute specified in section 2.3.3) then the server MUST fail the call with an implementation-defined failure value.

Actions Triggered: Upon successfully validating the session request, the server establishes a replicated folder session for the specified replicated folder with the client.

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