UnlockAndRelock
The UnlockAndRelock operation releases a lock on a file, and then immediately places a new lock on the file.
POST /wopi/files/(file_id)
The UnlockAndRelock operation releases a lock on a file, and then immediately places a new lock on the file.
Important
This operation must be atomic.
UnlockAndRelock is similar semantically to the Lock operation. The two operations share the same X-WOPI-Override value. So, hosts must differentiate the two operations based on the presence, or lack of, the X-WOPI-OldLock request header.
Unlike the Lock operation, the UnlockAndRelock operation passes the current expected lock ID in the X-WOPI-OldLock request header. The X-WOPI-Lock value is the lock ID for the new lock.
If the file is currently locked and the X-WOPI-OldLock value doesn't match the lock currently on the file, or if the file is unlocked, the host must:
- Return a lock mismatch response (409 Conflict)
- Include an X-WOPI-Lock response header containing the value of the current lock on the file
In cases where the file is unlocked, the host must set X-WOPI-Lock to the empty string.
In cases where the file is locked by someone other than a WOPI client, hosts should still always include the current lock ID in the X-WOPI-Lock response header. However, if the current lock ID isn't representable as a WOPI lock (for example, it's longer than the maximum lock length), you should set the X-WOPI-Lock response header to the empty string or omitted completely.
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
LOCK. Required.X-WOPI-Lock – A string provided by the WOPI client that the host must use to identify the new lock on the file. The maximum length of a lock ID is 1024 ASCII characters. Required.
X-WOPI-OldLock – A string provided by the WOPI client that is the existing lock on the file. Required. If X-WOPI-OldLock is not provided, the request is identical to a Lock request.
Response headers
X-WOPI-Lock – A string value identifying the current lock on the file. This header must always be included when responding to the request with 409 Conflict. It should not be included when responding to the request with 200 OK.
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.
400 Bad Request – X-WOPI-Lock was not provided or was empty.
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.