tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 4918

 
 
 

HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)

Part 3 of 5, p. 44 to 77
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 44 
9.2.  PROPPATCH Method

   The PROPPATCH method processes instructions specified in the request
   body to set and/or remove properties defined on the resource
   identified by the Request-URI.

   All DAV-compliant resources MUST support the PROPPATCH method and
   MUST process instructions that are specified using the
   propertyupdate, set, and remove XML elements.  Execution of the
   directives in this method is, of course, subject to access control
   constraints.  DAV-compliant resources SHOULD support the setting of
   arbitrary dead properties.

   The request message body of a PROPPATCH method MUST contain the
   propertyupdate XML element.

   Servers MUST process PROPPATCH instructions in document order (an
   exception to the normal rule that ordering is irrelevant).
   Instructions MUST either all be executed or none executed.  Thus, if
   any error occurs during processing, all executed instructions MUST be
   undone and a proper error result returned.  Instruction processing
   details can be found in the definition of the set and remove
   instructions in Sections 14.23 and 14.26.

   If a server attempts to make any of the property changes in a
   PROPPATCH request (i.e., the request is not rejected for high-level
   errors before processing the body), the response MUST be a Multi-
   Status response as described in Section 9.2.1.

   This method is idempotent, but not safe (see Section 9.1 of
   [RFC2616]).  Responses to this method MUST NOT be cached.

9.2.1.  Status Codes for Use in 'propstat' Element

   In PROPPATCH responses, information about individual properties is
   returned inside 'propstat' elements (see Section 14.22), each
   containing an individual 'status' element containing information
   about the properties appearing in it.  The list below summarizes the
   most common status codes used inside 'propstat'; however, clients
   should be prepared to handle other 2/3/4/5xx series status codes as
   well.

Top      Up      ToC       Page 45 
   200 (OK) - The property set or change succeeded.  Note that if this
   appears for one property, it appears for every property in the
   response, due to the atomicity of PROPPATCH.

   403 (Forbidden) - The client, for reasons the server chooses not to
   specify, cannot alter one of the properties.

   403 (Forbidden): The client has attempted to set a protected
   property, such as DAV:getetag.  If returning this error, the server
   SHOULD use the precondition code 'cannot-modify-protected-property'
   inside the response body.

   409 (Conflict) - The client has provided a value whose semantics are
   not appropriate for the property.

   424 (Failed Dependency) - The property change could not be made
   because of another property change that failed.

   507 (Insufficient Storage) - The server did not have sufficient space
   to record the property.

9.2.2.  Example - PROPPATCH

   >>Request

     PROPPATCH /bar.html HTTP/1.1
     Host: www.example.com
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <D:propertyupdate xmlns:D="DAV:"
             xmlns:Z="http://ns.example.com/standards/z39.50/">
       <D:set>
         <D:prop>
           <Z:Authors>
             <Z:Author>Jim Whitehead</Z:Author>
             <Z:Author>Roy Fielding</Z:Author>
           </Z:Authors>
         </D:prop>
       </D:set>
       <D:remove>
         <D:prop><Z:Copyright-Owner/></D:prop>
       </D:remove>
     </D:propertyupdate>

Top      Up      ToC       Page 46 
   >>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:"
             xmlns:Z="http://ns.example.com/standards/z39.50/">
       <D:response>
         <D:href>http://www.example.com/bar.html</D:href>
         <D:propstat>
           <D:prop><Z:Authors/></D:prop>
           <D:status>HTTP/1.1 424 Failed Dependency</D:status>
         </D:propstat>
         <D:propstat>
           <D:prop><Z:Copyright-Owner/></D:prop>
           <D:status>HTTP/1.1 409 Conflict</D:status>
         </D:propstat>
         <D:responsedescription> Copyright Owner cannot be deleted or
           altered.</D:responsedescription>
       </D:response>
     </D:multistatus>

   In this example, the client requests the server to set the value of
   the "Authors" property in the
   "http://ns.example.com/standards/z39.50/" namespace, and to remove
   the property "Copyright-Owner" in the same namespace.  Since the
   Copyright-Owner property could not be removed, no property
   modifications occur.  The 424 (Failed Dependency) status code for the
   Authors property indicates this action would have succeeded if it
   were not for the conflict with removing the Copyright-Owner property.

9.3.  MKCOL Method

   MKCOL creates a new collection resource at the location specified by
   the Request-URI.  If the Request-URI is already mapped to a resource,
   then the MKCOL MUST fail.  During MKCOL processing, a server MUST
   make the Request-URI an internal member of its parent collection,
   unless the Request-URI is "/".  If no such ancestor exists, the
   method MUST fail.  When the MKCOL operation creates a new collection
   resource, all ancestors MUST already exist, or the method MUST fail
   with a 409 (Conflict) status code.  For example, if a request to
   create collection /a/b/c/d/ is made, and /a/b/c/ does not exist, the
   request must fail.

   When MKCOL is invoked without a request body, the newly created
   collection SHOULD have no members.

Top      Up      ToC       Page 47 
   A MKCOL request message may contain a message body.  The precise
   behavior of a MKCOL request when the body is present is undefined,
   but limited to creating collections, members of a collection, bodies
   of members, and properties on the collections or members.  If the
   server receives a MKCOL request entity type it does not support or
   understand, it MUST respond with a 415 (Unsupported Media Type)
   status code.  If the server decides to reject the request based on
   the presence of an entity or the type of an entity, it should use the
   415 (Unsupported Media Type) status code.

   This method is idempotent, but not safe (see Section 9.1 of
   [RFC2616]).  Responses to this method MUST NOT be cached.

9.3.1.  MKCOL Status Codes

   In addition to the general status codes possible, the following
   status codes have specific applicability to MKCOL:

   201 (Created) - The collection was created.

   403 (Forbidden) - This indicates at least one of two conditions: 1)
   the server does not allow the creation of collections at the given
   location in its URL namespace, or 2) the parent collection of the
   Request-URI exists but cannot accept members.

   405 (Method Not Allowed) - MKCOL can only be executed on an unmapped
   URL.

   409 (Conflict) - A collection cannot be made at the Request-URI until
   one or more intermediate collections have been created.  The server
   MUST NOT create those intermediate collections automatically.

   415 (Unsupported Media Type) - The server does not support the
   request body type (although bodies are legal on MKCOL requests, since
   this specification doesn't define any, the server is likely not to
   support any given body type).

   507 (Insufficient Storage) - The resource does not have sufficient
   space to record the state of the resource after the execution of this
   method.

9.3.2.  Example - MKCOL

   This example creates a collection called /webdisc/xfiles/ on the
   server www.example.com.

Top      Up      ToC       Page 48 
   >>Request

     MKCOL /webdisc/xfiles/ HTTP/1.1
     Host: www.example.com


   >>Response

     HTTP/1.1 201 Created

