3.1.4.5 ExclusiveLock Subrequest

  • Article

This operation is used to request an exclusive lock on the file or different types of exclusive lock operations on a file from the protocol server. Depending on the ExclusiveLockRequestType attribute value, the protocol server interprets the request as one of the following types of lock operations:

  • Get lock

  • Release lock

  • Refresh lock

  • Convert to schema lock with coauthoring transition tracked

  • Convert to schema lock

  • Check lock availability

The ExclusiveLockRequestType attribute is defined in section 2.3.3.4. The SubRequestData element for an exclusive lock subrequest is of type ExclusiveLockSubRequestDataType and is defined in section 2.3.1.9.

The protocol client sends an exclusive lock SubRequest message, which is of type ExclusiveLockSubRequestType as specified in section 2.3.1.10. The protocol server responds with an exclusive lock SubResponse message, which is of type ExclusiveLockSubResponseType as specified in section 2.3.1.12. 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 "ExclusiveLock" and the SubRequestData element contains attributes that are input parameters used by the protocol server when processing the exclusive lock subrequest. The SubRequestData element is of type ExclusiveLockSubRequestDataType and is defined in section 2.3.1.9.

  • The protocol server receives the request, parses the logic, and depending on the type of exclusive lock subrequest, processes the request as specified in section 3.1.4.5.1, 3.1.4.5.2, 3.1.4.5.3, 3.1.4.5.4, 3.1.4.5.5, or 3.1.4.5.6.

  • The Response element is defined in section 2.2.3.5, and the SubResponse element is defined in section 2.2.3.10. The ExclusiveLockSubResponseDataType defines the type of the SubResponseData element inside the exclusive lock SubResponse element. The ExclusiveLockSubResponseDataType is defined in section 2.3.1.11.

  • The protocol returns results based on the following conditions:

    • Depending on the type of error, the 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 "LockRequestFail" or "Unknown" or "FileNotExistsOrCannotBeCreated" in the ErrorCode attribute sent back in the SubResponse element.

    • If the protocol server gets an exclusive lock subrequest of type "Convert to schema lock with coauthoring transition tracked" or "Convert to schema lock" for a file, and the conversion fails because the file is checked out by the current client, the protocol server returns an error code value set to "ConvertToSchemaFailedFileCheckedOutByCurrentUser".

    • 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 "CoauthRefblobConcurrencyViolation" when there is a concurrency violation and the exclusive lock subrequest is one of the following types:

      • Convert to schema lock with coauthoring transition tracked

      • Convert to schema lock

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