LOCK Method

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.

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.

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 is the process of determining what lock types the server supports by retrieving the supportedlock Field. This may be done using the PROPFIND Method.

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.

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:

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.

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>

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>

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="..."

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>

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>

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>