3.1.4.3 Coauth Subrequest

  • Article

This operation is used to make a request to the protocol server for a shared lock on the file or for shared lock operations on a file. A protocol server that supports a coauthoring subrequest MUST also support tracking the coauthoring transition. Depending on the CoauthRequestType attribute value, the protocol server interprets the subrequest as one of the following types of shared lock operations:

  • Join coauthoring session

  • Exit coauthoring session

  • Refresh coauthoring session

  • Convert to exclusive lock

  • Check lock availability

  • Mark transition to complete

  • Get coauthoring status

The CoauthRequestType attribute is defined in section 2.3.3.3. The CoauthRequestType attribute is one of the attributes for the coauthoring SubRequestData element, which is of type CoauthSubRequestDataType as specified in section 2.3.1.5.

The protocol client sends a coauthoring SubRequest message, which is of type CoauthSubRequestType as specified in section 2.3.1.6. The protocol server responds with a coauthoring SubResponse message, which is of type CoauthSubResponseType as specified in section 2.3.1.8. This is done as follows:

  • The protocol client prepares a request containing a URL for the file, a unique Request token, and one or more SubRequest elements, as defined in section 2.2.3.2 and section 2.2.3.8. The SubRequest element is of type "Coauth", and the SubRequestData element contains attributes that are input parameters used by the server when processing the coauthoring subrequest. The SubRequestData element is of type CoauthSubRequestDataType and is defined in section 2.3.1.5.

  • The protocol server receives the request and parses the logic. Depending on the type of coauthoring request, the protocol server processes the subrequest as specified in section 3.1.4.3.1, 3.1.4.3.2, 3.1.4.3.3, 3.1.4.3.4, 3.1.4.3.5, 3.1.4.3.6, or 3.1.4.3.7. The protocol server uses the ClientID attribute sent in a coauthoring subrequest to do the following:

    • Uniquely identify each client

    • Keep track of each client and its timeout on the shared lock for the file

    • Decide when to release the shared lock on the file

  • The Response element is defined in section 2.2.3.5, and the SubResponse element is defined in section 2.2.3.10. CoauthSubResponseDataType defines the type of the SubResponseData element inside the coauthoring SubResponse element. CoauthSubResponseDataType is defined in section 2.3.1.7.

  • If the coauthoring subrequest is of type "Join coauthoring session" or "Refresh coauthoring session", the protocol server MUST return the lock type granted to the protocol client as part of the response message to  the protocol client—if  the ErrorCode attribute that is part of the SubResponse element is set to a value of "Success". The lock type is specified in the LockType attribute in the coauthoring SubResponseData element. The SubResponseData element returned for a coauthoring subrequest is of type CoauthSubResponseDataType and is defined in section 2.3.1.7. The LockType attribute is specified in section 2.3.1.7.

  • The protocol server returns results based on the following conditions:

    • Depending on the type of error, ErrorCode is returned as an attribute of the SubResponse element. The ErrorCode attribute that is part of the SubResponse element is updated with a specific error code as specified in section 2.2.5.4.

    • If the protocol server was unable to find the URL for the file specified in the Url attribute, the protocol server reports a failure by returning an error code value set to "FileNotExistsOrCannotBeCreated" in the ErrorCode attribute sent back in the SubResponse element.

    • The protocol server returns an error code value set to "CoauthRefblobConcurrencyViolation" when there is a concurrency violation and the coauthoring subrequest is one of the following types:

      • Join coauthoring session

      • Exit coauthoring session

      • Refresh coauthoring session

      • Convert to an exclusive lock

      • Mark in transition complete

    • A concurrency violation happens when a current client’s request to save the file coauthoring tracker fails because another client’s request to edit and save the file coauthoring tracker is in progress on the server before the save is done by the current client. "CoauthRefblobConcurrencyViolation" is specified in section 2.2.5.8. The file coauthoring tracker is defined in section 3.1.1.

    • The protocol server returns an error code value set to "RequestNotSupported" if the server does not support this request type.

    • An ErrorCode value of "Success" indicates success in processing the coauthoring request.