Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 4918

HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)

Pages: 127
Proposed Standard
Errata
Obsoletes:  2518
Updated by:  5689
Part 4 of 5 – Pages 77 to 102
First   Prev   Next

Top   ToC   RFC4918 - Page 77   prevText

10.5. Lock-Token Header

Lock-Token = "Lock-Token" ":" Coded-URL The Lock-Token request header is used with the UNLOCK method to identify the lock to be removed. The lock token in the Lock-Token request header MUST identify a lock that contains the resource identified by Request-URI as a member. The Lock-Token response header is used with the LOCK method to indicate the lock token created as a result of a successful LOCK request to create a new lock.

10.6. Overwrite Header

Overwrite = "Overwrite" ":" ("T" | "F") The Overwrite request header specifies whether the server should overwrite a resource mapped to the destination URL during a COPY or MOVE. A value of "F" states that the server must not perform the COPY or MOVE operation if the destination URL does map to a resource. If the overwrite header is not included in a COPY or MOVE request, then the resource MUST treat the request as if it has an overwrite header of value "T". While the Overwrite header appears to duplicate the functionality of using an "If-Match: *" header (see [RFC2616]), If-Match applies only to the Request-URI, and not to the Destination of a COPY or MOVE. If a COPY or MOVE is not performed due to the value of the Overwrite header, the method MUST fail with a 412 (Precondition Failed) status code. The server MUST do authorization checks before checking this or any conditional header. All DAV-compliant resources MUST support the Overwrite header.
Top   ToC   RFC4918 - Page 78

10.7. Timeout Request Header

TimeOut = "Timeout" ":" 1#TimeType TimeType = ("Second-" DAVTimeOutVal | "Infinite") ; No LWS allowed within TimeType DAVTimeOutVal = 1*DIGIT Clients MAY include Timeout request headers in their LOCK requests. However, the server is not required to honor or even consider these requests. Clients MUST NOT submit a Timeout request header with any method other than a LOCK method. The "Second" TimeType specifies the number of seconds that will elapse between granting of the lock at the server, and the automatic removal of the lock. The timeout value for TimeType "Second" MUST NOT be greater than 2^32-1. See Section 6.6 for a description of lock timeout behavior.

11. Status Code Extensions to HTTP/1.1

The following status codes are added to those defined in HTTP/1.1 [RFC2616].

11.1. 207 Multi-Status

The 207 (Multi-Status) status code provides status for multiple independent operations (see Section 13 for more information).

11.2. 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code means the server understands the content type of the request entity (hence a 415(Unsupported Media Type) status code is inappropriate), and the syntax of the request entity is correct (thus a 400 (Bad Request) status code is inappropriate) but was unable to process the contained instructions. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.

11.3. 423 Locked

The 423 (Locked) status code means the source or destination resource of a method is locked. This response SHOULD contain an appropriate precondition or postcondition code, such as 'lock-token-submitted' or 'no-conflicting-lock'.
Top   ToC   RFC4918 - Page 79

11.4. 424 Failed Dependency

The 424 (Failed Dependency) status code means that the method could not be performed on the resource because the requested action depended on another action and that action failed. For example, if a command in a PROPPATCH method fails, then, at minimum, the rest of the commands will also fail with 424 (Failed Dependency).

11.5. 507 Insufficient Storage

The 507 (Insufficient Storage) status code means the method could not be performed on the resource because the server is unable to store the representation needed to successfully complete the request. This condition is considered to be temporary. If the request that received this status code was the result of a user action, the request MUST NOT be repeated until it is requested by a separate user action.

12. Use of HTTP Status Codes

These HTTP codes are not redefined, but their use is somewhat extended by WebDAV methods and requirements. In general, many HTTP status codes can be used in response to any request, not just in cases described in this document. Note also that WebDAV servers are known to use 300-level redirect responses (and early interoperability tests found clients unprepared to see those responses). A 300-level response MUST NOT be used when the server has created a new resource in response to the request.

12.1. 412 Precondition Failed

Any request can contain a conditional header defined in HTTP (If- Match, If-Modified-Since, etc.) or the "If" or "Overwrite" conditional headers defined in this specification. If the server evaluates a conditional header, and if that condition fails to hold, then this error code MUST be returned. On the other hand, if the client did not include a conditional header in the request, then the server MUST NOT use this status code.

12.2. 414 Request-URI Too Long

This status code is used in HTTP 1.1 only for Request-URIs, not URIs in other locations.
Top   ToC   RFC4918 - Page 80

13. Multi-Status Response

