1HTTP::DAV::Resource(3)User Contributed Perl DocumentationHTTP::DAV::Resource(3)
2
6 HTTP::DAV::Resource - Represents and interfaces with WebDAV Resources
7
9 Sample
10
12 Description here
13
15 new Returns a new resource represented by the URI.
16 $r = HTTP::DAV::Resource->new(
18 -uri => $uri,
19 -LockedResourceList => $locks,
20 -Comms => $comms
21 -Client => $dav_client
22 );
23 On creation a Resource object needs 2 other objects passed in:
25 1. a "ResourceList" Object. This list will be added to if you lock
27 this Resource.
28 2. a "Comms" Object. This object will be used for HTTP
30 communication.
31 2. a "HTTP::DAV" Object. This object is where all locks are stored
33
35 get/GET
36 Performs an HTTP GET and returns a DAV::Response object.
37 $response = $resource->get;
39 print $resource->get_content if ($response->is_success);
40 put/PUT
42 Performs an HTTP PUT and returns a DAV::Response object.
43 $response = $resource->put( $string );
45 $string is be passed as the body.
47 e.g.
49 $response = $resource->put($string);
50 print $resource->get_content if ($response->is_success);
51 Will use a Lock header if this resource was previously locked.
53 copy
55 Not implemented
56 move
58 Not implemented
59 delete
61 Performs an HTTP DELETE and returns a DAV::Response object.
62 $response = $resource->delete;
64 print "Delete successful" if ($response->is_success);
65 Will use a Lock header if this resource was previously locked.
67 options
69 Performs an HTTP OPTIONS and returns a DAV::Response object.
70 $response = $resource->options;
72 print "Yay for PUT!" if $resource->is_option("PUT");
73 mkcol
75 Performs a WebDAV MKCOL request and returns a DAV::Response object.
76 $response = $resource->mkcol;
78 print "MKCOL successful" if ($response->is_success);
79 Will use a Lock header if this resource was previously locked.
81 proppatch
83 xxx
84 propfind
86 Performs a WebDAV PROPFIND request and returns a DAV::Response
87 object.
88 $response = $resource->propfind;
90 if ($response->is_success) {
91 print "PROPFIND successful\n";
92 print $resource->get_property("displayname") . "\n";
93 }
94 A successful PROPFIND fills the object with much data about the
96 Resource. Including:
97 displayname
98 ...
99 TODO
100 lock
102 Performs a WebDAV LOCK request and returns a DAV::Response object.
103 $resource->lock(
105 -owner => "Patrick Collins",
106 -depth => "infinity"
107 -scope => "exclusive",
108 -type => "write"
109 -timeout => TIMEOUT',
110 )
111 lock takes the following arguments.
113 owner - Indicates who locked this resource
115 The default value is:
117 DAV.pm/v$DAV::VERSION ($$)
118 e.g. DAV.pm/v0.1 (123)
120 If you use a URL as the owner, the module will automatically
122 indicate to the server that is is a URL
123 (<D:href>http://...</D:href>)
124 depth - Indicates the depth of the lock.
126 Legal values are 0 or infinity. (1 is not allowed).
128 The default value is infinity.
130 A lock value of 0 on a collection will lock just the collection but
132 not it's members, whereas a lock value of infinity will lock the
133 collection and all of it's members.
134 scope - Indicates the scope of the lock.
136 Legal DAV values are "exclusive" or "shared".
138 The default value is exclusive.
140 See section 6.1 of RFC2518 for a description of shared vs.
142 exclusive locks.
143 type - Indicates the type of lock (read, write, etc)
145 The only legal DAV value currently is "write".
147 The default value is write.
149 timeout - Indicates when the lock will timeout
151 The timeout value may be one of, an Absolute Date, a Time Offset
153 from now, or the word "infinity".
154 The default value is "infinity".
156 The following are all valid timeout values:
158 Time Offset:
160 30s 30 seconds from now
161 10m ten minutes from now
162 1h one hour from now
163 1d tomorrow
164 3M in three months
165 10y in ten years time
166 Absolute Date:
168 timeout at the indicated time & date (UTC/GMT)
170 2000-02-31 00:40:33
171 timeout at the indicated date (UTC/GMT)
173 2000-02-31
174 You can use any of the Absolute Date formats specified in
176 HTTP::Date (see perldoc HTTP::Date)
177 Note: the DAV server may choose to ignore your specified timeout.
179 unlock
181 Performs a WebDAV UNLOCK request and returns a DAV::Response
182 object.
183 $response = $resource->unlock()
185 $response = $resource->unlock( -force => 1 )
186 $response = $resource->unlock(
187 -token => "opaquelocktoken:1342-21423-2323" )
188 This method will automatically use the correct locktoken If: header
190 if this resource was previously locked.
191 force - Synonymous to calling $resource->forcefully_unlock_all.
193 forcefully_unlock_all
195 Remove all locks from a resource and return the last DAV::Response
196 object. This method take no arguments.
197 $response = $resource->forcefully_unlock_all;
199 This method will perform a lockdiscovery against the resource to
201 determine all of the current locks. Then it will UNLOCK them one by
202 one. unlock( -token => locktoken ).
203 This unlock process is achievable because DAV does not enforce any
205 security over locks.
206 Note: this method returns the LAST unlock response (this is
208 sufficient to indicate the success of the sequence of unlocks). If
209 an unlock fails, it will bail and return that response. For
210 instance, In the event that there are 3 shared locks and the second
211 unlock method fails, then you will get returned the unsuccessful
212 second response. The 3rd unlock will not be attempted.
213 Don't run with this knife, you could hurt someone (or yourself).
215 steal_lock
217 Removes all locks from a resource, relocks it in your name and
218 returns the DAV::Response object for the lock command. This method
219 takes no arguments.
220 $response = $resource->steal_lock;
222 Synonymous to forcefully_unlock_all() and then lock().
224 lockdiscovery
226 Discover the locks held against this resource and return a
227 DAV::Response object. This method take no arguments.
228 $response = $resource->lockdiscovery;
230 @locks = $resource->get_locks if $response->is_success;
231 This method is in fact a simplified version of propfind().
233 as_string
235 Returns a string representation of the object. Mainly useful for
236 debugging purposes. It takes no arguments.
237 print $resource->as_string
239
241 is_option
242 Returns a boolean indicating whether this resource supports the
243 option passed in as a string. The option match is case insensitive
244 so, PUT and Put are should both work.
245 if ($resource->is_option( "PUT" ) ) {
247 $resource->put( ... )
248 }
249 Note: this routine automatically calls the options() routine which
251 makes the request to the server. Subsequent calls to is_option will
252 use the cached option list. To force a rerequest to the server call
253 options()
254 is_locked
256 Returns a boolean indicating whether this resource is locked.
257 @lock = $resource->is_locked( -owned=>[1|0] );
259 owned - this parameter is used to ask, is this resource locked by
261 me?
262 Note: You must have already called propfind() or lockdiscovery()
264 e.g. Is the resource locked at all?
266 print "yes" if $resource->is_locked();
267 Is the resource locked by me?
269 print "yes" if $resource->is_locked( -owned=>1 );
270 Is the resource locked by someone other than me?
272 print "yes" if $resource->is_locked( -owned=>0 );
273 is_collection
275 Returns a boolean indicating whether this resource is a collection.
276 print "Directory" if ( $resource->is_collection );
278 You must first have performed a propfind.
280 get_uri
282 Returns the URI object for this resource.
283 print "URL is: " . $resource->get_uri()->as_string . "\n";
285 See the URI manpage from the LWP libraries (perldoc URI)
287 get_property
289 Returns a property value. Takes a string as an argument.
290 print $resource->get_property( "displayname" );
292 You must first have performed a propfind.
294 get_options
296 Returns an array of options allowed on this resource. Note: If
297 $resource->options has not been called then it will return an empty
298 array.
299 @options = $resource->get_options
301 get_content
303 Returns the resource's content/body as a string. The content is
304 typically the result of a GET.
305 $content = $resource->get_content
307 get_content_ref
309 Returns the resource's content/body as a reference to a string.
310 This is useful and more efficient if the content is large.
311 ${$resource->get_content_ref} =~ s/\bfoo\b/bar/g;
313 Note: You must have already called get()
315 get_lock
317 Returns the DAV::Lock object if it exists. Requires opaquelocktoken
318 passed as a parameter.
319 $lock = $resource->get_lock( "opaquelocktoken:234214--342-3444" );
321 get_locks
323 Returns a list of any DAV::Lock objects held against the resource.
324 @lock = $resource->get_locks( -owned=>[1|0] );
326 owned - this parameter indicates which locks you want.
328 - '1', requests any of my locks. (Locked by this DAV instance).
329 - '0' ,requests any locks not owned by us.
330 - any other value or no value, requests ALL locks.
331 Note: You must have already called propfind() or lockdiscovery()
333 e.g.
335 Give me my locks
336 @lock = $resource->get_locks( -owned=>1 );
337 Give me all locks
339 @lock = $resource->get_locks();
340 get_lockedresourcelist
342 get_parentresourcelist
343 get_comms
344 set_parent_resourcelist
345 $resource->set_parent_resourcelist( $resourcelist )
346 Sets the parent resource list (ask the question, which collection
348 am I a member of?). See HTTP::DAV::ResourceList.
349perl v5.36.0 2022-07-22 HTTP::DAV::Resource(3)