8.5 Lock-Related Properties

The properties described here are available on a resource only if locking is supported.

8.5.1 lockdiscovery

Clients need some way of discovering what locks exist on a resource, if any, and the lockdiscovery property serves that purpose. Since a resource may have several locks, the lockdiscovery value may have several components. The information about a single lock includes several more pieces of information, including the client-provided owner value that might be expressed in XML. Thus, lockdiscovery is a multivalued XML-formatted property.

Every lock on the resource shows up as an additional activelock XML element in the value of the lockdiscovery property. Each activelock element contains a set of XML tags with information about the lock:

• locktype: Describes the type of lock (write lock being the only standard type).

• lockscope: Describes whether the lock is exclusive or shared.

• depth: Does the lock apply only to this resource (0) or to its descendants as well (Infinity)?

• owner: A client-provided string or XML fragment intended to contain information to help users get in touch with the lock's creator (e.g., to ask them to unlock it), possibly as well as information about the client software that created the lock.

• timeout: The time remaining on the lock (or Infinite).

• locktoken: This must be provided in case the client software loses the token.

This example builds on the first LOCK response in this chapter, Listing 8-2. Some time has passed since that response, so the timeout shows the countdown or time remaining on the lock lifetime. This property value would normally appear inside a PROPFIND response (see Listing 8-14).

Listing 8-14 Example lockdiscovery property value.

 <lockdiscovery xmlns="DAV:">    <activelock>       <locktype><D:write/></locktype>       <lockscope><D:exclusive/></lockscope>       <depth>infinity</depth>       <owner xmlns:x="http://www.customapp.com/ns/">          <x:lock-user>[e-mail]</x:lock-user>          <x:created-by>Text Editor v1.2.5</x:created-by>       </owner>       <timeout>Second-604625</timeout>       <locktoken><href>opaquelocktoken:e71d4fae-5dec-22d6              -fea5-00a0c91e6be4</href></locktoken>    </activelock> </lockdiscovery> 

8.5.2 supportedlock

The supportedlock property returns an XML-formatted listing of the kinds of locks that may be created on this resource. Sometimes this information applies to the whole server, and the value returned by this property is always the same. An implementation could allow different kinds of locks depending on the kind of resource. For example, collections might only support exclusive locks, while ordinary resources support both exclusive and shared locks. Most WebDAV servers will return a consistent value much like the example in Listing 8-15, indicating that both exclusive and shared write locks are supported on all resources, as required by WebDAV.

Listing 8-15 Example supportedlock property value.

 <D:supportedlock>    <D:lockentry>       <D:lockscope><D:exclusive/></D:lockscope>       <D:locktype><D:write/></D:locktype>    </D:lockentry>    <D:lockentry>       <D:lockscope><D:shared/></D:lockscope>       <D:locktype><D:write/></D:locktype>    </D:lockentry> </D:supportedlock> 

Bug in supportedlock

An early version of the WebDAV RFC omitted the lockscope and locktype elements in its example value for the supportedlock property.

 <D:supportedlock> <D:lockentry><D:exclusive/><D:write/></D:lockentry> <D:lockentry><D:shared/><D:write/></D:lockentry> </D:supportedlock> 

Microsoft IIS 5.0 implemented the property based on the example, not on the defining text, so the implementation perpetuated the specification's error for several years. The property value is still useful if special client code detects this case.