AGPL-3.0 License
Files Lock allows your users to temporary lock a file to avoid other users' edits. By default, files locked using this app will be locked indefinitely.
Administrators can change the time of the maximum lock time in minutes (30) using the command:
./occ config:app:set --value '30' files_lock lock_timeout
Locks have no expiry by default.
Administrators can also lock files using the ./occ
command:
./occ files:lock <fileId> [<lockOwner>] [--status] [--unlock]
Locks are separated into three different types:
X-User-Lock
header for WebDAV requests, but in that case the server will not be able to validate the lock ownership when unlocking the file from the client.If locking is available the app will expose itself through the capabilties endpoint under the files key:
Make sure to validate that also the key exists in the capabilities response, not just check the value as on older versions the entry might be missing completely.
curl http://admin:[email protected]/ocs/v1.php/cloud/capabilities\?format\=json \
-H 'OCS-APIRequest: true' \
| jq .ocs.data.capabilities.files
{
...
"locking": "1.0",
"api-feature-lock-type" => true,
...
}
locking
: The version of the locking APIapi-feature-lock-type
: Feature flag, whether the server supports the lockType
parameter for the OCS API or X-User-Lock-Type
header for WebDAV requests.WebDAV returns the following additional properties if requests through a PROPFIND
:
{http://nextcloud.org/ns}lock
: true
if the file is locked, otherwise false
{http://nextcloud.org/ns}lock-owner-type
: User id of the lock owner
0
represents a manual lock by a user1
represents a collaboratively locked file, e.g. when being edited through Office or Text2
represents a WebDAV lock identified by a lock token, which will have the other properties set as if it was type 0{http://nextcloud.org/ns}lock-owner
: User id of the lock owner{http://nextcloud.org/ns}lock-owner-displayname
: Display name of the lock owner{http://nextcloud.org/ns}lock-owner-editor
: App id of an app owned lock to allow clients to suggest joining the collaborative editing session through the web or direct editing{http://nextcloud.org/ns}lock-time
: Timestamp of the log creation time{http://nextcloud.org/ns}lock-timeout
: TTL of the lock in seconds staring from the creation time. a value of 0 means the timeout is infinite. client implementations should properly handle this specific value{http://nextcloud.org/ns}lock-token
: Unique lock token (to be preserved on the client side while holding the lock to sent once full webdav locking is implemented)curl -X PROPFIND \
--url http://admin:[email protected]/remote.php/dav/files/admin/myfile.odt \
--data '<D:propfind xmlns:D="DAV:" xmlns:NC="http://nextcloud.org/ns">
<D:prop>
<NC:lock />
<NC:lock-owner-type />
<NC:lock-owner />
<NC:lock-owner-displayname />
<NC:lock-owner-editor />
<NC:lock-time />
</D:prop>
</D:propfind>'
curl -X LOCK \
--url http://admin:[email protected]/remote.php/dav/files/admin/myfile.odt \
--header 'X-User-Lock: 1'
X-User-Lock
: Indicate that locking shall ignore token requirements that the WebDAV standard required.X-User-Lock-Type
: The type of the lock (see description above)The response will give back the updated properties after obtaining the lock with a 200 Success
status code or the existing lock details in case of a 423 Locked
status.
<?xml version="1.0"?>
<d:prop
xmlns:d="DAV:"
xmlns:s="http://sabredav.org/ns"
xmlns:oc="http://owncloud.org/ns"
xmlns:nc="http://nextcloud.org/ns">
<nc:lock>1</nc:lock>
<nc:lock-owner-type>0</nc:lock-owner-type>
<nc:lock-owner>user1</nc:lock-owner>
<nc:lock-owner-displayname>user1</nc:lock-owner-displayname>
<nc:lock-owner-editor>user1</nc:lock-owner-editor>
<nc:lock-time>1648046707</nc:lock-time>
</d:prop>
curl -X UNLOCK \
--url http://admin:[email protected]/remote.php/dav/files/admin/myfile.odt \
--header 'X-User-Lock: 1'
X-User-Lock
: Indicate that locking shall ignore token requirements that the WebDAV standard required.X-User-Lock-Type
: The type of the lock (see description above)<?xml version="1.0"?>
<d:prop
xmlns:d="DAV:"
xmlns:s="http://sabredav.org/ns"
xmlns:oc="http://owncloud.org/ns"
xmlns:nc="http://nextcloud.org/ns">
<nc:lock></nc:lock>
<nc:lock-owner-type/>
<nc:lock-owner/>
<nc:lock-owner-displayname/>
<nc:lock-owner-editor/>
<nc:lock-time/>
</d:prop>
PUT /apps/files_lock/lock/{fileId}
curl -X PUT 'http://admin:[email protected]/ocs/v2.php/apps/files_lock/lock/123' -H 'OCS-APIREQUEST: true'`
lockType
(optional): The type of the lock. Defaults to 0
(user owned manual lock). Possible values are:
0
: User owned manual lock1
: App owned lock2
: Token owned lock<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>200</statuscode>
<message>OK</message>
</meta>
</ocs>
<?xml version="1.0"?>
<ocs>
<meta>
<status>failure</status>
<statuscode>500</statuscode>
<message/>
</meta>
<data>
<status>-1</status>
<exception>OCA\FilesLock\Exceptions\AlreadyLockedException</exception>
<message>File is already locked by admin</message>
</data>
</ocs>
DELETE /apps/files_lock/lock/{fileId}
curl -X DELETE 'http://admin:[email protected]/ocs/v2.php/apps/files_lock/lock/123' -H 'OCS-APIREQUEST: true'
lockType
(optional): The type of the lock. Defaults to 0
(user owned manual lock). Possible values are:
0
: User owned manual lock1
: App owned lock2
: Token owned lock<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>200</statuscode>
<message>OK</message>
</meta>
</ocs>
<?xml version="1.0"?>
<ocs>
<meta>
<status>failure</status>
<statuscode>500</statuscode>
<message/>
</meta>
<data>
<status>-1</status>
<exception>OCA\FilesLock\Exceptions\LockNotFoundException</exception>
<message></message>
</data>
</ocs>