9.4.  GET, HEAD for Collections

   The semantics of GET are unchanged when applied to a collection,
   since GET is defined as, "retrieve whatever information (in the form
   of an entity) is identified by the Request-URI" [RFC2616].  GET, when
   applied to a collection, may return the contents of an "index.html"
   resource, a human-readable view of the contents of the collection, or
   something else altogether.  Hence, it is possible that the result of
   a GET on a collection will bear no correlation to the membership of
   the collection.

   Similarly, since the definition of HEAD is a GET without a response
   message body, the semantics of HEAD are unmodified when applied to
   collection resources.

9.5.  POST for Collections

   Since by definition the actual function performed by POST is
   determined by the server and often depends on the particular
   resource, the behavior of POST when applied to collections cannot be
   meaningfully modified because it is largely undefined.  Thus, the
   semantics of POST are unmodified when applied to a collection.

9.6.  DELETE Requirements

   DELETE is defined in [RFC2616], Section 9.7, to "delete the resource
   identified by the Request-URI".  However, WebDAV changes some DELETE
   handling requirements.

   A server processing a successful DELETE request:

      MUST destroy locks rooted on the deleted resource

      MUST remove the mapping from the Request-URI to any resource.

   Thus, after a successful DELETE operation (and in the absence of
   other actions), a subsequent GET/HEAD/PROPFIND request to the target
   Request-URI MUST return 404 (Not Found).

Top      Up      ToC       Page 49 
9.6.1.  DELETE for Collections

   The DELETE method on a collection MUST act as if a "Depth: infinity"
   header was used on it.  A client MUST NOT submit a Depth header with
   a DELETE on a collection with any value but infinity.

   DELETE instructs that the collection specified in the Request-URI and
   all resources identified by its internal member URLs are to be
   deleted.

   If any resource identified by a member URL cannot be deleted, then
   all of the member's ancestors MUST NOT be deleted, so as to maintain
   URL namespace consistency.

   Any headers included with DELETE MUST be applied in processing every
   resource to be deleted.

   When the DELETE method has completed processing, it MUST result in a
   consistent URL namespace.

   If an error occurs deleting a member resource (a resource other than
   the resource identified in the Request-URI), then the response can be
   a 207 (Multi-Status).  Multi-Status is used here to indicate which
   internal resources could NOT be deleted, including an error code,
   which should help the client understand which resources caused the
   failure.  For example, the Multi-Status body could include a response
   with status 423 (Locked) if an internal resource was locked.

   The server MAY return a 4xx status response, rather than a 207, if
   the request failed completely.

   424 (Failed Dependency) status codes SHOULD NOT be in the 207 (Multi-
   Status) response for DELETE.  They can be safely left out because the
   client will know that the ancestors of a resource could not be
   deleted when the client receives an error for the ancestor's progeny.
   Additionally, 204 (No Content) errors SHOULD NOT be returned in the
   207 (Multi-Status).  The reason for this prohibition is that 204 (No
   Content) is the default success code.

9.6.2.  Example - DELETE

   >>Request

     DELETE  /container/ HTTP/1.1
     Host: www.example.com

Top      Up      ToC       Page 50 
   >>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/resource3</d:href>
         <d:status>HTTP/1.1 423 Locked</d:status>
         <d:error><d:lock-token-submitted/></d:error>
       </d:response>
     </d:multistatus>

   In this example, the attempt to delete
   http://www.example.com/container/resource3 failed because it is
   locked, and no lock token was submitted with the request.
   Consequently, the attempt to delete http://www.example.com/container/
   also failed.  Thus, the client knows that the attempt to delete
   http://www.example.com/container/ must have also failed since the
   parent cannot be deleted unless its child has also been deleted.
   Even though a Depth header has not been included, a depth of infinity
   is assumed because the method is on a collection.

9.7.  PUT Requirements

9.7.1.  PUT for Non-Collection Resources

   A PUT performed on an existing resource replaces the GET response
   entity of the resource.  Properties defined on the resource may be
   recomputed during PUT processing but are not otherwise affected.  For
   example, if a server recognizes the content type of the request body,
   it may be able to automatically extract information that could be
   profitably exposed as properties.

   A PUT that would result in the creation of a resource without an
   appropriately scoped parent collection MUST fail with a 409
   (Conflict).

   A PUT request allows a client to indicate what media type an entity
   body has, and whether it should change if overwritten.  Thus, a
   client SHOULD provide a Content-Type for a new resource if any is
   known.  If the client does not provide a Content-Type for a new
   resource, the server MAY create a resource with no Content-Type
   assigned, or it MAY attempt to assign a Content-Type.

Top      Up      ToC       Page 51 
   Note that although a recipient ought generally to treat metadata
   supplied with an HTTP request as authoritative, in practice there's
   no guarantee that a server will accept client-supplied metadata
   (e.g., any request header beginning with "Content-").  Many servers
   do not allow configuring the Content-Type on a per-resource basis in
   the first place.  Thus, clients can't always rely on the ability to
   directly influence the content type by including a Content-Type
   request header.

9.7.2.  PUT for Collections

   This specification does not define the behavior of the PUT method for
   existing collections.  A PUT request to an existing collection MAY be
   treated as an error (405 Method Not Allowed).

   The MKCOL method is defined to create collections.

9.8.  COPY Method

   The COPY method creates a duplicate of the source resource identified
   by the Request-URI, in the destination resource identified by the URI
   in the Destination header.  The Destination header MUST be present.
   The exact behavior of the COPY method depends on the type of the
   source resource.

   All WebDAV-compliant resources MUST support the COPY method.
   However, support for the COPY method does not guarantee the ability
   to copy a resource.  For example, separate programs may control
   resources on the same server.  As a result, it may not be possible to
   copy a resource to a location that appears to be on the same server.

   This method is idempotent, but not safe (see Section 9.1 of
   [RFC2616]).  Responses to this method MUST NOT be cached.

9.8.1.  COPY for Non-collection Resources

   When the source resource is not a collection, the result of the COPY
   method is the creation of a new resource at the destination whose
   state and behavior match that of the source resource as closely as
   possible.  Since the environment at the destination may be different
   than at the source due to factors outside the scope of control of the
   server, such as the absence of resources required for correct
   operation, it may not be possible to completely duplicate the
   behavior of the resource at the destination.  Subsequent alterations
   to the destination resource will not modify the source resource.
   Subsequent alterations to the source resource will not modify the
   destination resource.

Top      Up      ToC       Page 52 
9.8.2.  COPY for Properties

   After a successful COPY invocation, all dead properties on the source
   resource SHOULD be duplicated on the destination resource.  Live
   properties described in this document SHOULD be duplicated as
   identically behaving live properties at the destination resource, but
   not necessarily with the same values.  Servers SHOULD NOT convert
   live properties into dead properties on the destination resource,
   because clients may then draw incorrect conclusions about the state
   or functionality of a resource.  Note that some live properties are
   defined such that the absence of the property has a specific meaning
   (e.g., a flag with one meaning if present, and the opposite if
   absent), and in these cases, a successful COPY might result in the
   property being reported as "Not Found" in subsequent requests.

   When the destination is an unmapped URL, a COPY operation creates a
   new resource much like a PUT operation does.  Live properties that
   are related to resource creation (such as DAV:creationdate) should
   have their values set accordingly.