A Multi-Status response conveys information about multiple resources in situations where multiple status codes might be appropriate. The default Multi-Status response body is a text/xml or application/xml HTTP entity with a 'multistatus' root element. Further elements contain 200, 300, 400, and 500 series status codes generated during the method invocation. 100 series status codes SHOULD NOT be recorded in a 'response' XML element. Although '207' is used as the overall response status code, the recipient needs to consult the contents of the multistatus response body for further information about the success or failure of the method execution. The response MAY be used in success, partial success and also in failure situations. The 'multistatus' root element holds zero or more 'response' elements in any order, each with information about an individual resource. Each 'response' element MUST have an 'href' element to identify the resource. A Multi-Status response uses one out of two distinct formats for representing the status: 1. A 'status' element as child of the 'response' element indicates the status of the message execution for the identified resource as a whole (for instance, see Section 9.6.2). Some method definitions provide information about specific status codes clients should be prepared to see in a response. However, clients MUST be able to handle other status codes, using the generic rules defined in Section 10 of [RFC2616]. 2. For PROPFIND and PROPPATCH, the format has been extended using the 'propstat' element instead of 'status', providing information about individual properties of a resource. This format is specific to PROPFIND and PROPPATCH, and is described in detail in Sections 9.1 and 9.2.

13.1. Response Headers

HTTP defines the Location header to indicate a preferred URL for the resource that was addressed in the Request-URI (e.g., in response to successful PUT requests or in redirect responses). However, use of this header creates ambiguity when there are URLs in the body of the response, as with Multi-Status. Thus, use of the Location header with the Multi-Status response is intentionally undefined.
Top   ToC   RFC4918 - Page 81

13.2. Handling Redirected Child Resources

Redirect responses (300-303, 305, and 307) defined in HTTP 1.1 normally take a Location header to indicate the new URI for the single resource redirected from the Request-URI. Multi-Status responses contain many resource addresses, but the original definition in [RFC2518] did not have any place for the server to provide the new URI for redirected resources. This specification does define a 'location' element for this information (see Section 14.9). Servers MUST use this new element with redirect responses in Multi-Status. Clients encountering redirected resources in Multi-Status MUST NOT rely on the 'location' element being present with a new URI. If the element is not present, the client MAY reissue the request to the individual redirected resource, because the response to that request can be redirected with a Location header containing the new URI.

13.3. Internal Status Codes

Sections 9.2.1, 9.1.2, 9.6.1, 9.8.3, and 9.9.2 define various status codes used in Multi-Status responses. This specification does not define the meaning of other status codes that could appear in these responses.

14. XML Element Definitions

In this section, the final line of each section gives the element type declaration using the format defined in [REC-XML]. The "Value" field, where present, specifies further restrictions on the allowable contents of the XML element using BNF (i.e., to further restrict the values of a PCDATA element). Note that all of the elements defined here may be extended according to the rules defined in Section 17. All elements defined here are in the "DAV:" namespace.

14.1. activelock XML Element

Name: activelock Purpose: Describes a lock on a resource. <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?, locktoken?, lockroot)>
Top   ToC   RFC4918 - Page 82

14.2. allprop XML Element

Name: allprop Purpose: Specifies that all names and values of dead properties and the live properties defined by this document existing on the resource are to be returned. <!ELEMENT allprop EMPTY >

14.3. collection XML Element

Name: collection Purpose: Identifies the associated resource as a collection. The DAV:resourcetype property of a collection resource MUST contain this element. It is normally empty but extensions may add sub- elements. <!ELEMENT collection EMPTY >

14.4. depth XML Element

