GetLock

POST /wopi/files/(file_id)

The GetLock operation retrieves a lock on a file. Note that this operation does not create a new lock. Rather, this operation always returns the current lock value in the X-WOPI-Lock response header. Because of this, its semantics differ slightly from the other lock-related operations.

If the file is currently not locked, the host must return a 200 OK and include an X-WOPI-Lock response header set to the empty string.

If the file is currently locked, the host should return a 200 OK and include an X-WOPI-Lock response header containing the value of the current lock on the file. If the current lock ID is not representable as a WOPI lock (for example, it is longer than the maximum lock length), the host should return a 409 Conflict and set the X-WOPI-Lock response header to the empty string or omit it completely.

Tip

While a 409 Conflict is technically a valid response to this operation, it is rarely needed in practice, and hosts should respond with a 200 OK in most cases.

See Lock for more general information regarding locks.

Parameters

  • file_id (string) – A string that specifies a file ID of a file managed by host. This string must be URL safe.

Query Parameters

  • access_token (string) – An access token that the host will use to determine whether the request is authorized.

Request Headers

  • X-WOPI-Override – The string GET_LOCK. Required.

Response Headers

  • X-WOPI-Lock – A string value identifying the current lock on the file. Unlike other lock operations, this header is required when responding to the request with either 200 OK or 409 Conflict.

  • X-WOPI-LockFailureReason – An optional string value indicating the cause of a lock failure. This header may be included when responding to the request with 409 Conflict. There is no standard for how this string is formatted, and it must only be used for logging purposes.

  • X-WOPI-LockedByOtherInterface –

    Deprecated since version 2015-12-15: This header is deprecated and should be ignored by WOPI clients.

Status Codes

  • 200 OK – Success; an X-WOPI-Lock response header containing the value of the current lock on the file must always be included when using this response code

  • 401 Unauthorized – Invalid access token

  • 404 Not Found – Resource not found/user unauthorized

  • 409 Conflict – Lock mismatch/locked by another interface; an X-WOPI-Lock response header containing the value of the current lock on the file must always be included when using this response code

  • 500 Internal Server Error – Server error

  • 501 Not Implemented – Operation not supported

See also

Standard WOPI request and response headers

In addition to the request/response headers listed here, this operation may also use the Standard WOPI request and response headers.