9.8.3.  COPY for Collections

   The COPY method on a collection without a Depth header MUST act as if
   a Depth header with value "infinity" was included.  A client may
   submit a Depth header on a COPY on a collection with a value of "0"
   or "infinity".  Servers MUST support the "0" and "infinity" Depth
   header behaviors on WebDAV-compliant resources.

   An infinite-depth COPY instructs that the collection resource
   identified by the Request-URI is to be copied to the location
   identified by the URI in the Destination header, and all its internal
   member resources are to be copied to a location relative to it,
   recursively through all levels of the collection hierarchy.  Note
   that an infinite-depth COPY of /A/ into /A/B/ could lead to infinite
   recursion if not handled correctly.

   A COPY of "Depth: 0" only instructs that the collection and its
   properties, but not resources identified by its internal member URLs,
   are to be copied.

   Any headers included with a COPY MUST be applied in processing every
   resource to be copied with the exception of the Destination header.

   The Destination header only specifies the destination URI for the
   Request-URI.  When applied to members of the collection identified by
   the Request-URI, the value of Destination is to be modified to
   reflect the current location in the hierarchy.  So, if the Request-
   URI is /a/ with Host header value http://example.com/ and the

Top      Up      ToC       Page 53 
   Destination is http://example.com/b/, then when
   http://example.com/a/c/d is processed, it must use a Destination of
   http://example.com/b/c/d.

   When the COPY method has completed processing, it MUST have created a
   consistent URL namespace at the destination (see Section 5.1 for the
   definition of namespace consistency).  However, if an error occurs
   while copying an internal collection, the server MUST NOT copy any
   resources identified by members of this collection (i.e., the server
   must skip this subtree), as this would create an inconsistent
   namespace.  After detecting an error, the COPY operation SHOULD try
   to finish as much of the original copy operation as possible (i.e.,
   the server should still attempt to copy other subtrees and their
   members that are not descendants of an error-causing collection).

   So, for example, if an infinite-depth copy operation is performed on
   collection /a/, which contains collections /a/b/ and /a/c/, and an
   error occurs copying /a/b/, an attempt should still be made to copy
   /a/c/.  Similarly, after encountering an error copying a non-
   collection resource as part of an infinite-depth copy, the server
   SHOULD try to finish as much of the original copy operation as
   possible.

   If an error in executing the COPY method occurs with a resource other
   than the resource identified in the Request-URI, then the response
   MUST be a 207 (Multi-Status), and the URL of the resource causing the
   failure MUST appear with the specific error.

   The 424 (Failed Dependency) status code SHOULD NOT be returned in the
   207 (Multi-Status) response from a COPY method.  These responses can
   be safely omitted because the client will know that the progeny of a
   resource could not be copied when the client receives an error for
   the parent.  Additionally, 201 (Created)/204 (No Content) status
   codes SHOULD NOT be returned as values in 207 (Multi-Status)
   responses from COPY methods.  They, too, can be safely omitted
   because they are the default success codes.

9.8.4.  COPY and Overwriting Destination Resources

   If a COPY request has an Overwrite header with a value of "F", and a
   resource exists at the Destination URL, the server MUST fail the
   request.

   When a server executes a COPY request and overwrites a destination
   resource, the exact behavior MAY depend on many factors, including
   WebDAV extension capabilities (see particularly [RFC3253]).  For

Top      Up      ToC       Page 54 
   example, when an ordinary resource is overwritten, the server could
   delete the target resource before doing the copy, or could do an in-
   place overwrite to preserve live properties.

   When a collection is overwritten, the membership of the destination
   collection after the successful COPY request MUST be the same
   membership as the source collection immediately before the COPY.
   Thus, merging the membership of the source and destination
   collections together in the destination is not a compliant behavior.

   In general, if clients require the state of the destination URL to be
   wiped out prior to a COPY (e.g., to force live properties to be
   reset), then the client could send a DELETE to the destination before
   the COPY request to ensure this reset.

9.8.5.  Status Codes

   In addition to the general status codes possible, the following
   status codes have specific applicability to COPY:

   201 (Created) - The source resource was successfully copied.  The
   COPY operation resulted in the creation of a new resource.

   204 (No Content) - The source resource was successfully copied to a
   preexisting destination resource.

   207 (Multi-Status) - Multiple resources were to be affected by the
   COPY, but errors on some of them prevented the operation from taking
   place.  Specific error messages, together with the most appropriate
   of the source and destination URLs, appear in the body of the multi-
   status response.  For example, if a destination resource was locked
   and could not be overwritten, then the destination resource URL
   appears with the 423 (Locked) status.

   403 (Forbidden) - The operation is forbidden.  A special case for
   COPY could be that the source and destination resources are the same
   resource.

   409 (Conflict) - A resource cannot be created at the destination
   until one or more intermediate collections have been created.  The
   server MUST NOT create those intermediate collections automatically.

   412 (Precondition Failed) - A precondition header check failed, e.g.,
   the Overwrite header is "F" and the destination URL is already mapped
   to a resource.

Top      Up      ToC       Page 55 
   423 (Locked) - The destination resource, or resource within the
   destination collection, was locked.  This response SHOULD contain the
   'lock-token-submitted' precondition element.

   502 (Bad Gateway) - This may occur when the destination is on another
   server, repository, or URL namespace.  Either the source namespace
   does not support copying to the destination namespace, or the
   destination namespace refuses to accept the resource.  The client may
   wish to try GET/PUT and PROPFIND/PROPPATCH instead.

   507 (Insufficient Storage) - The destination resource does not have
   sufficient space to record the state of the resource after the
   execution of this method.

9.8.6.  Example - COPY with Overwrite

   This example shows resource
   http://www.example.com/~fielding/index.html being copied to the
   location http://www.example.com/users/f/fielding/index.html.  The 204
   (No Content) status code indicates that the existing resource at the
   destination was overwritten.

   >>Request

     COPY /~fielding/index.html HTTP/1.1
     Host: www.example.com
     Destination: http://www.example.com/users/f/fielding/index.html

   >>Response

     HTTP/1.1 204 No Content

9.8.7.  Example - COPY with No Overwrite

   The following example shows the same copy operation being performed,
   but with the Overwrite header set to "F." A response of 412
   (Precondition Failed) is returned because the destination URL is
   already mapped to a resource.

   >>Request

     COPY /~fielding/index.html HTTP/1.1
     Host: www.example.com
     Destination: http://www.example.com/users/f/fielding/index.html
     Overwrite: F

Top      Up      ToC       Page 56 
   >>Response

     HTTP/1.1 412 Precondition Failed

