LOCK Method
Topic Last Modified: 2006-06-13
The WebDAV LOCK method is used to take out a lock of any access type on a resource so that another principal will not modify the resource while it is being edited. The LOCK method may also be used to initiate transactions, which allow clients to define groups of operations that are performed atomically.
Write Locks
A write lock will prevent a principal without the lock from executing a PROPPATCH Method, a LOCK method, an UNLOCK Method, a MOVE Method, a DELETE Method, or a MKCOL Method on a locked resource. A write lock is specified by the write XML Element within the locktype XML Element of the XML request body.
The most basic form of a write lock is an exclusive lock, where the access right to a resource is only granted to a single principal. An exclusive lock is specified by the exclusive XML Element within the lockscope XML Element of the XML request body.
Shared locks allow multiple principals to receive a lock on a resource and therefore may be used to limit access to a resource to a certain set of principals. A shared lock is specified by a shared XML Element within the lockscope XML Element of the XML request body.
A successful request for an exclusive or shared lock will result in the generation of a unique lock token associated with the requesting principal. If five principals request a shared lock on a resource, then five lock tokens will be generated, one for each principal. The generated lock token is returned in the locktoken XML Element of the LOCK method response.
A Timeout Header may be used with a LOCK method request to specify when the lock will expire.
The Depth Header with a value of "0" or "Infinity" may be used with a LOCK method request. A Depth Header with a value of "0" will lock only the resource specified in the request Uniform Resource Identifier (URI). A Depth Header with a value of "Infinity" will lock the resource specified in the request URI along with all of the internal members of the resource. If no Depth Header is specified, then the default is "Infinity."
An exclusive or shared lock cannot be created within the scope of a transaction and an attempt to do so will make the method fail.
Using the IF Header with a Lock Token
If a principal has put a write lock on a resource and wants to perform a write method on that resource, then the associated lock token must be submitted with the method request. This is done by including the lock token in the If Header of the method request.
Refreshing Locks
A client cannot submit the same lock request twice; however, a client may refresh an existing lock. This is done by submitting a LOCK method without an XML body and including the lock token of the associated lock in the If Header of the method request. This will reset the lifetime of the lock. A Timeout Header may also be submitted to specify the lifetime of the refreshed lock.
Lock Capability Discovery
Lock capability discovery is the process of determining what lock types the server supports by retrieving the supportedlock Field. This may be done using the PROPFIND Method.
Active Lock Discovery
If a principal locks a resource that another principal wants to use, then it may be useful for the second principal to determine who placed the lock on the resource. This may be done by retrieving the lockdiscovery Field with the PROPFIND Method. The lockdiscovery Field lists all active locks currently in place on the resource, describes their type, and when available, provides their lock token.
Transactions
A transaction is defined as a set of independent operations that are performed as an atomic operation. The LOCK method is used to initiate a transaction but does not necessarily mean that a write lock is being set on the involved resources.
There are several new XML elements relevant to transactions that must be used in the XML body of the method request: the local XML Element, and the transaction XML Element. The following is an example of a XML request body of a LOCK method used to initiate a transaction:
<?xml version="1.0" ?>
<D:lockinfo xmlns:D="DAV:">
<D:lockscope><D:local/></D:lockscope>
<D:locktype>
<D:transaction><D:groupoperation/></D:transaction>
</D:locktype>
<D:owner>
<D:href>https://www.contoso.com/public/contact.html</D:href>
</D:owner>
</D:lockinfo>
Upon successful execution of a LOCK method with a lock type of "transaction", the server will return a lock token in the locktoken XML Element which identifies the transaction. This lock token may then be used in the Transaction Header of subsequent WebDAV method requests to make them a part of the transaction. Note that it is possible to issue other WebDAV method requests without the Transaction Header. These method requests would not fall within the scope of a transaction. On completion of the transaction, the UNLOCK Method is used to either commit or abort the transaction.
Only transactions of Depth: 0 are allowed. If a Depth Header is submitted with the LOCK method, it may only have a value of 0.
The Timeout Header may be submitted by the client with the LOCK method, specifying the amount of time until the transaction expires. The server may honor this request or return another timeout in the XML body of the response.
Refreshing Transactions
Refreshing a transaction is exactly like refreshing a standard lock, where the lock token used in the If Header identifies a transaction, not a write lock.
Note
See Authentication and Security Using WebDAV for more information.
The list of WebDAV Protocol Status Codes in the following table is not comprehensive. For information about 500-level status codes, see WebDAV Status Codes: 500s.
Status Codes
| Status Code | Meaning |
|---|---|
200 (OK) |
The lock request succeeded and the value of the lockdiscovery Field is included in the response body. |
201 (Created) |
If you do a LOCK on a null resource, the LOCK will create the resource. |
207 (Multi-Status) |
Used with a multiresource lock request. |
400 (Bad Request) |
A group operation (transaction) of Depth: 1 or Depth: Infinity was attempted. |
403 (Forbidden) |
The client does not have permission to lock the resource. |
412 (Precondition Failed) |
The lock token was not enforceable on the resource or the server could not satisfy the request. |
422 (Unprocessable Entity) |
Non-zero depth was specified for a check-out lock, or the Depth Header was omitted. |
423 (Locked) |
The destination resource is locked and the operation was rejected, or nested transactions are not supported on the server. |
Example
The following example illustrates a successful creation of an exclusive write lock using the WebDAV LOCK method on resource https://www.contoso.com/~user/index.htm. Note in the response that the server has a time-out policy in place that will cause the lock to be automatically lifted after 4 days (345600 seconds).
The following example illustrates a lock being successfully refreshed. Note that the client requested an infinite time out but that the server chose to ignore it.
The following example illustrates a transaction being initiated.
Request
LOCK /docs/myfile.doc HTTP/1.1
Host: www.contoso.com
Timeout: Infinite, Second-4100000000
Content-Type: text/xml; charset="utf-8"
Content-Length: XXXX
Authorization: Digest username="user",
realm="user@contoso.com", nonce="...",
uri="/docs/myfile.doc",
response="...", opaque="..."
<?xml version="1.0" encoding="utf-8" ?>
<d:lockinfo xmlns:d="DAV:">
<d:lockscope><d:exclusive/></d:lockscope>
<d:locktype><d:write/></d:locktype>
<d:owner>
<d:href>https://www.contoso.com/~user/contact.htm</d:href>
</d:owner>
</d:lockinfo>
Response
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: XXXX
<?xml version="1.0" encoding="utf-8" ?>
<d:prop xmlns:d="DAV:">
<d:lockdiscovery>
<d:activelock>
<d:locktype><d:write/></d:locktype>
<d:lockscope><d:exclusive/></d:lockscope>
<d:depth>Infinity</d:depth>
<d:owner>
<d:href>https://www.contoso.com/~user/contact.htm</d:href>
</d:owner>
<d:timeout>Second-345600</d:timeout>
<d:locktoken>
<d:href>opaquelocktoken:e71d4fae-5dec-22df-fea5-00a0c93bd5eb1</d:href>
</d:locktoken>
</d:activelock>
</d:lockdiscovery>
</d:prop>
Request
LOCK /public/docs/myfile.doc HTTP/1.1
Host: www.contoso.com
Timeout: Infinite, Second-4100000000
If: (<opaquelocktoken:e71df4fae-5dec-22d6-fea5-00a0c91e6be4>)
Authorization: Digest username="user",
realm="user@contoso.com", nonce="...",
uri="/public/docs/myfile.doc",
response="...", opaque="..."
Response
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: XXXX
<?xml version="1.0" encoding="utf-8" ?>
<d:prop xmlns:d="DAV:">
<d:lockdiscovery>
<d:activelock>
<d:locktype><d:write/></d:locktype>
<d:lockscope><d:exclusive/></d:lockscope>
<d:depth>Infinity</d:depth>
<d:owner>
<d:href>https://www.contoso.com/~user/contact.htm</d:href>
</d:owner>
<d:timeout>Second-604800</d:timeout>
<d:locktoken>
<d:href>opaquelocktoken:e71df4fae-5dec-22d6-fea5-00a0c91e6be4</d:href>
</d:locktoken>
</d:activelock>
</d:lockdiscovery>
</d:prop>
Request
LOCK /public/workspace/ HTTP/1.1
Host: www.contoso.com
Timeout: Second-100
Depth: 0
Content-Type: text/xml
Translate: f
<?xml version="1.0" ?>
<d:lockinfo xmlns:d="DAV:">
<d:lockscope><d:local/></d:lockscope>
<d:locktype>
<d:transaction><d:groupoperation/></d:transaction>
</d:locktype>
<d:owner>
<d:href>https://www.contoso.com/public/contact.html</d:href>
</d:owner>
</D:lockinfo>
Response
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: XXXX
<?xml version="1.0" encoding="utf-8" ?>
<d:prop xmlns:d="DAV:">
<d:lockdiscovery>
<d:activelock>
<d:locktype>
<d:transaction><d:groupoperation/></d:transaction>
</d:locktype>
<d:lockscope><d:local/></d:lockscope>
<d:depth>0</d:depth>
<d:owner>
<d:href>https://www.contoso.com/public/contact.html</d:href>
</d:owner>
<d:timeout>Second-604800</d:timeout>
<d:locktoken>
<d:href>opaquelocktoken:e71df4fae-5dec-22d6-fea5-00a0c91e6be4</d:href>
</d:locktoken>
</d:activelock>
</d:lockdiscovery>
</d:prop>