1This document describes how to add support for extended webdav features (locking, 2properties etc.) to your webdav-aware application. 3Author: Hamish Rodda, rodda@kde.org 4Version: 0.3 5 6Compatible with (tested on): 7Apache + mod_dav version 1 and 2 8Zope 9Silverstream webdav server 10 11Applications supporting extended webdav features 12 (include name and contact email, in case the interface has to change): 13[none currently] 14 15Much of the info here is elaborated by rfc #2518; the rest can be understood by reading 16davPropStat() in http.cc, specifically the setMetaData() calls. 17 18Extended information is transferred via kio's metadata system... 19 20=== MISCELLANEOUS === 21Display Names (names suitable for presentation to the user) are passed as the metadata 22element davDisplayName. 23 24Source template locations (href, usually an absolute URL w/o host info) 25are passed as element davSource. 26 27Content languages are passed as element davContentLanguage. 28 29Extra webdav headers are passed as metadata element davHeader 30 31For doing a webdav SEARCH, use listDir() and set the metadata element 32davSearchQuery to the search query. The root element of this query should be like 33<d:basicsearch> or <d:sql>. 34 35For doing a generic webdav action, call a special request, with 36the following data: 37int, value 7 (WEBDAV generic) 38QUrl url 39int method - the HTTP/WEBDAV method to call 40Send the xml request and receive the xml response in the usual way. 41 42=== CREATING A LOCK === 43To create a lock, call a special request, with the following data: 44 45int, value 5 (LOCK request) 46QUrl url - the location of the resource to lock 47QString scope - the scope of the lock, currently "exclusive" or "shared" 48QString type - the type of the lock, currently only "write" 49QString owner (optional) - owner contact details (url) 50 51Additionally, the lock timeout requested from the server may be altered from the default 52of Infinity by setting the metadata "davTimeout" to the number of seconds, or 0 for 53infinity. 54 55=== REMOVING A LOCK === 56To remove a lock, call a special request, with the following data: 57 58int, value 5 (LOCK request) 59QUrl url - the location of the resource to unlock 60 61metadata required: 62davLockToken - the lock token to remove 63 64and, of course, any other lock information as below required for the operation 65to succeed. 66 67=== SETTING LOCK INFORMATION === 68To provide lock data so that urls can be accessed, you need to pass the following metadata: 69davLockCount: (uint) the number of locks you are providing 70davLockToken%1: (string) the token 71(optional) davLockURL%1: (string) the absolute URL specified by the lock token 72(optional) davLockNot%1: (value ignored) the presence of this meta key negates the lock 73 (ie. requires the lock to not be set) 74 75Example data: 76============= 77davLockCount: 2 78davLockToken1: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76A 79davLockNot1: (value ignored) 80davLockToken2: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76B 81davLockURL2: http://www.foo.bar/container2/ 82 83 84=== RECEIVING LOCK INFORMATION === 85For each file, stat/listdir always returns two pieces of information: 86 87davSupportedLockCount: (uint) the number of lock types discovered for this resource. 88davLockCount: (uint) the number of locks discovered on this resource. 89 90for each count, additional information is returned: 91 92=================== 93Information about the locks on a resource: 94 95davLockCount: %1 (the number of locks to be described, as below) 96*** Required items *** 97davLockScope%1 - The scope of this lock. May be exclusive, shared, or a custom type. 98davLockType%1 - The type of the lock. 99davLockDepth%1 - The depth to which this lock applies 100 (0=only this resource, 1=this collection, infinity=applies recursively) 101 102*** Optional items *** 103davLockOwner%1 - The owner of this lock. 104davLockTimeout%1 - The timeout parameter. Possibilities: see section 9.8, rfc #2518 105davLockToken%1 - The token which iden 106 107=================== 108Information about the lock types supported by the resource 109 110davSupportedLockCount: %1 (the number of locks types to be described, as below) 111 112davSupportedLockScope%1 - The scope of the lock (exclusive, shared, other custom type) 113davSupportedLockType%1 - The type of the lock (webdav 1.0 supports only the "write" type) 114=================== 115 116Example Metadata which would be supplied if the response was the example XML below: 117 118davSupportedLockCount: 2 119davLockCount: 2 120davLockScope1: exclusive 121davLockType1: write 122davLockDepth1: 0 123davLockOwner1: Jane Smith 124davLockTimeout1: infinite 125davLockToken1: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76A 126davLockScope2: shared 127davLockType2: write 128davLockDepth2: 1 129davLockOwner2: John Doe 130davLockToken2: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76B 131davSupportedLockScope1: exclusive 132davSupportedLockType1: write 133davSupportedLockScope2: shared 134davSupportedLockType2: write 135 136 137(example XML:) 138 139 <?xml version="1.0" encoding="utf-8" ?> 140 <D:multistatus xmlns:D='DAV:'> 141 <D:response> 142 <D:href>http://www.foo.bar/container/</D:href> 143 <D:propstat> 144 <D:prop> 145 <D:lockdiscovery> 146 <D:activelock> 147 <D:locktype><D:write/></D:locktype> 148 <D:lockscope><D:exclusive/></D:lockscope> 149 <D:depth>0</D:depth> 150 <D:owner>Jane Smith</D:owner> 151 <D:timeout>Infinite</D:timeout> 152 <D:locktoken> 153 <D:href> 154 opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76A 155 </D:href> 156 </D:locktoken> 157 </D:activelock> 158 <D:activelock> 159 <D:locktype><D:write/></D:locktype> 160 <D:lockscope><D:shared/></D:lockscope> 161 <D:depth>1</D:depth> 162 <D:owner>John Doe</D:owner> 163 <D:locktoken> 164 <D:href> 165 opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76B 166 </D:href> 167 </D:locktoken> 168 </D:activelock> 169 </D:lockdiscovery> 170 <D:supportedlock> 171 <D:lockentry> 172 <D:lockscope><D:exclusive/></D:lockscope> 173 <D:locktype><D:write/></D:locktype> 174 </D:lockentry> 175 <D:lockentry> 176 <D:lockscope><D:shared/></D:lockscope> 177 <D:locktype><D:write/></D:locktype> 178 </D:lockentry> 179 </D:supportedlock> 180 </D:prop> 181 <D:status>HTTP/1.1 200 OK</D:status> 182 </D:propstat> 183 </D:response> 184 </D:multistatus> 185