9.8.8.  Example - COPY of a Collection

   >>Request

     COPY /container/ HTTP/1.1
     Host: www.example.com
     Destination: http://www.example.com/othercontainer/
     Depth: infinity

   >>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/othercontainer/R2/</d:href>
         <d:status>HTTP/1.1 423 Locked</d:status>
         <d:error><d:lock-token-submitted/></d:error>
       </d:response>
     </d:multistatus>

   The Depth header is unnecessary as the default behavior of COPY on a
   collection is to act as if a "Depth: infinity" header had been
   submitted.  In this example, most of the resources, along with the
   collection, were copied successfully.  However, the collection R2
   failed because the destination R2 is locked.  Because there was an
   error copying R2, none of R2's members were copied.  However, no
   errors were listed for those members due to the error minimization
   rules.

9.9.  MOVE Method

   The MOVE operation on a non-collection resource is the logical
   equivalent of a copy (COPY), followed by consistency maintenance
   processing, followed by a delete of the source, where all three
   actions are performed in a single operation.  The consistency
   maintenance step allows the server to perform updates caused by the
   move, such as updating all URLs, other than the Request-URI that
   identifies the source resource, to point to the new destination
   resource.

Top      Up      ToC       Page 57 
   The Destination header MUST be present on all MOVE methods and MUST
   follow all COPY requirements for the COPY part of the MOVE method.
   All WebDAV-compliant resources MUST support the MOVE method.

   Support for the MOVE method does not guarantee the ability to move a
   resource to a particular destination.  For example, separate programs
   may actually control different sets of resources on the same server.
   Therefore, it may not be possible to move a resource within a
   namespace that appears to belong to the same server.

   If a resource exists at the destination, the destination resource
   will be deleted as a side-effect of the MOVE operation, subject to
   the restrictions of the Overwrite header.

   This method is idempotent, but not safe (see Section 9.1 of
   [RFC2616]).  Responses to this method MUST NOT be cached.

9.9.1.  MOVE for Properties

   Live properties described in this document SHOULD be moved along with
   the resource, such that the resource has identically behaving live
   properties at the destination resource, but not necessarily with the
   same values.  Note that some live properties are defined such that
   the absence of the property has a specific meaning (e.g., a flag with
   one meaning if present, and the opposite if absent), and in these
   cases, a successful MOVE might result in the property being reported
   as "Not Found" in subsequent requests.  If the live properties will
   not work the same way at the destination, the server MAY fail the
   request.

   MOVE is frequently used by clients to rename a file without changing
   its parent collection, so it's not appropriate to reset all live
   properties that are set at resource creation.  For example, the DAV:
   creationdate property value SHOULD remain the same after a MOVE.

   Dead properties MUST be moved along with the resource.

9.9.2.  MOVE for Collections

   A MOVE with "Depth: infinity" instructs that the collection
   identified by the Request-URI be moved to the address specified in
   the Destination header, and all resources identified by its internal
   member URLs are to be moved to locations relative to it, recursively
   through all levels of the collection hierarchy.

   The MOVE method on a collection MUST act as if a "Depth: infinity"
   header was used on it.  A client MUST NOT submit a Depth header on a
   MOVE on a collection with any value but "infinity".

Top      Up      ToC       Page 58 
   Any headers included with MOVE MUST be applied in processing every
   resource to be moved with the exception of the Destination header.
   The behavior of the Destination header is the same as given for COPY
   on collections.

   When the MOVE method has completed processing, it MUST have created a
   consistent URL namespace at both the source and destination (see
   Section 5.1 for the definition of namespace consistency).  However,
   if an error occurs while moving an internal collection, the server
   MUST NOT move any resources identified by members of the failed
   collection (i.e., the server must skip the error-causing subtree), as
   this would create an inconsistent namespace.  In this case, after
   detecting the error, the move operation SHOULD try to finish as much
   of the original move as possible (i.e., the server should still
   attempt to move other subtrees and the resources identified by their
   members that are not descendants of an error-causing collection).
   So, for example, if an infinite-depth move is performed on collection
   /a/, which contains collections /a/b/ and /a/c/, and an error occurs
   moving /a/b/, an attempt should still be made to try moving /a/c/.
   Similarly, after encountering an error moving a non-collection
   resource as part of an infinite-depth move, the server SHOULD try to
   finish as much of the original move operation as possible.

   If an error occurs with a resource other than the resource identified
   in the Request-URI, then the response MUST be a 207 (Multi-Status),
   and the errored resource's URL MUST appear with the specific error.

   The 424 (Failed Dependency) status code SHOULD NOT be returned in the
   207 (Multi-Status) response from a MOVE method.  These errors can be
   safely omitted because the client will know that the progeny of a
   resource could not be moved when the client receives an error for the
   parent.  Additionally, 201 (Created)/204 (No Content) responses
   SHOULD NOT be returned as values in 207 (Multi-Status) responses from
   a MOVE.  These responses can be safely omitted because they are the
   default success codes.

9.9.3.  MOVE and the Overwrite Header

   If a resource exists at the destination and the Overwrite header is
   "T", then prior to performing the move, the server MUST perform a
   DELETE with "Depth: infinity" on the destination resource.  If the
   Overwrite header is set to "F", then the operation will fail.

Top      Up      ToC       Page 59 
9.9.4.  Status Codes

   In addition to the general status codes possible, the following
   status codes have specific applicability to MOVE:

   201 (Created) - The source resource was successfully moved, and a new
   URL mapping was created at the destination.

   204 (No Content) - The source resource was successfully moved to a
   URL that was already mapped.

   207 (Multi-Status) - Multiple resources were to be affected by the
   MOVE, but errors on some of them prevented the operation from taking
   place.  Specific error messages, together with the most appropriate
   of the source and destination URLs, appear in the body of the multi-
   status response.  For example, if a source resource was locked and
   could not be moved, then the source resource URL appears with the 423
   (Locked) status.

   403 (Forbidden) - Among many possible reasons for forbidding a MOVE
   operation, this status code is recommended for use when the source
   and destination resources are the same.

   409 (Conflict) - A resource cannot be created at the destination
   until one or more intermediate collections have been created.  The
   server MUST NOT create those intermediate collections automatically.
   Or, the server was unable to preserve the behavior of the live
   properties and still move the resource to the destination (see
   'preserved-live-properties' postcondition).

   412 (Precondition Failed) - A condition header failed.  Specific to
   MOVE, this could mean that the Overwrite header is "F" and the
   destination URL is already mapped to a resource.

   423 (Locked) - The source or the destination resource, the source or
   destination resource parent, or some resource within the source or
   destination collection, was locked.  This response SHOULD contain the
   'lock-token-submitted' precondition element.

   502 (Bad Gateway) - This may occur when the destination is on another
   server and the destination server refuses to accept the resource.
   This could also occur when the destination is on another sub-section
   of the same server namespace.

