Share via

3.1.4.5.4 Convert to Schema Lock with Coauthoring Transition Tracked

  • Article

If the ExclusiveLockRequestType attribute is set to "ConvertToSchemaJoinCoauth", the protocol server considers this exclusive lock subrequest to be of type "Convert to schema lock with coauthoring transition tracked". When the protocol server receives this subrequest, it does all of the following:

  • Converts the exclusive lock on the file to a shared lock.

  • Starts a coauthoring session for the file if one is not already present and adds the client to that session.

After the request to convert the exclusive lock to a shared lock is processed successfully, the protocol server gets the coauthoring status and returns the status to the client.

The protocol server uses the ClientID attribute sent in an exclusive lock subrequest of type "Convert to schema lock with coauthoring transition tracked" to uniquely identify each client and keep track of each client and its timeout on the shared lock for the file. The protocol server also uses the ClientID sent in the exclusive lock subrequest to decide when to release the shared lock on the file. The protocol server uses the SchemaLockID attribute sent in an exclusive lock subrequest of type "Convert to schema lock with coauthoring transition tracked" to ensure that after the exclusive lock on the file is converted to a shared lock, the protocol server MUST allow only other clients with the same schema lock identifier to share the lock on the file. The SchemaLockID and ClientID attributes are defined in section 2.3.1.9.

The protocol server returns error codes according to the following rules:

  • If the feature of transitioning a file that currently has an exclusive lock to one that has a shared lock is not supported by the protocol server, the protocol server returns an error code value set to "RequestNotSupported".

  • If the coauthoring feature is disabled by the protocol server, the protocol server returns an error code value set to "LockNotConvertedAsCoauthDisabled".

  • If the protocol server is unable to convert the exclusive lock to a shared lock on the file because the file is checked out by the current user, the protocol server returns an error code value set to "ConvertToSchemaFailedFileCheckedOutByCurrentUser".

  • If the protocol server is unable to convert the lock because either there is an exclusive lock with a different exclusive lock identifier or there is a shared lock already present on the file, the protocol server returns an error code value set to "FileAlreadyLockedOnServer".

  • If the protocol server is unable to convert the lock on the file because no lock exists on the server, the protocol server returns an error code value set to "FileNotLockedOnServer".

  • If the protocol server is unable to convert the lock because the document is saved to a document library that requires checking out files and the document is not checked out on the server, the protocol server returns an error code value set to "DocumentCheckoutRequired". The "DocumentCheckoutRequired" error code value indicates to the protocol client that a checkout needs to be done before the exclusive lock is converted to a shared lock. The checkout of the file is done by the client using the CheckoutFile web service call as specified in [MS-LISTSWS].

  • If the protocol server encounters unknown exceptions or failures when converting the lock on the file, the protocol server returns an error code value set to "LockRequestFail".

To get the coauthoring status, the protocol server checks the number of clients editing the document at that instant in time. If the current client is the only client editing the file, the protocol server MUST return a CoauthStatus attribute set to "Alone", which indicates that no one else is editing the file. If the current client is not the only client editing the document, the protocol server MUST return a CoauthStatus attribute set to "Coauthoring", which indicates that the current client is coauthoring when editing the document. The "Coauthoring" status is possible because the operations of converting the exclusive lock on the file to a shared lock and then adding the client to the coauthoring session are not executed atomically, and another client could add itself to the coauthoring session after the lock was converted but before the current client was added to the session. The CoauthStatus attribute is sent as part of the SubResponseData element and is defined in section 2.2.8.2.

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. GenericErrorCodeTypes is defined in section 2.2.5.6. DependencyCheckRelatedErrorCodeTypes is defined in section 2.2.5.2. LockAndCoauthRelatedErrorCodeTypes is defined in section 2.2.5.8.