summaryrefslogtreecommitdiffstats
path: root/tdeioslave/http/README.webdav
blob: 7d0d2528b1e884322615ecc240640d66f9373943 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
This document describes how to add support for extended webdav features (locking,
properties etc.) to your webdav-aware application.
Author: Hamish Rodda, rodda@kde.org
Version: 0.3

Compatable with (tested on):
Apache + mod_dav version 1 and 2
Zope
Silverstream webdav server

Applications supporting extended webdav features
  (include name and contact email, in case the interface has to change):
[none currently]

Much of the info here is elaborated by rfc #2518; the rest can be understood by reading
davPropStat() in http.cpp, specifically the setMetaData() calls.

Extended information is transferred via tdeio's metadata system...

=== MISCELLANEOUS ===
Display Names (names suitable for presentation to the user) are passed as the metadata
element davDisplayName.

Source template locations (href, usually an absolute URL w/o host info)
are passed as element davSource.

Content languages are passed as element davContentLanguage.

Extra webdav headers are passed as metadata element davHeader

For doing a webdav SEARCH, use listDir() and set the metadata element
davSearchQuery to the search query. The root element of this query should be like
<d:basicsearch> or <d:sql>.

For doing a generic webdav action, call a special request, with
the following data:
int, value 7 (WEBDAV generic)
KURL url
int method - the HTTP/WEBDAV method to call
Send the xml request and receive the xml response in the usual way.

=== CREATING A LOCK ===
To create a lock, call a special request, with the following data:

int, value 5 (LOCK request)
KURL url - the location of the resource to lock
TQString scope - the scope of the lock, currently "exclusive" or "shared"
TQString type - the type of the lock, currently only "write"
TQString owner (optional) - owner contact details (url)

Additionally, the lock timeout requested from the server may be altered from the default
of Infinity by setting the metadata "davTimeout" to the number of seconds, or 0 for
infinity.

=== REMOVING A LOCK ===
To remove a lock, call a special request, with the following data:

int, value 5 (LOCK request)
KURL url - the location of the resource to unlock

metadata required:
davLockToken - the lock token to remove

and, of course, any other lock information as below required for the operation
to suceed.

=== SETTING LOCK INFORMATION ===
To provide lock data so that urls can be accessed, you need to pass the following metadata:
davLockCount: (uint) the number of locks you are providing
davLockToken%1: (string) the token
(optional) davLockURL%1: (string) the absolute URL specified by the lock token
(optional) davLockNot%1: (value ignored) the presence of this meta key negates the lock
                                          (ie. requires the lock to not be set)

Example data:
=============
davLockCount: 2
davLockToken1: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76A
davLockNot1: (value ignored)
davLockToken2: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76B
davLockURL2: http://www.foo.bar/container2/


=== RECEIVING LOCK INFORMATION ===
For each file, stat/listdir always returns two pieces of information:

davSupportedLockCount: (uint) the number of lock types discovered for this resource.
davLockCount: (uint) the number of locks discovered on this resource.

for each count, additional information is returned:

===================
Information about the locks on a resource:

davLockCount: %1 (the number of locks to be described, as below)
*** Required items ***
davLockScope%1 - The scope of this lock. May be exclusive, shared, or a custom type.
davLockType%1 - The type of the lock.
davLockDepth%1 - The depth to which this lock applies
                    (0=only this resource, 1=this collection, infinity=applies recursively)

*** Optional items ***
davLockOwner%1 - The owner of this lock.
davLockTimeout%1 - The timeout parameter. Possibilities: see section 9.8, rfc #2518
davLockToken%1 - The token which iden

===================
Information about the lock types supported by the resource

davSupportedLockCount: %1 (the number of locks types to be described, as below)

davSupportedLockScope%1 - The scope of the lock (exclusive, shared, other custom type)
davSupportedLockType%1 - The type of the lock (webdav 1.0 supports only the "write" type)
===================

Example Metadata which would be supplied if the response was the example XML below:

davSupportedLockCount: 2
davLockCount: 2
davLockScope1: exclusive
davLockType1: write
davLockDepth1: 0
davLockOwner1: Jane Smith
davLockTimeout1: infinite
davLockToken1: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76A
davLockScope2: shared
davLockType2: write
davLockDepth2: 1
davLockOwner2: John Doe
davLockToken2: opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76B
davSupportedLockScope1: exclusive
davSupportedLockType1: write
davSupportedLockScope2: shared
davSupportedLockType2: write


(example XML:)

   <?xml version="1.0" encoding="utf-8" ?>
   <D:multistatus xmlns:D='DAV:'>
     <D:response>
          <D:href>http://www.foo.bar/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>
               opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76A
                                   </D:href>
                              </D:locktoken>
                         </D:activelock>
                         <D:activelock>
                              <D:locktype><D:write/></D:locktype>
                              <D:lockscope><D:shared/></D:lockscope>
                              <D:depth>1</D:depth>
                              <D:owner>John Doe</D:owner>
                              <D:locktoken>
                                   <D:href>
               opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76B
                                   </D:href>
                              </D:locktoken>
                         </D:activelock>
                    </D:lockdiscovery>
                    <D:supportedlock>
                         <D:lockentry>
                              <D:lockscope><D:exclusive/></D:lockscope>
                              <D:locktype><D:write/></D:locktype>
                         </D:lockentry>
                         <D:lockentry>
                              <D:lockscope><D:shared/></D:lockscope>
                              <D:locktype><D:write/></D:locktype>
                         </D:lockentry>
                    </D:supportedlock>
               </D:prop>
               <D:status>HTTP/1.1 200 OK</D:status>
          </D:propstat>
     </D:response>
   </D:multistatus>