Top      Up      ToC       Page 60 
9.9.5.  Example - MOVE of a Non-Collection

   This example shows resource
   http://www.example.com/~fielding/index.html being moved to the
   location http://www.example.com/users/f/fielding/index.html.  The
   contents of the destination resource would have been overwritten if
   the destination URL was already mapped to a resource.  In this case,
   since there was nothing at the destination resource, the response
   code is 201 (Created).

   >>Request

     MOVE /~fielding/index.html HTTP/1.1
     Host: www.example.com
     Destination: http://www.example/users/f/fielding/index.html

   >>Response

     HTTP/1.1 201 Created
     Location: http://www.example.com/users/f/fielding/index.html

9.9.6.  Example - MOVE of a Collection

   >>Request

     MOVE /container/ HTTP/1.1
     Host: www.example.com
     Destination: http://www.example.com/othercontainer/
     Overwrite: F
     If: (<urn:uuid:fe184f2e-6eec-41d0-c765-01adc56e6bb4>)
        (<urn:uuid:e454f3f3-acdc-452a-56c7-00a5c91e4b77>)

   >>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/othercontainer/C2/</d:href>
         <d:status>HTTP/1.1 423 Locked</d:status>
         <d:error><d:lock-token-submitted/></d:error>
       </d:response>
     </d:multistatus>

Top      Up      ToC       Page 61 
   In this example, the client has submitted a number of lock tokens
   with the request.  A lock token will need to be submitted for every
   resource, both source and destination, anywhere in the scope of the
   method, that is locked.  In this case, the proper lock token was not
   submitted for the destination
   http://www.example.com/othercontainer/C2/.  This means that the
   resource /container/C2/ could not be moved.  Because there was an
   error moving /container/C2/, none of /container/C2's members were
   moved.  However, no errors were listed for those members due to the
   error minimization rules.  User agent authentication has previously
   occurred via a mechanism outside the scope of the HTTP protocol, in
   an underlying transport layer.

9.10.  LOCK Method

   The following sections describe the LOCK method, which is used to
   take out a lock of any access type and to refresh an existing lock.
   These sections on the LOCK method describe only those semantics that
   are specific to the LOCK method and are independent of the access
   type of the lock being requested.

   Any resource that supports the LOCK method MUST, at minimum, support
   the XML request and response formats defined herein.

   This method is neither idempotent nor safe (see Section 9.1 of
   [RFC2616]).  Responses to this method MUST NOT be cached.

9.10.1.  Creating a Lock on an Existing Resource

   A LOCK request to an existing resource will create a lock on the
   resource identified by the Request-URI, provided the resource is not
   already locked with a conflicting lock.  The resource identified in
   the Request-URI becomes the root of the lock.  LOCK method requests
   to create a new lock MUST have an XML request body.  The server MUST
   preserve the information provided by the client in the 'owner'
   element in the LOCK request.  The LOCK request MAY have a Timeout
   header.

   When a new lock is created, the LOCK response:

   o  MUST contain a body with the value of the DAV:lockdiscovery
      property in a prop XML element.  This MUST contain the full
      information about the lock just granted, while information about
      other (shared) locks is OPTIONAL.

   o  MUST include the Lock-Token response header with the token
      associated with the new lock.

Top      Up      ToC       Page 62 
9.10.2.  Refreshing Locks

   A lock is refreshed by sending a LOCK request to the URL of a
   resource within the scope of the lock.  This request MUST NOT have a
   body and it MUST specify which lock to refresh by using the 'If'
   header with a single lock token (only one lock may be refreshed at a
   time).  The request MAY contain a Timeout header, which a server MAY
   accept to change the duration remaining on the lock to the new value.
   A server MUST ignore the Depth header on a LOCK refresh.

   If the resource has other (shared) locks, those locks are unaffected
   by a lock refresh.  Additionally, those locks do not prevent the
   named lock from being refreshed.

   The Lock-Token header is not returned in the response for a
   successful refresh LOCK request, but the LOCK response body MUST
   contain the new value for the DAV:lockdiscovery property.

9.10.3.  Depth and Locking

   The Depth header may be used with the LOCK method.  Values other than
   0 or infinity MUST NOT be used with the Depth header on a LOCK
   method.  All resources that support the LOCK method MUST support the
   Depth header.

   A Depth header of value 0 means to just lock the resource specified
   by the Request-URI.

   If the Depth header is set to infinity, then the resource specified
   in the Request-URI along with all its members, all the way down the
   hierarchy, are to be locked.  A successful result MUST return a
   single lock token.  Similarly, if an UNLOCK is successfully executed
   on this token, all associated resources are unlocked.  Hence, partial
   success is not an option for LOCK or UNLOCK.  Either the entire
   hierarchy is locked or no resources are locked.

   If the lock cannot be granted to all resources, the server MUST
   return a Multi-Status response with a 'response' element for at least
   one resource that prevented the lock from being granted, along with a
   suitable status code for that failure (e.g., 403 (Forbidden) or 423
   (Locked)).  Additionally, if the resource causing the failure was not
   the resource requested, then the server SHOULD include a 'response'
   element for the Request-URI as well, with a 'status' element
   containing 424 Failed Dependency.

   If no Depth header is submitted on a LOCK request, then the request
   MUST act as if a "Depth:infinity" had been submitted.

Top      Up      ToC       Page 63 
9.10.4.  Locking Unmapped URLs

   A successful LOCK method MUST result in the creation of an empty
   resource that is locked (and that is not a collection) when a
   resource did not previously exist at that URL.  Later on, the lock
   may go away but the empty resource remains.  Empty resources MUST
   then appear in PROPFIND responses including that URL in the response
   scope.  A server MUST respond successfully to a GET request to an
   empty resource, either by using a 204 No Content response, or by
   using 200 OK with a Content-Length header indicating zero length

9.10.5.  Lock Compatibility Table

   The table below describes the behavior that occurs when a lock
   request is made on a resource.

     +--------------------------+----------------+-------------------+
     | Current State            | Shared Lock OK | Exclusive Lock OK |
     +--------------------------+----------------+-------------------+
     | None                     | True           | True              |
     | Shared Lock              | True           | False             |
     | Exclusive Lock           | False          | False*            |
     +--------------------------+----------------+-------------------+

   Legend: True = lock may be granted.  False = lock MUST NOT be
   granted. *=It is illegal for a principal to request the same lock
   twice.

   The current lock state of a resource is given in the leftmost column,
   and lock requests are listed in the first row.  The intersection of a
   row and column gives the result of a lock request.  For example, if a
   shared lock is held on a resource, and an exclusive lock is
   requested, the table entry is "false", indicating that the lock must
   not be granted.

9.10.6.  LOCK Responses

   In addition to the general status codes possible, the following
   status codes have specific applicability to LOCK:

   200 (OK) - The LOCK request succeeded and the value of the DAV:
   lockdiscovery property is included in the response body.

   201 (Created) - The LOCK request was to an unmapped URL, the request
   succeeded and resulted in the creation of a new resource, and the
   value of the DAV:lockdiscovery property is included in the response
   body.