Name: depth Purpose: Used for representing depth values in XML content (e.g., in lock information). Value: "0" | "1" | "infinity" <!ELEMENT depth (#PCDATA) >

14.5. error XML Element

Name: error Purpose: Error responses, particularly 403 Forbidden and 409 Conflict, sometimes need more information to indicate what went wrong. In these cases, servers MAY return an XML response body with a document element of 'error', containing child elements identifying particular condition codes. Description: Contains at least one XML element, and MUST NOT contain text or mixed content. Any element that is a child of the 'error' element is considered to be a precondition or postcondition code. Unrecognized elements MUST be ignored. <!ELEMENT error ANY >
Top   ToC   RFC4918 - Page 83

14.6. exclusive XML Element

Name: exclusive Purpose: Specifies an exclusive lock. <!ELEMENT exclusive EMPTY >

14.7. href XML Element

Name: href Purpose: MUST contain a URI or a relative reference. Description: There may be limits on the value of 'href' depending on the context of its use. Refer to the specification text where 'href' is used to see what limitations apply in each case. Value: Simple-ref <!ELEMENT href (#PCDATA)>

14.8. include XML Element

Name: include Purpose: Any child element represents the name of a property to be included in the PROPFIND response. All elements inside an 'include' XML element MUST define properties related to the resource, although possible property names are in no way limited to those property names defined in this document or other standards. This element MUST NOT contain text or mixed content. <!ELEMENT include ANY >

14.9. location XML Element

Name: location Purpose: HTTP defines the "Location" header (see [RFC2616], Section 14.30) for use with some status codes (such as 201 and the 300 series codes). When these codes are used inside a 'multistatus' element, the 'location' element can be used to provide the accompanying Location header value.
Top   ToC   RFC4918 - Page 84
   Description:   Contains a single href element with the same value
      that would be used in a Location header.


   <!ELEMENT location (href)>

14.10. lockentry XML Element

Name: lockentry Purpose: Defines the types of locks that can be used with the resource. <!ELEMENT lockentry (lockscope, locktype) >

14.11. lockinfo XML Element

Name: lockinfo Purpose: The 'lockinfo' XML element is used with a LOCK method to specify the type of lock the client wishes to have created. <!ELEMENT lockinfo (lockscope, locktype, owner?) >

14.12. lockroot XML Element

Name: lockroot Purpose: Contains the root URL of the lock, which is the URL through which the resource was addressed in the LOCK request. Description: The href element contains the root of the lock. The server SHOULD include this in all DAV:lockdiscovery property values and the response to LOCK requests. <!ELEMENT lockroot (href) >

14.13. lockscope XML Element

Name: lockscope Purpose: Specifies whether a lock is an exclusive lock, or a shared lock. <!ELEMENT lockscope (exclusive | shared) >
Top   ToC   RFC4918 - Page 85

14.14. locktoken XML Element

Name: locktoken Purpose: The lock token associated with a lock. Description: The href contains a single lock token URI, which refers to the lock. <!ELEMENT locktoken (href) >

14.15. locktype XML Element

Name: locktype Purpose: Specifies the access type of a lock. At present, this specification only defines one lock type, the write lock. <!ELEMENT locktype (write) >

14.16. multistatus XML Element

Name: multistatus Purpose: Contains multiple response messages. Description: The 'responsedescription' element at the top level is used to provide a general message describing the overarching nature of the response. If this value is available, an application may use it instead of presenting the individual response descriptions contained within the responses. <!ELEMENT multistatus (response*, responsedescription?) >

14.17. owner XML Element

Name: owner Purpose: Holds client-supplied information about the creator of a lock. Description: Allows a client to provide information sufficient for either directly contacting a principal (such as a telephone number or Email URI), or for discovering the principal (such as the URL
Top   ToC   RFC4918 - Page 86
      of a homepage) who created a lock.  The value provided MUST be
      treated as a dead property in terms of XML Information Item
      preservation.  The server MUST NOT alter the value unless the
      owner value provided by the client is empty.  For a certain amount
      of interoperability between different client implementations, if
      clients have URI-formatted contact information for the lock
      creator suitable for user display, then clients SHOULD put those
      URIs in 'href' child elements of the 'owner' element.

   Extensibility:   MAY be extended with child elements, mixed content,
      text content or attributes.

   <!ELEMENT owner ANY >

14.18. prop XML Element

Name: prop Purpose: Contains properties related to a resource. Description: A generic container for properties defined on resources. All elements inside a 'prop' XML element MUST define properties related to the resource, although possible property names are in no way limited to those property names defined in this document or other standards. This element MUST NOT contain text or mixed content. <!ELEMENT prop ANY >

14.19. propertyupdate XML Element

Name: propertyupdate Purpose: Contains a request to alter the properties on a resource. Description: This XML element is a container for the information required to modify the properties on the resource. <!ELEMENT propertyupdate (remove | set)+ >

14.20. propfind XML Element

Name: propfind
Top   ToC   RFC4918 - Page 87
   Purpose:   Specifies the properties to be returned from a PROPFIND
      method.  Four special elements are specified for use with
      'propfind': 'prop', 'allprop', 'include', and 'propname'.  If
      'prop' is used inside 'propfind', it MUST NOT contain property
      values.

   <!ELEMENT propfind ( propname | (allprop, include?) | prop ) >

14.21. propname XML Element

Name: propname Purpose: Specifies that only a list of property names on the resource is to be returned. <!ELEMENT propname EMPTY >

14.22. propstat XML Element

Name: propstat Purpose: Groups together a prop and status element that is associated with a particular 'href' element. Description: The propstat XML element MUST contain one prop XML element and one status XML element. The contents of the prop XML element MUST only list the names of properties to which the result in the status element applies. The optional precondition/ postcondition element and 'responsedescription' text also apply to the properties named in 'prop'. <!ELEMENT propstat (prop, status, error?, responsedescription?) >

14.23. remove XML Element

Name: remove Purpose: Lists the properties to be removed from a resource. Description: Remove instructs that the properties specified in prop should be removed. Specifying the removal of a property that does not exist is not an error. All the XML elements in a 'prop' XML element inside of a 'remove' XML element MUST be empty, as only the names of properties to be removed are required. <!ELEMENT remove (prop) >
Top   ToC   RFC4918 - Page 88

14.24. response XML Element

Name: response Purpose: Holds a single response describing the effect of a method on resource and/or its properties. Description: The 'href' element contains an HTTP URL pointing to a WebDAV resource when used in the 'response' container. A particular 'href' value MUST NOT appear more than once as the child of a 'response' XML element under a 'multistatus' XML element. This requirement is necessary in order to keep processing costs for a response to linear time. Essentially, this prevents having to search in order to group together all the responses by 'href'. There are, however, no requirements regarding ordering based on 'href' values. The optional precondition/postcondition element and 'responsedescription' text can provide additional information about this resource relative to the request or result. <!ELEMENT response (href, ((href*, status)|(propstat+)), error?, responsedescription? , location?) >

14.25. responsedescription XML Element

Name: responsedescription Purpose: Contains information about a status response within a Multi-Status. Description: Provides information suitable to be presented to a user. <!ELEMENT responsedescription (#PCDATA) >

14.26. set XML Element

Name: set Purpose: Lists the property values to be set for a resource. Description: The 'set' element MUST contain only a 'prop' element. The elements contained by the 'prop' element inside the 'set' element MUST specify the name and value of properties that are set on the resource identified by Request-URI. If a property already exists, then its value is replaced. Language tagging information appearing in the scope of the 'prop' element (in the "xml:lang"
Top   ToC   RFC4918 - Page 89
      attribute, if present) MUST be persistently stored along with the
      property, and MUST be subsequently retrievable using PROPFIND.

   <!ELEMENT set (prop) >

14.27. shared XML Element

Name: shared Purpose: Specifies a shared lock. <!ELEMENT shared EMPTY >

14.28. status XML Element

Name: status Purpose: Holds a single HTTP status-line. Value: status-line (defined in Section 6.1 of [RFC2616]) <!ELEMENT status (#PCDATA) >

14.29. timeout XML Element

Name: timeout Purpose: The number of seconds remaining before a lock expires. Value: TimeType (defined in Section 10.7) <!ELEMENT timeout (#PCDATA) >

14.30. write XML Element

Name: write Purpose: Specifies a write lock. <!ELEMENT write EMPTY >
Top   ToC   RFC4918 - Page 90

15. DAV Properties

For DAV properties, the name of the property is also the same as the name of the XML element that contains its value. In the section below, the final line of each section gives the element type declaration using the format defined in [REC-XML]. The "Value" field, where present, specifies further restrictions on the allowable contents of the XML element using BNF (i.e., to further restrict the values of a PCDATA element). A protected property is one that cannot be changed with a PROPPATCH request. There may be other requests that would result in a change to a protected property (as when a LOCK request affects the value of DAV:lockdiscovery). Note that a given property could be protected on one type of resource, but not protected on another type of resource. A computed property is one with a value defined in terms of a computation (based on the content and other properties of that resource, or even of some other resource). A computed property is always a protected property. COPY and MOVE behavior refers to local COPY and MOVE operations. For properties defined based on HTTP GET response headers (DAV:get*), the header value could include LWS as defined in [RFC2616], Section 4.2. Server implementors SHOULD strip LWS from these values before using as WebDAV property values.

15.1. creationdate Property

Name: creationdate Purpose: Records the time and date the resource was created. Value: date-time (defined in [RFC3339], see the ABNF in Section 5.6.) Protected: MAY be protected. Some servers allow DAV:creationdate to be changed to reflect the time the document was created if that is more meaningful to the user (rather than the time it was uploaded). Thus, clients SHOULD NOT use this property in synchronization logic (use DAV:getetag instead). COPY/MOVE behavior: This property value SHOULD be kept during a MOVE operation, but is normally re-initialized when a resource is created with a COPY. It should not be set in a COPY.
Top   ToC   RFC4918 - Page 91
   Description:   The DAV:creationdate property SHOULD be defined on all
      DAV compliant resources.  If present, it contains a timestamp of
      the moment when the resource was created.  Servers that are
      incapable of persistently recording the creation date SHOULD
      instead leave it undefined (i.e. report "Not Found").

   <!ELEMENT creationdate (#PCDATA) >

15.2. displayname Property

Name: displayname Purpose: Provides a name for the resource that is suitable for presentation to a user. Value: Any text. Protected: SHOULD NOT be protected. Note that servers implementing [RFC2518] might have made this a protected property as this is a new requirement. COPY/MOVE behavior: This property value SHOULD be preserved in COPY and MOVE operations. Description: Contains a description of the resource that is suitable for presentation to a user. This property is defined on the resource, and hence SHOULD have the same value independent of the Request-URI used to retrieve it (thus, computing this property based on the Request-URI is deprecated). While generic clients might display the property value to end users, client UI designers must understand that the method for identifying resources is still the URL. Changes to DAV:displayname do not issue moves or copies to the server, but simply change a piece of meta-data on the individual resource. Two resources can have the same DAV: displayname value even within the same collection. <!ELEMENT displayname (#PCDATA) >

15.3. getcontentlanguage Property

Name: getcontentlanguage Purpose: Contains the Content-Language header value (from Section 14.12 of [RFC2616]) as it would be returned by a GET without accept headers. Value: language-tag (language-tag is defined in Section 3.10 of [RFC2616])
Top   ToC   RFC4918 - Page 92
   Protected:   SHOULD NOT be protected, so that clients can reset the
      language.  Note that servers implementing [RFC2518] might have
      made this a protected property as this is a new requirement.

   COPY/MOVE behavior:   This property value SHOULD be preserved in COPY
      and MOVE operations.

   Description:   The DAV:getcontentlanguage property MUST be defined on
      any DAV-compliant resource that returns the Content-Language
      header on a GET.

   <!ELEMENT getcontentlanguage (#PCDATA) >

15.4. getcontentlength Property

Name: getcontentlength Purpose: Contains the Content-Length header returned by a GET without accept headers. Value: See Section 14.13 of [RFC2616]. Protected: This property is computed, therefore protected. Description: The DAV:getcontentlength property MUST be defined on any DAV-compliant resource that returns the Content-Length header in response to a GET. COPY/MOVE behavior: This property value is dependent on the size of the destination resource, not the value of the property on the source resource. <!ELEMENT getcontentlength (#PCDATA) >

15.5. getcontenttype Property

Name: getcontenttype Purpose: Contains the Content-Type header value (from Section 14.17 of [RFC2616]) as it would be returned by a GET without accept headers. Value: media-type (defined in Section 3.7 of [RFC2616]) Protected: Potentially protected if the server prefers to assign content types on its own (see also discussion in Section 9.7.1).
Top   ToC   RFC4918 - Page 93
   COPY/MOVE behavior:   This property value SHOULD be preserved in COPY
      and MOVE operations.

   Description:   This property MUST be defined on any DAV-compliant
      resource that returns the Content-Type header in response to a
      GET.

   <!ELEMENT getcontenttype (#PCDATA) >

15.6. getetag Property

Name: getetag Purpose: Contains the ETag header value (from Section 14.19 of [RFC2616]) as it would be returned by a GET without accept headers. Value: entity-tag (defined in Section 3.11 of [RFC2616]) Protected: MUST be protected because this value is created and controlled by the server. COPY/MOVE behavior: This property value is dependent on the final state of the destination resource, not the value of the property on the source resource. Also note the considerations in Section 8.8. Description: The getetag property MUST be defined on any DAV- compliant resource that returns the Etag header. Refer to Section 3.11 of RFC 2616 for a complete definition of the semantics of an ETag, and to Section 8.6 for a discussion of ETags in WebDAV. <!ELEMENT getetag (#PCDATA) >

15.7. getlastmodified Property

Name: getlastmodified Purpose: Contains the Last-Modified header value (from Section 14.29 of [RFC2616]) as it would be returned by a GET method without accept headers. Value: rfc1123-date (defined in Section 3.3.1 of [RFC2616]) Protected: SHOULD be protected because some clients may rely on the value for appropriate caching behavior, or on the value of the Last-Modified header to which this property is linked.
Top   ToC   RFC4918 - Page 94
   COPY/MOVE behavior:   This property value is dependent on the last
      modified date of the destination resource, not the value of the
      property on the source resource.  Note that some server
      implementations use the file system date modified value for the
      DAV:getlastmodified value, and this can be preserved in a MOVE
      even when the HTTP Last-Modified value SHOULD change.  Note that
      since [RFC2616] requires clients to use ETags where provided, a
      server implementing ETags can count on clients using a much better
      mechanism than modification dates for offline synchronization or
      cache control.  Also note the considerations in Section 8.8.

   Description:   The last-modified date on a resource SHOULD only
      reflect changes in the body (the GET responses) of the resource.
      A change in a property only SHOULD NOT cause the last-modified
      date to change, because clients MAY rely on the last-modified date
      to know when to overwrite the existing body.  The DAV:
      getlastmodified property MUST be defined on any DAV-compliant
      resource that returns the Last-Modified header in response to a
      GET.

   <!ELEMENT getlastmodified (#PCDATA) >

15.8. lockdiscovery Property

Name: lockdiscovery Purpose: Describes the active locks on a resource Protected: MUST be protected. Clients change the list of locks through LOCK and UNLOCK, not through PROPPATCH. COPY/MOVE behavior: The value of this property depends on the lock state of the destination, not on the locks of the source resource. Recall that locks are not moved in a MOVE operation. Description: Returns a listing of who has a lock, what type of lock he has, the timeout type and the time remaining on the timeout, and the associated lock token. Owner information MAY be omitted if it is considered sensitive. If there are no locks, but the server supports locks, the property will be present but contain zero 'activelock' elements. If there are one or more locks, an 'activelock' element appears for each lock on the resource. This property is NOT lockable with respect to write locks (Section 7). <!ELEMENT lockdiscovery (activelock)* >
Top   ToC   RFC4918 - Page 95

15.8.1. Example - Retrieving DAV:lockdiscovery

>>Request PROPFIND /container/ HTTP/1.1 Host: www.example.com Content-Length: xxxx Content-Type: application/xml; charset="utf-8" <?xml version="1.0" encoding="utf-8" ?> <D:propfind xmlns:D='DAV:'> <D:prop><D:lockdiscovery/></D:prop> </D:propfind> >>Response HTTP/1.1 207 Multi-Status Content-Type: application/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D='DAV:'> <D:response> <D:href>http://www.example.com/container/</D:href> <D:propstat> <D:prop> <D:lockdiscovery> <D:activelock> <D:locktype><D:write/></D:locktype> <D:lockscope><D:exclusive/></D:lockscope> <D:depth>0</D:depth> <D:owner>Jane Smith</D:owner> <D:timeout>Infinite</D:timeout> <D:locktoken> <D:href >urn:uuid:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76</D:href> </D:locktoken> <D:lockroot> <D:href>http://www.example.com/container/</D:href> </D:lockroot> </D:activelock> </D:lockdiscovery> </D:prop> <D:status>HTTP/1.1 200 OK</D:status> </D:propstat> </D:response> </D:multistatus>
Top   ToC   RFC4918 - Page 96
   This resource has a single exclusive write lock on it, with an
   infinite timeout.

15.9. resourcetype Property

Name: resourcetype Purpose: Specifies the nature of the resource. Protected: SHOULD be protected. Resource type is generally decided through the operation creating the resource (MKCOL vs PUT), not by PROPPATCH. COPY/MOVE behavior: Generally a COPY/MOVE of a resource results in the same type of resource at the destination. Description: MUST be defined on all DAV-compliant resources. Each child element identifies a specific type the resource belongs to, such as 'collection', which is the only resource type defined by this specification (see Section 14.3). If the element contains the 'collection' child element plus additional unrecognized elements, it should generally be treated as a collection. If the element contains no recognized child elements, it should be treated as a non-collection resource. The default value is empty. This element MUST NOT contain text or mixed content. Any custom child element is considered to be an identifier for a resource type. Example: (fictional example to show extensibility) <x:resourcetype xmlns:x="DAV:"> <x:collection/> <f:search-results xmlns:f="http://www.example.com/ns"/> </x:resourcetype>

15.10. supportedlock Property

Name: supportedlock Purpose: To provide a listing of the lock capabilities supported by the resource. Protected: MUST be protected. Servers, not clients, determine what lock mechanisms are supported.
Top   ToC   RFC4918 - Page 97
   COPY/MOVE behavior:   This property value is dependent on the kind of
      locks supported at the destination, not on the value of the
      property at the source resource.  Servers attempting to COPY to a
      destination should not attempt to set this property at the
      destination.

   Description:   Returns a listing of the combinations of scope and
      access types that may be specified in a lock request on the
      resource.  Note that the actual contents are themselves controlled
      by access controls, so a server is not required to provide
      information the client is not authorized to see.  This property is
      NOT lockable with respect to write locks (Section 7).

   <!ELEMENT supportedlock (lockentry)* >

15.10.1. Example - Retrieving DAV:supportedlock

>>Request PROPFIND /container/ HTTP/1.1 Host: www.example.com Content-Length: xxxx Content-Type: application/xml; charset="utf-8" <?xml version="1.0" encoding="utf-8" ?> <D:propfind xmlns:D="DAV:"> <D:prop><D:supportedlock/></D:prop> </D:propfind> >>Response HTTP/1.1 207 Multi-Status Content-Type: application/xml; charset="utf-8" Content-Length: xxxx <?xml version="1.0" encoding="utf-8" ?> <D:multistatus xmlns:D="DAV:"> <D:response> <D:href>http://www.example.com/container/</D:href> <D:propstat> <D:prop> <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>
Top   ToC   RFC4918 - Page 98
                 <D:locktype><D:write/></D:locktype>
               </D:lockentry>
             </D:supportedlock>
           </D:prop>
           <D:status>HTTP/1.1 200 OK</D:status>
         </D:propstat>
       </D:response>
     </D:multistatus>

16. Precondition/Postcondition XML Elements

As introduced in Section 8.7, extra information on error conditions can be included in the body of many status responses. This section makes requirements on the use of the error body mechanism and introduces a number of precondition and postcondition codes. A "precondition" of a method describes the state of the server that must be true for that method to be performed. A "postcondition" of a method describes the state of the server that must be true after that method has been completed. Each precondition and postcondition has a unique XML element associated with it. In a 207 Multi-Status response, the XML element MUST appear inside an 'error' element in the appropriate 'propstat or 'response' element depending on whether the condition applies to one or more properties or to the resource as a whole. In all other error responses where this specification's 'error' body is used, the precondition/postcondition XML element MUST be returned as the child of a top-level 'error' element in the response body, unless otherwise negotiated by the request, along with an appropriate response status. The most common response status codes are 403 (Forbidden) if the request should not be repeated because it will always fail, and 409 (Conflict) if it is expected that the user might be able to resolve the conflict and resubmit the request. The 'error' element MAY contain child elements with specific error information and MAY be extended with any custom child elements. This mechanism does not take the place of using a correct numeric status code as defined here or in HTTP, because the client must always be able to take a reasonable course of action based only on the numeric code. However, it does remove the need to define new numeric codes. The new machine-readable codes used for this purpose are XML elements classified as preconditions and postconditions, so naturally, any group defining a new condition code can use their own namespace. As always, the "DAV:" namespace is reserved for use by IETF-chartered WebDAV working groups.
Top   ToC   RFC4918 - Page 99
   A server supporting this specification SHOULD use the XML error
   whenever a precondition or postcondition defined in this document is
   violated.  For error conditions not specified in this document, the
   server MAY simply choose an appropriate numeric status and leave the
   response body blank.  However, a server MAY instead use a custom
   condition code and other supporting text, because even when clients
   do not automatically recognize condition codes, they can be quite
   useful in interoperability testing and debugging.

   Example - Response with precondition code

   >>Response

      HTTP/1.1 423 Locked
      Content-Type: application/xml; charset="utf-8"
      Content-Length: xxxx

      <?xml version="1.0" encoding="utf-8" ?>
      <D:error xmlns:D="DAV:">
        <D:lock-token-submitted>
          <D:href>/workspace/webdav/</D:href>
        </D:lock-token-submitted>
      </D:error>

   In this example, a client unaware of a depth-infinity lock on the
   parent collection "/workspace/webdav/" attempted to modify the
   collection member "/workspace/webdav/proposal.doc".

   Some other useful preconditions and postconditions have been defined
   in other specifications extending WebDAV, such as [RFC3744] (see
   particularly Section 7.1.1), [RFC3253], and [RFC3648].

   All these elements are in the "DAV:" namespace.  If not specified
   otherwise, the content for each condition's XML element is defined to
   be empty.


   Name:  lock-token-matches-request-uri

   Use with:  409 Conflict

   Purpose:  (precondition) -- A request may include a Lock-Token header
      to identify a lock for the UNLOCK method.  However, if the
      Request-URI does not fall within the scope of the lock identified
      by the token, the server SHOULD use this error.  The lock may have
      a scope that does not include the Request-URI, or the lock could
      have disappeared, or the token may be invalid.
Top   ToC   RFC4918 - Page 100
   Name:  lock-token-submitted (precondition)

   Use with:  423 Locked

   Purpose:  The request could not succeed because a lock token should
      have been submitted.  This element, if present, MUST contain at
      least one URL of a locked resource that prevented the request.  In
      cases of MOVE, COPY, and DELETE where collection locks are
      involved, it can be difficult for the client to find out which
      locked resource made the request fail -- but the server is only
      responsible for returning one such locked resource.  The server
      MAY return every locked resource that prevented the request from
      succeeding if it knows them all.

   <!ELEMENT lock-token-submitted (href+) >


   Name:  no-conflicting-lock (precondition)

   Use with:  Typically 423 Locked

   Purpose:  A LOCK request failed due the presence of an already
      existing conflicting lock.  Note that a lock can be in conflict
      although the resource to which the request was directed is only
      indirectly locked.  In this case, the precondition code can be
      used to inform the client about the resource that is the root of
      the conflicting lock, avoiding a separate lookup of the
      "lockdiscovery" property.

   <!ELEMENT no-conflicting-lock (href)* >


   Name:  no-external-entities

   Use with:  403 Forbidden

   Purpose:  (precondition) -- If the server rejects a client request
      because the request body contains an external entity, the server
      SHOULD use this error.


   Name:  preserved-live-properties

   Use with:  409 Conflict

   Purpose:  (postcondition) -- The server received an otherwise-valid
      MOVE or COPY request, but cannot maintain the live properties with
      the same behavior at the destination.  It may be that the server
Top   ToC   RFC4918 - Page 101
      only supports some live properties in some parts of the
      repository, or simply has an internal error.


   Name:  propfind-finite-depth

   Use with:  403 Forbidden

   Purpose:  (precondition) -- This server does not allow infinite-depth
      PROPFIND requests on collections.


   Name:  cannot-modify-protected-property

   Use with:  403 Forbidden

   Purpose:  (precondition) -- The client attempted to set a protected
      property in a PROPPATCH (such as DAV:getetag).  See also
      [RFC3253], Section 3.12.

17. XML Extensibility in DAV

The XML namespace extension ([REC-XML-NAMES]) is used in this specification in order to allow for new XML elements to be added without fear of colliding with other element names. Although WebDAV request and response bodies can be extended by arbitrary XML elements, which can be ignored by the message recipient, an XML element in the "DAV:" namespace SHOULD NOT be used in the request or response body unless that XML element is explicitly defined in an IETF RFC reviewed by a WebDAV working group. For WebDAV to be both extensible and backwards-compatible, both clients and servers need to know how to behave when unexpected or unrecognized command extensions are received. For XML processing, this means that clients and servers MUST process received XML documents as if unexpected elements and attributes (and all children of unrecognized elements) were not there. An unexpected element or attribute includes one that may be used in another context but is not expected here. Ignoring such items for purposes of processing can of course be consistent with logging all information or presenting for debugging. This restriction also applies to the processing, by clients, of DAV property values where unexpected XML elements SHOULD be ignored unless the property's schema declares otherwise. This restriction does not apply to setting dead DAV properties on the server where the server MUST record all XML elements.
Top   ToC   RFC4918 - Page 102
   Additionally, this restriction does not apply to the use of XML where
   XML happens to be the content type of the entity body, for example,
   when used as the body of a PUT.

   Processing instructions in XML SHOULD be ignored by recipients.
   Thus, specifications extending WebDAV SHOULD NOT use processing
   instructions to define normative behavior.

   XML DTD fragments are included for all the XML elements defined in
   this specification.  However, correct XML will not be valid according
   to any DTD due to namespace usage and extension rules.  In
   particular:

   o  Elements (from this specification) are in the "DAV:" namespace,

   o  Element ordering is irrelevant unless otherwise stated,

   o  Extension attributes MAY be added,

   o  For element type definitions of "ANY", the normative text
      definition for that element defines what can be in it and what
      that means.

   o  For element type definitions of "#PCDATA", extension elements MUST
      NOT be added.

   o  For other element type definitions, including "EMPTY", extension
      elements MAY be added.

   Note that this means that elements containing elements cannot be
   extended to contain text, and vice versa.

   With DTD validation relaxed by the rules above, the constraints
   described by the DTD fragments are normative (see for example
   Appendix A).  A recipient of a WebDAV message with an XML body MUST
   NOT validate the XML document according to any hard-coded or
   dynamically-declared DTD.

   Note that this section describes backwards-compatible extensibility
   rules.  There might also be times when an extension is designed not
   to be backwards-compatible, for example, defining an extension that
   reuses an XML element defined in this document but omitting one of
   the child elements required by the DTDs in this specification.


(next page on part 5)

Next Section