188.8.131.52.3 EstablishSession (Opnum 2)
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 );
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.
The method completed successfully.
The connection is invalid.
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.