Top      Up      ToC       Page 64 
   409 (Conflict) - A resource cannot be created at the destination
   until one or more intermediate collections have been created.  The
   server MUST NOT create those intermediate collections automatically.

   423 (Locked), potentially with 'no-conflicting-lock' precondition
   code - There is already a lock on the resource that is not compatible
   with the requested lock (see lock compatibility table above).

   412 (Precondition Failed), with 'lock-token-matches-request-uri'
   precondition code - The LOCK request was made with an If header,
   indicating that the client wishes to refresh the given lock.
   However, the Request-URI did not fall within the scope of the lock
   identified by the token.  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.

9.10.7.  Example - Simple Lock Request

   >>Request

     LOCK /workspace/webdav/proposal.doc HTTP/1.1
     Host: example.com
     Timeout: Infinite, Second-4100000000
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx
     Authorization: Digest username="ejw",
       realm="ejw@example.com", nonce="...",
       uri="/workspace/webdav/proposal.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>http://example.org/~ejw/contact.html</D:href>
       </D:owner>
     </D:lockinfo>

   >>Response

     HTTP/1.1 200 OK
     Lock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <D:prop xmlns:D="DAV:">

Top      Up      ToC       Page 65 
       <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>http://example.org/~ejw/contact.html</D:href>
           </D:owner>
           <D:timeout>Second-604800</D:timeout>
           <D:locktoken>
             <D:href
             >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
           </D:locktoken>
           <D:lockroot>
             <D:href
             >http://example.com/workspace/webdav/proposal.doc</D:href>
           </D:lockroot>
         </D:activelock>
       </D:lockdiscovery>
     </D:prop>


   This example shows the successful creation of an exclusive write lock
   on resource http://example.com/workspace/webdav/proposal.doc.  The
   resource http://example.org/~ejw/contact.html contains contact
   information for the creator of the lock.  The server has an activity-
   based timeout policy in place on this resource, which causes the lock
   to automatically be removed after 1 week (604800 seconds).  Note that
   the nonce, response, and opaque fields have not been calculated in
   the Authorization request header.

9.10.8.  Example - Refreshing a Write Lock

   >>Request

     LOCK /workspace/webdav/proposal.doc HTTP/1.1
     Host: example.com
     Timeout: Infinite, Second-4100000000
     If: (<urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>)
     Authorization: Digest username="ejw",
       realm="ejw@example.com", nonce="...",
       uri="/workspace/webdav/proposal.doc",
       response="...", opaque="..."

Top      Up      ToC       Page 66 
   >>Response

     HTTP/1.1 200 OK
     Content-Type: application/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>http://example.org/~ejw/contact.html</D:href>
           </D:owner>
           <D:timeout>Second-604800</D:timeout>
           <D:locktoken>
             <D:href
             >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
           </D:locktoken>
           <D:lockroot>
             <D:href
             >http://example.com/workspace/webdav/proposal.doc</D:href>
           </D:lockroot>
         </D:activelock>
       </D:lockdiscovery>
     </D:prop>


   This request would refresh the lock, attempting to reset the timeout
   to the new value specified in the timeout header.  Notice that the
   client asked for an infinite time out but the server choose to ignore
   the request.  In this example, the nonce, response, and opaque fields
   have not been calculated in the Authorization request header.

9.10.9.  Example - Multi-Resource Lock Request

   >>Request

     LOCK /webdav/ HTTP/1.1
     Host: example.com
     Timeout: Infinite, Second-4100000000
     Depth: infinity
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx
     Authorization: Digest username="ejw",
       realm="ejw@example.com", nonce="...",

Top      Up      ToC       Page 67 
       uri="/workspace/webdav/proposal.doc",
       response="...", opaque="..."

     <?xml version="1.0" encoding="utf-8" ?>
     <D:lockinfo xmlns:D="DAV:">
       <D:locktype><D:write/></D:locktype>
       <D:lockscope><D:exclusive/></D:lockscope>
       <D:owner>
         <D:href>http://example.org/~ejw/contact.html</D:href>
       </D:owner>
     </D:lockinfo>

   >>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://example.com/webdav/secret</D:href>
         <D:status>HTTP/1.1 403 Forbidden</D:status>
       </D:response>
       <D:response>
         <D:href>http://example.com/webdav/</D:href>
         <D:status>HTTP/1.1 424 Failed Dependency</D:status>
       </D:response>
     </D:multistatus>


   This example shows a request for an exclusive write lock on a
   collection and all its children.  In this request, the client has
   specified that it desires an infinite-length lock, if available,
   otherwise a timeout of 4.1 billion seconds, if available.  The
   request entity body contains the contact information for the
   principal taking out the lock -- in this case, a Web page URL.

   The error is a 403 (Forbidden) response on the resource
   http://example.com/webdav/secret.  Because this resource could not be
   locked, none of the resources were locked.  Note also that the a
   'response' element for the Request-URI itself has been included as
   required.

   In this example, the nonce, response, and opaque fields have not been
   calculated in the Authorization request header.

Top      Up      ToC       Page 68 
9.11.  UNLOCK Method

   The UNLOCK method removes the lock identified by the lock token in
   the Lock-Token request header.  The Request-URI MUST identify a
   resource within the scope of the lock.

   Note that use of the Lock-Token header to provide the lock token is
   not consistent with other state-changing methods, which all require
   an If header with the lock token.  Thus, the If header is not needed
   to provide the lock token.  Naturally, when the If header is present,
   it has its normal meaning as a conditional header.

   For a successful response to this method, the server MUST delete the
   lock entirely.

   If all resources that have been locked under the submitted lock token
   cannot be unlocked, then the UNLOCK request MUST fail.

   A successful response to an UNLOCK method does not mean that the
   resource is necessarily unlocked.  It means that the specific lock
   corresponding to the specified token no longer exists.

   Any DAV-compliant resource that supports the LOCK method MUST support
   the UNLOCK method.

   This method is idempotent, but not safe (see Section 9.1 of
   [RFC2616]).  Responses to this method MUST NOT be cached.

9.11.1.  Status Codes

   In addition to the general status codes possible, the following
   status codes have specific applicability to UNLOCK:

   204 (No Content) - Normal success response (rather than 200 OK, since
   200 OK would imply a response body, and an UNLOCK success response
   does not normally contain a body).

   400 (Bad Request) - No lock token was provided.

   403 (Forbidden) - The currently authenticated principal does not have
   permission to remove the lock.

   409 (Conflict), with 'lock-token-matches-request-uri' precondition -
   The resource was not locked, or the request was made to a Request-URI
   that was not within the scope of the lock.

