kioworkers/http/README.webdav

0001 This document describes how to add support for extended webdav features (locking,
0002 properties etc.) to your webdav-aware application.
0003 Author: Hamish Rodda, rodda@kde.org
0004 Version: 0.3
0005
0006 Compatible with (tested on):
0007 Apache + mod_dav version 1 and 2
0008 Zope
0009 Silverstream webdav server
0010
0011 Applications supporting extended webdav features
0012   (include name and contact email, in case the interface has to change):
0013 [none currently]
0014
0015 Much of the info here is elaborated by rfc #2518; the rest can be understood by reading
0016 davPropStat() in http.cc, specifically the setMetaData() calls.
0017
0018 Extended information is transferred via kio's metadata system...
0019
0020 === MISCELLANEOUS ===
0021 Display Names (names suitable for presentation to the user) are passed as the metadata
0022 element davDisplayName.
0023
0024 Source template locations (href, usually an absolute URL w/o host info)
0025 are passed as element davSource.
0026
0027 Content languages are passed as element davContentLanguage.
0028
0029 Extra webdav headers are passed as metadata element davHeader
0030
0031 For doing a webdav SEARCH, use listDir() and set the metadata element
0032 davSearchQuery to the search query. The root element of this query should be like
0033 <d:basicsearch> or <d:sql>.
0034
0035 For doing a generic webdav action, call a special request, with
0036 the following data:
0037 int, value 7 (WEBDAV generic)
0038 QUrl url
0039 int method - the HTTP/WEBDAV method to call
0040 Send the xml request and receive the xml response in the usual way.
0041
0042 === CREATING A LOCK ===
0043 To create a lock, call a special request, with the following data:
0044
0045 int, value 5 (LOCK request)
0046 QUrl url - the location of the resource to lock
0047 QString scope - the scope of the lock, currently "exclusive" or "shared"
0048 QString type - the type of the lock, currently only "write"
0049 QString owner (optional) - owner contact details (url)
0050
0051 Additionally, the lock timeout requested from the server may be altered from the default
0052 of Infinity by setting the metadata "davTimeout" to the number of seconds, or 0 for
0053 infinity.
0054
0055 === REMOVING A LOCK ===
0056 To remove a lock, call a special request, with the following data:
0057
0058 int, value 5 (LOCK request)
0059 QUrl url - the location of the resource to unlock
0060
0061 metadata required:
0062 davLockToken - the lock token to remove
0063
0064 and, of course, any other lock information as below required for the operation
0065 to succeed.
0066
0067 === SETTING LOCK INFORMATION ===
0068 To provide lock data so that urls can be accessed, you need to pass the following metadata:
0069 davLockCount: (uint) the number of locks you are providing
0070 davLockToken%1: (string) the token
0071 (optional) davLockURL%1: (string) the absolute URL specified by the lock token
0072 (optional) davLockNot%1: (value ignored) the presence of this meta key negates the lock
0073                                           (ie. requires the lock to not be set)
0074
0075 Example data:
0076 =============
0077 davLockCount: 2
0078 davLockToken1: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76A
0079 davLockNot1: (value ignored)
0080 davLockToken2: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76B
0081 davLockURL2: http://www.foo.bar/container2/
0082
0083
0084 === RECEIVING LOCK INFORMATION ===
0085 For each file, stat/listdir always returns two pieces of information:
0086
0087 davSupportedLockCount: (uint) the number of lock types discovered for this resource.
0088 davLockCount: (uint) the number of locks discovered on this resource.
0089
0090 for each count, additional information is returned:
0091
0092 ===================
0093 Information about the locks on a resource:
0094
0095 davLockCount: %1 (the number of locks to be described, as below)
0096 *** Required items ***
0097 davLockScope%1 - The scope of this lock. May be exclusive, shared, or a custom type.
0098 davLockType%1 - The type of the lock.
0099 davLockDepth%1 - The depth to which this lock applies
0100                     (0=only this resource, 1=this collection, infinity=applies recursively)
0101
0102 *** Optional items ***
0103 davLockOwner%1 - The owner of this lock.
0104 davLockTimeout%1 - The timeout parameter. Possibilities: see section 9.8, rfc #2518
0105 davLockToken%1 - The token which iden
0106
0107 ===================
0108 Information about the lock types supported by the resource
0109
0110 davSupportedLockCount: %1 (the number of locks types to be described, as below)
0111
0112 davSupportedLockScope%1 - The scope of the lock (exclusive, shared, other custom type)
0113 davSupportedLockType%1 - The type of the lock (webdav 1.0 supports only the "write" type)
0114 ===================
0115
0116 Example Metadata which would be supplied if the response was the example XML below:
0117
0118 davSupportedLockCount: 2
0119 davLockCount: 2
0120 davLockScope1: exclusive
0121 davLockType1: write
0122 davLockDepth1: 0
0123 davLockOwner1: Jane Smith
0124 davLockTimeout1: infinite
0125 davLockToken1: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76A
0126 davLockScope2: shared
0127 davLockType2: write
0128 davLockDepth2: 1
0129 davLockOwner2: John Doe
0130 davLockToken2: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76B
0131 davSupportedLockScope1: exclusive
0132 davSupportedLockType1: write
0133 davSupportedLockScope2: shared
0134 davSupportedLockType2: write
0135
0136
0137 (example XML:)
0138
0139    <?xml version="1.0" encoding="utf-8" ?>
0140    <D:multistatus xmlns:D='DAV:'>
0141      <D:response>
0142           <D:href>http://www.foo.bar/container/</D:href>
0143           <D:propstat>
0144                <D:prop>
0145                     <D:lockdiscovery>
0146                          <D:activelock>
0147                               <D:locktype><D:write/></D:locktype>
0148                               <D:lockscope><D:exclusive/></D:lockscope>
0149                               <D:depth>0</D:depth>
0150                               <D:owner>Jane Smith</D:owner>
0151                               <D:timeout>Infinite</D:timeout>
0152                               <D:locktoken>
0153                                    <D:href>
0154                opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76A
0155                                    </D:href>
0156                               </D:locktoken>
0157                          </D:activelock>
0158                          <D:activelock>
0159                               <D:locktype><D:write/></D:locktype>
0160                               <D:lockscope><D:shared/></D:lockscope>
0161                               <D:depth>1</D:depth>
0162                               <D:owner>John Doe</D:owner>
0163                               <D:locktoken>
0164                                    <D:href>
0165                opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76B
0166                                    </D:href>
0167                               </D:locktoken>
0168                          </D:activelock>
0169                     </D:lockdiscovery>
0170                     <D:supportedlock>
0171                          <D:lockentry>
0172                               <D:lockscope><D:exclusive/></D:lockscope>
0173                               <D:locktype><D:write/></D:locktype>
0174                          </D:lockentry>
0175                          <D:lockentry>
0176                               <D:lockscope><D:shared/></D:lockscope>
0177                               <D:locktype><D:write/></D:locktype>
0178                          </D:lockentry>
0179                     </D:supportedlock>
0180                </D:prop>
0181                <D:status>HTTP/1.1 200 OK</D:status>
0182           </D:propstat>
0183      </D:response>
0184    </D:multistatus>