GetLock
The GetLock operation retrieves a lock on a file.
POST /wopi/files/(file_id)
The GetLock operation retrieves a lock on a file. This operation doesn't create a new lock. Rather, it always returns the current lock value in the X-WOPI-Lock response header. Because of this, this operation's semantics differ slightly from the other lock-related operations.
If the file is currently unlocked, 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 isn't representable as a WOPI lock (for example, it's 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's rarely needed in practice, and hosts should respond with a 200 OK in most cases.
For more general information about locks, see Lock.
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 uses to determine whether the request is authorized.
Request headers
- X-WOPI-Override – The string
GET_LOCK. This string is 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 might be included when responding to the request with 409 Conflict. There's no standard for how this string is formatted, and it must only be used for logging purposes.
X-WOPI-LockedByOtherInterface – Deprecated: Deprecated since version 2015-12-15: This header is deprecated and should be ignored by WOPI clients.
Status codes
200 OK – Success. You must include an X-WOPI-Lock response header containing the value of the current lock on the file when using this response code.
401 Unauthorized – Invalid access token
404 Not Found – Resource not found/user unauthorized.
409 Conflict – Lock mismatch or locked by another interface. You must include an X-WOPI-Lock response header containing the value of the current lock on the file when using this response code.
500 Internal Server Error – Server error.
501 Not Implemented – Operation not supported.
In addition to the request and response headers listed here, this operation might also use the Standard WOPI request and response headers. For more information see Standard WOPI request and response headers.