Top      Up      ToC       Page 69 
9.11.2.  Example - UNLOCK

   >>Request

     UNLOCK /workspace/webdav/info.doc HTTP/1.1
     Host: example.com
     Lock-Token: <urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7>
     Authorization: Digest username="ejw"
       realm="ejw@example.com", nonce="...",
       uri="/workspace/webdav/proposal.doc",
       response="...", opaque="..."

   >>Response

     HTTP/1.1 204 No Content

   In this example, the lock identified by the lock token
   "urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully
   removed from the resource
   http://example.com/workspace/webdav/info.doc.  If this lock included
   more than just one resource, the lock is removed from all resources
   included in the lock.

   In this example, the nonce, response, and opaque fields have not been
   calculated in the Authorization request header.

10.  HTTP Headers for Distributed Authoring

   All DAV headers follow the same basic formatting rules as HTTP
   headers.  This includes rules like line continuation and how to
   combine (or separate) multiple instances of the same header using
   commas.

   WebDAV adds two new conditional headers to the set defined in HTTP:
   the If and Overwrite headers.

10.1.  DAV Header

    DAV              = "DAV" ":" #( compliance-class )
    compliance-class = ( "1" | "2" | "3" | extend )
    extend           = Coded-URL | token
                       ; token is defined in RFC 2616, Section 2.2
    Coded-URL        = "<" absolute-URI ">"
                       ; No linear whitespace (LWS) allowed in Coded-URL
                       ; absolute-URI defined in RFC 3986, Section 4.3

Top      Up      ToC       Page 70 
   This general-header appearing in the response indicates that the
   resource supports the DAV schema and protocol as specified.  All DAV-
   compliant resources MUST return the DAV header with compliance-class
   "1" on all OPTIONS responses.  In cases where WebDAV is only
   supported in part of the server namespace, an OPTIONS request to non-
   WebDAV resources (including "/") SHOULD NOT advertise WebDAV support.

   The value is a comma-separated list of all compliance class
   identifiers that the resource supports.  Class identifiers may be
   Coded-URLs or tokens (as defined by [RFC2616]).  Identifiers can
   appear in any order.  Identifiers that are standardized through the
   IETF RFC process are tokens, but other identifiers SHOULD be Coded-
   URLs to encourage uniqueness.

   A resource must show class 1 compliance if it shows class 2 or 3
   compliance.  In general, support for one compliance class does not
   entail support for any other, and in particular, support for
   compliance class 3 does not require support for compliance class 2.
   Please refer to Section 18 for more details on compliance classes
   defined in this specification.

   Note that many WebDAV servers do not advertise WebDAV support in
   response to "OPTIONS *".

   As a request header, this header allows the client to advertise
   compliance with named features when the server needs that
   information.  Clients SHOULD NOT send this header unless a standards
   track specification requires it.  Any extension that makes use of
   this as a request header will need to carefully consider caching
   implications.

10.2.  Depth Header

      Depth = "Depth" ":" ("0" | "1" | "infinity")

   The Depth request header is used with methods executed on resources
   that could potentially have internal members to indicate whether the
   method is to be applied only to the resource ("Depth: 0"), to the
   resource and its internal members only ("Depth: 1"), or the resource
   and all its members ("Depth: infinity").

   The Depth header is only supported if a method's definition
   explicitly provides for such support.

   The following rules are the default behavior for any method that
   supports the Depth header.  A method may override these defaults by
   defining different behavior in its definition.

Top      Up      ToC       Page 71 
   Methods that support the Depth header may choose not to support all
   of the header's values and may define, on a case-by-case basis, the
   behavior of the method if a Depth header is not present.  For
   example, the MOVE method only supports "Depth: infinity", and if a
   Depth header is not present, it will act as if a "Depth: infinity"
   header had been applied.

   Clients MUST NOT rely upon methods executing on members of their
   hierarchies in any particular order or on the execution being atomic
   unless the particular method explicitly provides such guarantees.

   Upon execution, a method with a Depth header will perform as much of
   its assigned task as possible and then return a response specifying
   what it was able to accomplish and what it failed to do.

   So, for example, an attempt to COPY a hierarchy may result in some of
   the members being copied and some not.

   By default, the Depth header does not interact with other headers.
   That is, each header on a request with a Depth header MUST be applied
   only to the Request-URI if it applies to any resource, unless
   specific Depth behavior is defined for that header.

   If a source or destination resource within the scope of the Depth
   header is locked in such a way as to prevent the successful execution
   of the method, then the lock token for that resource MUST be
   submitted with the request in the If request header.

   The Depth header only specifies the behavior of the method with
   regards to internal members.  If a resource does not have internal
   members, then the Depth header MUST be ignored.

10.3.  Destination Header

   The Destination request header specifies the URI that identifies a
   destination resource for methods such as COPY and MOVE, which take
   two URIs as parameters.

      Destination = "Destination" ":" Simple-ref


   If the Destination value is an absolute-URI (Section 4.3 of
   [RFC3986]), it may name a different server (or different port or
   scheme).  If the source server cannot attempt a copy to the remote
   server, it MUST fail the request.  Note that copying and moving
   resources to remote servers is not fully defined in this
   specification (e.g., specific error conditions).

Top      Up      ToC       Page 72 
   If the Destination value is too long or otherwise unacceptable, the
   server SHOULD return 400 (Bad Request), ideally with helpful
   information in an error body.

10.4.  If Header

   The If request header is intended to have similar functionality to
   the If-Match header defined in Section 14.24 of [RFC2616].  However,
   the If header handles any state token as well as ETags.  A typical
   example of a state token is a lock token, and lock tokens are the
   only state tokens defined in this specification.

10.4.1.  Purpose

   The If header has two distinct purposes:

   o  The first purpose is to make a request conditional by supplying a
      series of state lists with conditions that match tokens and ETags
      to a specific resource.  If this header is evaluated and all state
      lists fail, then the request MUST fail with a 412 (Precondition
      Failed) status.  On the other hand, the request can succeed only
      if one of the described state lists succeeds.  The success
      criteria for state lists and matching functions are defined in
      Sections 10.4.3 and 10.4.4.

   o  Additionally, the mere fact that a state token appears in an If
      header means that it has been "submitted" with the request.  In
      general, this is used to indicate that the client has knowledge of
      that state token.  The semantics for submitting a state token
      depend on its type (for lock tokens, please refer to Section 6).

   Note that these two purposes need to be treated distinctly: a state
   token counts as being submitted independently of whether the server
   actually has evaluated the state list it appears in, and also
   independently of whether or not the condition it expressed was found
   to be true.

10.4.2.  Syntax

     If = "If" ":" ( 1*No-tag-list | 1*Tagged-list )

     No-tag-list = List
     Tagged-list = Resource-Tag 1*List

     List = "(" 1*Condition ")"
     Condition = ["Not"] (State-token | "[" entity-tag "]")
     ; entity-tag: see Section 3.11 of [RFC2616]
     ; No LWS allowed between "[", entity-tag and "]"

