Share via

3.1.4.3.1 Join Coauthoring Session

  • Article

If the CoauthRequestType attribute is set to "JoinCoauthoring", the protocol server considers the coauthoring subrequest to be of type "Join coauthoring session". The protocol server processes this request to get a shared lock on the coauthorable file and joins the coauthoring session of the file by adding the client’s associated ClientID and timeout to the file coauthoring tracker. The protocol server also checks and gets the coauthoring status of the file.

If the file already has a shared lock on the server with the given schema lock identifier, and the client has already joined the coauthoring session, the protocol server does both of the following:

  • Refreshes the timeout value associated with the ClientID in the file coauthoring tracker.

  • Returns an error code value set to "Success".

If the coauthoring feature is disabled on the protocol server, it does one of the following:

  • If the AllowFallbackToExclusive attribute is set to true, the protocol server gets an exclusive lock on the file.

  • If the AllowFallbackToExclusive attribute is set to false, the protocol server returns an error code value set to "FileNotLockedOnServer".<43>

The AllowFallbackToExclusive attribute is defined in section 2.3.1.5. The result of the lock type gotten by the server MUST be sent as the LockType attribute in the CoauthSubResponseDataType. The CoauthSubResponseDataType is defined in section 2.3.1.7. LockType attribute values are defined in section 2.2.5.9.

To get the coauthoring status, the protocol server checks the number of clients editing the file at that instant in time. If the current client is the only client editing the file, the protocol server MUST return a CoauthStatus set to "Alone", which indicates that no one else is editing the file. If the current client is the second, third, or later coauthor joining the coauthoring session, the protocol server MUST return a CoauthStatus set to "Coauthoring", which indicates that the current client is coauthoring when editing the document. A CoauthStatus of "None" can be returned in situations where coauthoring is not achieved because an exclusive lock is returned instead of a shared lock. This can happen when 1. the file is checked out by the current user or 2. an exclusive lock is held by the current user or 3. the coauthoring feature is disabled and the AllowFallbackToExclusive attribute is set to true on the request. The CoauthStatus attribute sent as part of the SubResponseData element is defined in section 2.2.8.2.

If the current client is the second client to join the coauthoring session, the server creates a new transition request by using the TransitionID attribute for the file. TransitionID is defined in section 2.3.1.7. Since there is a transition request present for the file, when the first client that was added to the coauthoring session makes the IsOnlyClient web service request, the server returns "false". The descriptions of the transition request and the IsOnlyClient web service request are as specified in [MS-SHDACCWS]. This sequence of subrequests is described in the figure in section 3.1.4.3.6.

If there is a current exclusive lock on the file or a shared lock on the file with a different schema lock identifier, the protocol server returns an error code value set to "FileAlreadyLockedOnServer". If the coauthorable file is checked out on the server and checked out by a client with a different user name than the current client, the protocol server returns an error code value set to "FileAlreadyCheckedOutOnServer".

The protocol server returns an error code value set to "NumberOfCoauthorsReachedMax" when all of the following conditions are true:

  • The maximum number of coauthorable clients allowed to join a coauthoring session to edit a coauthorable file has been reached.

  • The current client is not allowed to edit the file because the limit has been reached.

If any failure occurs such that the subrequest cannot be processed successfully, the protocol server returns an error. The error that the protocol server returns is implementation-specific. Errors that are directly returned by the protocol server are implementation-specific. LockAndCoauthRelatedErrorCodeTypes is defined in section 2.2.5.8, and generic error code types are defined in section 2.2.5.6. For other unknown error types, the protocol server returns an error code value set to "LockRequestFail".