Top      Up      ToC       Page 73 
     State-token = Coded-URL

     Resource-Tag = "<" Simple-ref ">"
     ; Simple-ref: see Section 8.3
     ; No LWS allowed in Resource-Tag

   The syntax distinguishes between untagged lists ("No-tag-list") and
   tagged lists ("Tagged-list").  Untagged lists apply to the resource
   identified by the Request-URI, while tagged lists apply to the
   resource identified by the preceding Resource-Tag.

   A Resource-Tag applies to all subsequent Lists, up to the next
   Resource-Tag.

   Note that the two list types cannot be mixed within an If header.
   This is not a functional restriction because the No-tag-list syntax
   is just a shorthand notation for a Tagged-list production with a
   Resource-Tag referring to the Request-URI.

   Each List consists of one or more Conditions.  Each Condition is
   defined in terms of an entity-tag or state-token, potentially negated
   by the prefix "Not".

   Note that the If header syntax does not allow multiple instances of
   If headers in a single request.  However, the HTTP header syntax
   allows extending single header values across multiple lines, by
   inserting a line break followed by whitespace (see [RFC2616], Section
   4.2).

10.4.3.  List Evaluation

   A Condition that consists of a single entity-tag or state-token
   evaluates to true if the resource matches the described state (where
   the individual matching functions are defined below in
   Section 10.4.4).  Prefixing it with "Not" reverses the result of the
   evaluation (thus, the "Not" applies only to the subsequent entity-tag
   or state-token).

   Each List production describes a series of conditions.  The whole
   list evaluates to true if and only if each condition evaluates to
   true (that is, the list represents a logical conjunction of
   Conditions).

   Each No-tag-list and Tagged-list production may contain one or more
   Lists.  They evaluate to true if and only if any of the contained
   lists evaluates to true (that is, if there's more than one List, that
   List sequence represents a logical disjunction of the Lists).

Top      Up      ToC       Page 74 
   Finally, the whole If header evaluates to true if and only if at
   least one of the No-tag-list or Tagged-list productions evaluates to
   true.  If the header evaluates to false, the server MUST reject the
   request with a 412 (Precondition Failed) status.  Otherwise,
   execution of the request can proceed as if the header wasn't present.

10.4.4.  Matching State Tokens and ETags

   When performing If header processing, the definition of a matching
   state token or entity tag is as follows:

   Identifying a resource: The resource is identified by the URI along
   with the token, in tagged list production, or by the Request-URI in
   untagged list production.

   Matching entity tag: Where the entity tag matches an entity tag
   associated with the identified resource.  Servers MUST use either the
   weak or the strong comparison function defined in Section 13.3.3 of
   [RFC2616].

   Matching state token: Where there is an exact match between the state
   token in the If header and any state token on the identified
   resource.  A lock state token is considered to match if the resource
   is anywhere in the scope of the lock.

   Handling unmapped URLs: For both ETags and state tokens, treat as if
   the URL identified a resource that exists but does not have the
   specified state.

10.4.5.  If Header and Non-DAV-Aware Proxies

   Non-DAV-aware proxies will not honor the If header, since they will
   not understand the If header, and HTTP requires non-understood
   headers to be ignored.  When communicating with HTTP/1.1 proxies, the
   client MUST use the "Cache-Control: no-cache" request header so as to
   prevent the proxy from improperly trying to service the request from
   its cache.  When dealing with HTTP/1.0 proxies, the "Pragma: no-
   cache" request header MUST be used for the same reason.

   Because in general clients may not be able to reliably detect non-
   DAV-aware intermediates, they are advised to always prevent caching
   using the request directives mentioned above.

Top      Up      ToC       Page 75 
10.4.6.  Example - No-tag Production

     If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
       ["I am an ETag"])
       (["I am another ETag"])

   The previous header would require that the resource identified in the
   Request-URI be locked with the specified lock token and be in the
   state identified by the "I am an ETag" ETag or in the state
   identified by the second ETag "I am another ETag".

   To put the matter more plainly one can think of the previous If
   header as expressing the condition below:

     (
       is-locked-with(urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2) AND
       matches-etag("I am an ETag")
     )
     OR
     (
       matches-etag("I am another ETag")
     )

10.4.7.  Example - Using "Not" with No-tag Production

     If: (Not <urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
     <urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092>)

   This If header requires that the resource must not be locked with a
   lock having the lock token
   urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 and must be locked by a
   lock with the lock token
   urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092.

10.4.8.  Example - Causing a Condition to Always Evaluate to True

   There may be cases where a client wishes to submit state tokens, but
   doesn't want the request to fail just because the state token isn't
   current anymore.  One simple way to do this is to include a Condition
   that is known to always evaluate to true, such as in:

     If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)
       (Not <DAV:no-lock>)

   "DAV:no-lock" is known to never represent a current lock token.  Lock
   tokens are assigned by the server, following the uniqueness
   requirements described in Section 6.5, therefore cannot use the
   "DAV:" scheme.  Thus, by applying "Not" to a state token that is

Top      Up      ToC       Page 76 
   known not to be current, the Condition always evaluates to true.
   Consequently, the whole If header will always evaluate to true, and
   the lock token urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 will be
   submitted in any case.

10.4.9.  Example - Tagged List If Header in COPY

   >>Request

     COPY /resource1 HTTP/1.1
     Host: www.example.com
     Destination: /resource2
     If: </resource1>
       (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
       [W/"A weak ETag"]) (["strong ETag"])

   In this example, http://www.example.com/resource1 is being copied to
   http://www.example.com/resource2.  When the method is first applied
   to http://www.example.com/resource1, resource1 must be in the state
   specified by "(<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2> [W/"A
   weak ETag"]) (["strong ETag"])".  That is, either it must be locked
   with a lock token of "urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2"
   and have a weak entity tag W/"A weak ETag" or it must have a strong
   entity tag "strong ETag".

10.4.10.  Example - Matching Lock Tokens with Collection Locks

     DELETE /specs/rfc2518.txt HTTP/1.1
     Host: www.example.com
     If: <http://www.example.com/specs/>
       (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)

   For this example, the lock token must be compared to the identified
   resource, which is the 'specs' collection identified by the URL in
   the tagged list production.  If the 'specs' collection is not locked
   by a lock with the specified lock token, the request MUST fail.
   Otherwise, this request could succeed, because the If header
   evaluates to true, and because the lock token for the lock affecting
   the affected resource has been submitted.

10.4.11.  Example - Matching ETags on Unmapped URLs

   Consider a collection "/specs" that does not contain the member
   "/specs/rfc2518.doc".  In this case, the If header

     If: </specs/rfc2518.doc> (["4217"])

Top      Up      ToC       Page 77 
   will evaluate to false (the URI isn't mapped, thus the resource
   identified by the URI doesn't have an entity matching the ETag
   "4217").

   On the other hand, an If header of

     If: </specs/rfc2518.doc> (Not ["4217"])

   will consequently evaluate to true.

   Note that, as defined above in Section 10.4.4, the same
   considerations apply to matching state tokens.



(page 77 continued on part 4)

Next RFC Part