1DAV(3) User Contributed Perl Documentation DAV(3)
2
6 HTTP::DAV - A WebDAV client library for Perl5
7
9 # DAV script that connects to a webserver, safely makes
10 # a new directory and uploads all html files in
11 # the /tmp directory.
12 use HTTP::DAV;
14 $d = new HTTP::DAV;
16 $url = "http://host.org:8080/dav/";
17 $d->credentials( -user=>"pcollins",-pass =>"mypass",
19 -url =>$url, -realm=>"DAV Realm" );
20 $d->open( -url=>"$url )
22 or die("Couldn't open $url: " .$d->message . "\n");
23 # Make a null lock on newdir
25 $d->lock( -url => "$url/newdir", -timeout => "10m" )
26 or die "Won't put unless I can lock for 10 minutes\n";
27 # Make a new directory
29 $d->mkcol( -url => "$url/newdir" )
30 or die "Couldn't make newdir at $url\n";
31 # Upload multiple files to newdir.
33 if ( $d->put( -local => "/tmp/*.html", -url => $url ) ) {
34 print "successfully uploaded multiple files to $url\n";
35 } else {
36 print "put failed: " . $d->message . "\n";
37 }
38 $d->unlock( -url => $url );
40
42 HTTP::DAV is a Perl API for interacting with and modifying content on
43 webservers using the WebDAV protocol. Now you can LOCK, DELETE and PUT
44 files and much more on a DAV-enabled webserver.
45 HTTP::DAV is part of the PerlDAV project hosted at
47 http://www.webdav.org/perldav/ and has the following features:
48 · Full RFC2518 method support. OPTIONS, TRACE, GET, HEAD, DELETE,
50 PUT, COPY, MOVE, PROPFIND, PROPPATCH, LOCK, UNLOCK.
51 · A fully object-oriented API.
53 · Recursive GET and PUT for site backups and other scripted
55 transfers.
56 · Transparent lock handling when performing LOCK/COPY/UNLOCK
58 sequences.
59 · http and https support (https requires the Crypt::SSLeay library).
61 See INSTALLATION.
62 · Basic AND Digest authentication support (Digest auth requires the
64 MD5 library). See INSTALLATION.
65 · "dave", a fully-functional ftp-style interface written on top of
67 the HTTP::DAV API and bundled by default with the HTTP::DAV
68 library. (If you've already installed HTTP::DAV, then dave will
69 also have been installed (probably into /usr/local/bin). You can
70 see it's man page by typing "perldoc dave" or going to
71 http://www.webdav.org/perldav/dave/.
72 · It is built on top of the popular LWP (Library for WWW access in
74 Perl). This means that HTTP::DAV inherits proxy support, redirect
75 handling, basic (and digest) authorization and many other HTTP
76 operations. See "LWP" for more information.
77 · Popular server support. HTTP::DAV has been tested against the
79 following servers: mod_dav, IIS5, Xythos webfile server and
80 mydocsonline. The library is growing an impressive interoperability
81 suite which also serves as useful "sample scripts". See "make test"
82 and t/*.
83 "HTTP::DAV" essentially has two API's, one which is accessed through
85 this module directly (HTTP::DAV) and is a simple abstraction to the
86 rest of the HTTP::DAV::* Classes. The other interface consists of the
87 HTTP::DAV::* classes which if required allow you to get "down and
88 dirty" with your DAV and HTTP interactions.
89 The methods provided in "HTTP::DAV" should do most of what you want.
91 If, however, you need more control over the client's operations or need
92 more info about the server's responses then you will need to understand
93 the rest of the HTTP::DAV::* interfaces. A good place to start is with
94 the "HTTP::DAV::Resource" and "HTTP::DAV::Response" documentation.
95
97 METHOD CALLING: Named vs Unnamed parameters
98 You can pass parameters to "HTTP::DAV" methods in one of two ways:
99 named or unnamed.
100 Named parameters provides for a simpler/easier to use interface. A
102 named interface affords more readability and allows the developer to
103 ignore a specific order on the parameters. (named parameters are also
104 case insensitive)
105 Each argument name is preceded by a dash. Neither case nor order
107 matters in the argument list. -url, -Url, and -URL are all acceptable.
108 In fact, only the first argument needs to begin with a dash. If a dash
109 is present in the first argument, "HTTP::DAV" assumes dashes for the
110 subsequent ones.
111 Each method can also be called with unnamed parameters which often
113 makes sense for methods with only one parameter. But the developer will
114 need to ensure that the parameters are passed in the correct order (as
115 listed in the docs).
116 Doc: method( -url=>$url, [-depth=>$depth] )
118 Named: $d->method( -url=>$url, -depth=>$d ); # VALID
119 Named: $d->method( -Depth=>$d, -Url=>$url ); # VALID
120 Named: $d->method( Depth=>$d, Url=>$url ); # INVALID (needs -)
121 Named: $d->method( -Arg2=>$val2 ); # INVALID, ARG1 is not optional
122 Unnamed: $d->method( $val1 ); # VALID
123 Unnamed: $d->method( $val2,$val1 ); # INVALID, ARG1 must come first.
124 IMPORTANT POINT!!!! If you specify a named parameter first but then
126 forget for the second and third parameters, you WILL get weird things
127 happen. E.g. this is bad:
128 $d->method( -url=>$url, $arg2, $arg3 ); # BAD BAD BAD
130 THINGS YOU NEED TO KNOW
132 In all of the methods specified in "PUBLIC METHODS" there are some
133 common concepts you'll need to understand:
134 · URLs represent an absolute or relative URI.
136 -url=>"host.org/dav_dir/" # Absolute
138 -url=>"/dav_dir/" # Relative
139 -url=>"file.txt" # Relative
140 You can only use a relative URL if you have already "open"ed an
142 absolute URL.
143 The HTTP::DAV module now consistently uses the named parameter:
145 URL. The lower-level HTTP::DAV::Resource interface inconsistently
146 interchanges URL and URI. I'm working to resolve this, in the
147 meantime, you'll just need to remember to use the right one by
148 checking the documentation if you need to mix up your use of both
149 interfaces.
150 · GLOBS
152 Some methods accept wildcards in the URL. A wildcard can be used to
154 indicate that the command should perform the command on all
155 Resources that match the wildcard. These wildcards are called
156 GLOBS.
157 The glob may contain the characters "*", "?" and the set operator
159 "[...]" where ... contains multiple characters ([1t2]) or a range
160 such ([1-5]). For the curious, the glob is converted to a regex and
161 then matched: "*" to ".*", "?" to ".", and the [] is left
162 untouched.
163 It is important to note that globs only operate at the leaf-level.
165 For instance "/my_dir/*/file.txt" is not a valid glob.
166 If a glob matches no URL's the command will fail (which normally
168 means returns 0).
169 Globs are useful in conjunction with CALLBACKS to provide feedback
171 as each operation completes.
172 See the documentation for each method to determine whether it
174 supports globbing.
175 Globs are useful for interactive style applications (see the source
177 code for "dave" as an example).
178 Example globs:
180 $dav1->delete(-url=>"/my_dir/file[1-3]"); # Matches file1, file2, file3
182 $dav1->delete(-url=>"/my_dir/file[1-3]*.txt");# Matches file1*.txt,file2*.txt,file3*.txt
183 $dav1->delete(-url=>"/my_dir/*/file.txt"); # Invalid. Can only match at leaf-level
184 · CALLBACKS
186 Callbacks are used by some methods (primarily get and put) to give
188 the caller some insight as to how the operation is progressing. A
189 callback allows you to define a subroutine as defined below and
190 pass a reference (\&ref) to the method.
191 The rationale behind the callback is that a recursive get/put or an
193 operation against many files (using a "glob") can actually take a
194 long time to complete.
195 Example callback:
197 $d->get( -url=>$url, -to=>$to, -callback=>\&mycallback );
199 Your callback function MUST accept arguments as follows:
201 sub cat_callback {
202 my($status,$mesg,$url,$so_far,$length,$data) = @_;
203 ...
204 }
205 The "status" argument specifies whether the operation has succeeded
207 (1), failed (0), or is in progress (-1).
208 The "mesg" argument is a status message. The status message could
210 contain any string and often contains useful error messages or
211 success messages.
212 The "url" the remote URL.
214 The "so_far", "length" - these parameters indicate how many bytes
216 have been downloaded and how many we should expect. This is useful
217 for doing "56% to go" style-gauges.
218 The "data" parameter - is the actual data transferred. The "cat"
220 command uses this to print the data to the screen. This value will
221 be empty for "put".
222 See the source code of "dave" for a useful sample of how to setup a
224 callback.
225 Note that these arguments are NOT named parameters.
227 All error messages set during a "multi-operation" request (for
229 instance a recursive get/put) are also retrievable via the
230 "errors()" function once the operation has completed. See "ERROR
231 HANDLING" for more information.
232 PUBLIC METHODS
234 new(USERAGENT)
235 Creates a new "HTTP::DAV" client
236 $d = HTTP::DAV->new()
238 The "-useragent" parameter expects an "HTTP::DAV::UserAgent"
240 object. See the "dave" program for an advanced example of a custom
241 UserAgent that interactively prompts the user for their username
242 and password.
243 credentials(USER,PASS,[URL],[REALM])
245 sets authorization credentials for a "URL" and/or "REALM".
246 When the client hits a protected resource it will check these
248 credentials to see if either the "URL" or "REALM" match the
249 authorization response.
250 Either "URL" or "REALM" must be provided.
252 returns no value
254 Example:
256 $d->credentials( -url=>'myhost.org:8080/test/',
258 -user=>'pcollins',
259 -pass=>'mypass');
260 DebugLevel($val)
262 sets the debug level to $val. 0=off 3=noisy.
263 $val default is 0.
265 returns no value.
267 When the value is greater than 1, the "HTTP::DAV::Comms" module
269 will log all of the client<=>server interactions into
270 /tmp/perldav_debug.txt.
271 DAV OPERATIONS
273 For all of the following operations, URL can be absolute
274 (http://host.org/dav/) or relative (../dir2/). The only operation that
275 requires an absolute URL is open.
276 copy(URL,DEST,[OVERWRITE],[DEPTH])
278 copies one remote resource to another
279 "-url"
281 is the remote resource you'd like to copy. Mandatory
282 "-dest"
284 is the remote target for the copy command. Mandatory
285 "-overwrite"
287 optionally indicates whether the server should fail if the
288 target exists. Valid values are "T" and "F" (1 and 0 are
289 synonymous). Default is T.
290 "-depth"
292 optionally indicates whether the server should do a recursive
293 copy or not. Valid values are 0 and (1 or "infinity"). Default
294 is "infinity" (1).
295 The return value is always 1 or 0 indicating success or failure.
297 Requires a working resource to be set before being called. See
299 "open".
300 Note: if either 'URL' or 'DEST' are locked by this dav client, then
302 the lock headers will be taken care of automatically. If the either
303 of the two URL's are locked by someone else, the server should
304 reject the request.
305 copy examples:
307 $d->open(-url=>"host.org/dav_dir/");
309 Recursively copy dir1/ to dir2/
311 $d->copy(-url=>"dir1/", -dest=>"dir2/");
313 Non-recursively and non-forcefully copy dir1/ to dir2/
315 $d->copy(-url=>"dir1/", -dest=>"dir2/",-overwrite=>0,-depth=>0);
317 Create a copy of dir1/file.txt as dir2/file.txt
319 $d->cwd(-url=>"dir1/");
321 $d->copy("file.txt","../dir2");
322 Create a copy of file.txt as dir2/new_file.txt
324 $d->copy("file.txt","/dav_dir/dir2/new_file.txt")
326 cwd(URL)
328 changes the remote working directory.
329 This is synonymous to open except that the URL can be relative and
331 may contain a "glob" (the first match in a glob will be used).
332 $d->open("host.org/dav_dir/dir1/");
334 $d->cwd("../dir2");
335 $d->cwd(-url=>"../dir1");
336 The return value is always 1 or 0 indicating success or failure.
338 Requires a working resource to be set before being called. See
340 "open".
341 You can not cwd to files, only collections (directories).
343 delete(URL)
345 deletes a remote resource.
346 $d->open("host.org/dav_dir/");
348 $d->delete("index.html");
349 $d->delete("./dir1");
350 $d->delete(-url=>"/dav_dir/dir2/file*",-callback=>\&mycallback);
351 "-url"
353 is the remote resource(s) you'd like to delete. It can be a file,
354 directory or "glob".
355 "-callback"
357 is a reference to a callback function which will be called everytime a
358 file is deleted. This is mainly useful when used in conjunction with
359 GLOBS deletes. See callbacks
360 The return value is always 1 or 0 indicating success or failure.
361 Requires a working resource to be set before being called. See
363 "open".
364 This command will recursively delete directories. BE CAREFUL of
366 uninitialised file variables in situation like this:
367 $d->delete("$dir/$file"). This will trash your $dir if $file is not
368 set.
369 get(URL,[TO],[CALLBACK])
371 downloads the file or directory at "URL" to the local location
372 indicated by "TO".
373 "-url"
375 is the remote resource you'd like to get. It can be a file or
376 directory or a "glob".
377 "-to"
379 is where you'd like to put the remote resource. The -to
380 parameter can be:
381 - a B<filename> indicating where to save the contents.
383 - a B<FileHandle reference>.
385 - a reference to a B<scalar object> into which the contents will be saved.
387 If the "-url" matches multiple files (via a glob or a directory
389 download), then the "get" routine will return an error if you
390 try to use a FileHandle reference or a scalar reference.
391 "-callback"
393 is a reference to a callback function which will be called
394 everytime a file is completed downloading. The idea of the
395 callback function is that some recursive get's can take a very
396 long time and the user may require some visual feedback. See
397 CALLBACKS for an examples and how to use a callback.
398 The return value of get is always 1 or 0 indicating whether the
400 entire get sequence was a success or if there was ANY failures. For
401 instance, in a recursive get, if the server couldn't open 1 of the
402 10 remote files, for whatever reason, then the return value will be
403 0. This is so that you can have your script call the "errors()"
404 routine to handle error conditions.
405 Previous versions of HTTP::DAV allowed the return value to be the
407 file contents if no -to attribute was supplied. This functionality
408 is deprecated.
409 Requires a working resource to be set before being called. See
411 "open".
412 get examples:
414 $d->open("host.org/dav_dir/");
416 Recursively get remote my_dir/ to .
418 $d->get("my_dir/",".");
420 Recursively get remote my_dir/ to /tmp/my_dir/ calling
422 &mycallback($success,$mesg) everytime a file operation is
423 completed.
424 $d->get("my_dir","/tmp",\&mycallback);
426 Get remote my_dir/index.html to /tmp/index.html
428 $d->get(-url=>"/dav_dir/my_dir/index.html",-to=>"/tmp");
430 Get remote index.html to /tmp/index1.html
432 $d->get("index.html","/tmp/index1.html");
434 Get remote index.html to a filehandle
436 my $fh = new FileHandle;
438 $fh->open(">/tmp/index1.html");
439 $d->get("index.html",\$fh);
440 Get remote index.html as a scalar (into the string $file_contents):
442 my $file_contents;
444 $d->get("index.html",\$file_contents);
445 Get all of the files matching the globs file1* and file2*:
447 $d->get("file[12]*","/tmp");
449 Get all of the files matching the glob file?.html:
451 $d->get("file?.html","/tmp"); # downloads file1.html and file2.html but not file3.html or file1.txt
453 Invalid glob:
455 $d->get("/dav_dir/*/index.html","/tmp"); # Can not glob like this.
457 lock([URL],[OWNER],[DEPTH],[TIMEOUT],[SCOPE],[TYPE])
459 locks a resource. If URL is not specified, it will lock the current
460 working resource (opened resource).
461 $d->lock( -url => "index.html",
463 -owner => "Patrick Collins",
464 -depth => "infinity",
465 -scope => "exclusive",
466 -type => "write",
467 -timeout => "10h" )
468 See "HTTP::DAV::Resource" lock() for details of the above
470 parameters.
471 The return value is always 1 or 0 indicating success or failure.
473 Requires a working resource to be set before being called. See
475 "open".
476 When you lock a resource, the lock is held against the current
478 HTTP::DAV object. In fact, the locks are held in a
479 "HTTP::DAV::ResourceList" object. You can operate against all of
480 the locks that you have created as follows:
481 ## Print and unlock all locks that we own.
483 my $rl_obj = $d->get_lockedresourcelist();
484 foreach $resource ( $rl_obj->get_resources() ) {
485 @locks = $resource->get_locks(-owned=>1);
486 foreach $lock ( @locks ) {
487 print $resource->get_uri . "\n";
488 print $lock->as_string . "\n";
489 }
490 ## Unlock them?
491 $resource->unlock;
492 }
493 Typically, a simple $d->unlock($uri) will suffice.
495 lock example
497 $d->lock($uri, -timeout=>"1d");
499 ...
500 $d->put("/tmp/index.html",$uri);
501 $d->unlock($uri);
502 mkcol(URL)
504 make a remote collection (directory)
505 The return value is always 1 or 0 indicating success or failure.
507 Requires a working resource to be set before being called. See
509 "open".
510 $d->open("host.org/dav_dir/");
512 $d->mkcol("new_dir"); # Should succeed
513 $d->mkcol("/dav_dir/new_dir"); # Should succeed
514 $d->mkcol("/dav_dir/new_dir/xxx/yyy"); # Should fail
515 move(URL,DEST,[OVERWRITE],[DEPTH])
517 moves one remote resource to another
518 "-url"
520 is the remote resource you'd like to move. Mandatory
521 "-dest"
523 is the remote target for the move command. Mandatory
524 "-overwrite"
526 optionally indicates whether the server should fail if the
527 target exists. Valid values are "T" and "F" (1 and 0 are
528 synonymous). Default is T.
529 Requires a working resource to be set before being called. See
531 "open".
532 The return value is always 1 or 0 indicating success or failure.
534 Note: if either 'URL' or 'DEST' are locked by this dav client, then
536 the lock headers will be taken care of automatically. If either of
537 the two URL's are locked by someone else, the server should reject
538 the request.
539 move examples:
541 $d->open(-url=>"host.org/dav_dir/");
543 move dir1/ to dir2/
545 $d->move(-url=>"dir1/", -dest=>"dir2/");
547 non-forcefully move dir1/ to dir2/
549 $d->move(-url=>"dir1/", -dest=>"dir2/",-overwrite=>0);
551 Move dir1/file.txt to dir2/file.txt
553 $d->cwd(-url=>"dir1/");
555 $d->move("file.txt","../dir2");
556 move file.txt to dir2/new_file.txt
558 $d->move("file.txt","/dav_dir/dir2/new_file.txt")
560 open(URL)
562 opens the directory (collection resource) at URL.
563 open will perform a propfind against URL. If the server does not
565 understand the request then the open will fail.
566 Similarly, if the server indicates that the resource at URL is NOT
568 a collection, the open command will fail.
569 options([URL])
571 Performs an OPTIONS request against the URL or the working resource
572 if URL is not supplied.
573 Requires a working resource to be set before being called. See
575 "open".
576 The return value is a string of comma separated OPTIONS that the
578 server states are legal for URL or undef otherwise.
579 A fully compliant DAV server may offer as many methods as: OPTIONS,
581 TRACE, GET, HEAD, DELETE, PUT, COPY, MOVE, PROPFIND, PROPPATCH,
582 LOCK, UNLOCK
583 Note: IIS5 does not support PROPPATCH or LOCK on collections.
585 Example:
587 $options = $d->options($url);
589 print $options . "\n";
590 if ($options=~ /\bPROPPATCH\b/) {
591 print "OK to proppatch\n";
592 }
593 Or, put more simply:
595 if ( $d->options($url) =~ /\bPROPPATCH\b/ ) {
597 print "OK to proppatch\n";
598 }
599 propfind([URL],[DEPTH])
601 Perform a propfind against URL at DEPTH depth.
602 "-depth" can be used to specify how deep the propfind goes. "0" is
604 collection only. "1" is collection and it's immediate members (This
605 is the default value). "infinity" is the entire directory tree.
606 Note that most DAV compliant servers deny "infinity" depth
607 propfinds for security reasons.
608 Requires a working resource to be set before being called. See
610 "open".
611 The return value is an "HTTP::DAV::Resource" object on success or 0
613 on failure.
614 The Resource object can be used for interrogating properties or
616 performing other operations.
617 ## Print collection or content length
619 if ( $r=$d->propfind( -url=>"/my_dir", -depth=>1) ) {
620 if ( $r->is_collection ) {
621 print "Collection\n"
622 print $r->get_resourcelist->as_string . "\n"
623 } else {
624 print $r->get_property("getcontentlength") ."\n";
625 }
626 }
627 Please note that although you may set a different namespace for a
629 property of a resource during a set_prop, HTTP::DAV currently
630 ignores all XML namespaces so you will get clashes if two
631 properties have the same name but in different namespaces.
632 Currently this is unavoidable but I'm working on the solution.
633 proppatch([URL],[NAMESPACE],PROPNAME,PROPVALUE,ACTION,[NSABBR])
635 If "-action" equals "set" then we set a property named "-propname"
636 to "-propvalue" in the namespace "-namespace" for "-url".
637 If "-action" equals "remove" then we unset a property named
639 "-propname" in the namespace "-namespace" for "-url".
640 If no action is supplied then the default action is "set".
642 The return value is an "HTTP::DAV::Resource" object on success or 0
644 on failure.
645 The Resource object can be used for interrogating properties or
647 performing other operations.
648 To explicitly set a namespace in which to set the propname then you
650 can use the "-namespace" and "-nsabbr" (namespace abbreviation)
651 parameters. But you're welcome to play around with DAV namespaces.
652 Requires a working resource to be set before being called. See
654 "open".
655 It is recommended that you use "set_prop" and "unset_prop" instead
657 of proppatch for readability.
658 "set_prop" simply calls "proppatch(-action="set)> and "unset_prop"
660 calls "proppatch(-action=""remove")>
661 See "set_prop" and "unset_prop" for examples.
663 put(LOCAL,[URL],[CALLBACK])
665 uploads the files or directories at -local to the remote
666 destination at -url.
667 -local points to a file, directory or series of files or
669 directories (indicated by a glob).
670 If the filename contains any of the characters `*', `?' or `['
672 it is a candidate for filename substitution, also known as
673 ``globbing''. This word is then regarded as a pattern
674 (``glob-pattern''), and replaced with an alphabetically sorted list
675 of file names which match the pattern.
676 One can upload/put a string by passing a reference to a scalar in
678 the -local parameter. See example below.
679 put requires a working resource to be set before being called. See
681 "open".
682 The return value is always 1 or 0 indicating success or failure.
684 See get() for a description of what the optional callback parameter
686 does.
687 put examples:
689 Put a string to the server:
691 my $myfile = "This is the contents of a file to be uploaded\n";
693 $d->put(-local=>\$myfile,-url=>"http://www.host.org/dav_dir/file.txt");
694 Put a local file to the server:
696 $d->put(-local=>"/tmp/index.html",-url=>"http://www.host.org/dav_dir/");
698 Put a series of local files to the server:
700 In these examples, /tmp contains file1.html, file1, file2.html,
702 file2.txt, file3.html, file2/
703 $d->put(-local=>"/tmp/file[12]*",-url=>"http://www.host.org/dav_dir/");
705 uploads file1.html, file1, file2.html, file2.txt and the directory file2/ to dav_dir/.
707 set_prop([URL],[NAMESPACE],PROPNAME,PROPVALUE)
709 Sets a property named "-propname" to "-propvalue" in the namespace
710 "-namespace" for "-url".
711 Requires a working resource to be set before being called. See
713 "open".
714 The return value is an "HTTP::DAV::Resource" object on success or 0
716 on failure.
717 The Resource object can be used for interrogating properties or
719 performing other operations.
720 Example:
722 if ( $r = $d->set_prop(-url=>$url,
724 -namespace=>"dave",
725 -propname=>"author",
726 -propvalue=>"Patrick Collins"
727 ) ) {
728 print "Author property set\n";
729 } else {
730 print "set_prop failed:" . $d->message . "\n";
731 }
732 See the note in propfind about namespace support in HTTP::DAV.
734 They're settable, but not readable.
735 steal([URL])
737 forcefully steals any locks held against URL.
738 steal will perform a propfind against URL and then, any locks that
740 are found will be unlocked one by one regardless of whether we own
741 them or not.
742 Requires a working resource to be set before being called. See
744 "open".
745 The return value is always 1 or 0 indicating success or failure. If
747 multiple locks are found and unlocking one of them fails then the
748 operation will be aborted.
749 if ($d->steal()) {
751 print "Steal succeeded\n";
752 } else {
753 print "Steal failed: ". $d->message() . "\n";
754 }
755 unlock([URL])
757 unlocks any of our locks on URL.
758 Requires a working resource to be set before being called. See
760 "open".
761 The return value is always 1 or 0 indicating success or failure.
763 if ($d->unlock()) {
765 print "Unlock succeeded\n";
766 } else {
767 print "Unlock failed: ". $d->message() . "\n";
768 }
769 unset_prop([URL],[NAMESPACE],PROPNAME)
771 Unsets a property named "-propname" in the namespace "-namespace"
772 for "-url". Requires a working resource to be set before being
773 called. See "open".
774 The return value is an "HTTP::DAV::Resource" object on success or 0
776 on failure.
777 The Resource object can be used for interrogating properties or
779 performing other operations.
780 Example:
782 if ( $r = $d->unset_prop(-url=>$url,
784 -namespace=>"dave",
785 -propname=>"author",
786 ) ) {
787 print "Author property was unset\n";
788 } else {
789 print "set_prop failed:" . $d->message . "\n";
790 }
791 See the note in propfind about namespace support in HTTP::DAV.
793 They're settable, but not readable.
794 ACCESSOR METHODS
796 get_user_agent
797 Returns the clients' working "HTTP::DAV::UserAgent" object.
798 You may want to interact with the "HTTP::DAV::UserAgent" object to
800 modify request headers or provide advanced authentication
801 procedures. See dave for an advanced authentication procedure.
802 get_last_request
804 Takes no arguments and returns the clients' last outgoing
805 "HTTP::Request" object.
806 You would only use this to inspect a request that has already
808 occurred.
809 If you would like to modify the "HTTP::Request" BEFORE the HTTP
811 request takes place (for instance to add another header), you will
812 need to get the "HTTP::DAV::UserAgent" using "get_user_agent" and
813 interact with that.
814 get_workingresource
816 Returns the currently "opened" or "working" resource
817 ("HTTP::DAV::Resource").
818 The working resource is changed whenever you open a url or use the
820 cwd command.
821 e.g.
823 $r = $d->get_workingresource
824 print "pwd: " . $r->get_uri . "\n";
825 get_workingurl
827 Returns the currently "opened" or "working" "URL".
828 The working resource is changed whenever you open a url or use the
830 cwd command.
831 print "pwd: " . $d->get_workingurl . "\n";
833 get_lockedresourcelist
835 Returns an "HTTP::DAV::ResourceList" object that represents all of
836 the locks we've created using THIS dav client.
837 print "pwd: " . $d->get_workingurl . "\n";
839 get_absolute_uri(REL_URI,[BASE_URI])
841 This is a useful utility function which joins "BASE_URI" and
842 "REL_URI" and returns a new URI.
843 If "BASE_URI" is not supplied then the current working resource (as
845 indicated by get_workingurl) is used. If "BASE_URI" is not set and
846 there is no current working resource the "REL_URI" will be
847 returned.
848 For instance:
850 $d->open("http://host.org/webdav/dir1/");
851 # Returns "http://host.org/webdav/dir2/"
853 $d->get_absolute_uri(-rel_uri=>"../dir2");
854 # Returns "http://x.org/dav/dir2/file.txt"
856 $d->get_absolute_uri(-rel_uri =>"dir2/file.txt",
857 ->base_uri=>"http://x.org/dav/");
858 Note that it subtly takes care of trailing slashes.
860 ERROR HANDLING METHODS
862 message
863 "message" gets the last success or error message.
864 The return value is always a scalar (string) and will change
866 everytime a dav operation is invoked (lock, cwd, put, etc).
867 See also "errors" for operations which contain multiple error
869 messages.
870 errors
872 Returns an @array of error messages that had been set during a
873 multi-request operation.
874 Some of "HTTP::DAV"'s operations perform multiple request to the
876 server. At the time of writing only put and get are considered
877 multi-request since they can operate recursively requiring many
878 HTTP requests.
879 In these situations you should check the errors array if to
881 determine if any of the requests failed.
882 The "errors" function is used for multi-request operations and not
884 to be confused with a multi-status server response. A multi-status
885 server response is when the server responds with multiple error
886 messages for a SINGLE request. To deal with multi-status responses,
887 see "HTTP::DAV::Response".
888 # Recursive put
890 if (!$d->put( "/tmp/my_dir", $url ) ) {
891 # Get the overall message
892 print $d->message;
893 # Get the individual messages
894 foreach $err ( $d->errors ) { print " Error:$err\n" }
895 }
896 is_success
898 Returns the status of the last DAV operation performed through the
899 HTTP::DAV interface.
900 This value will always be the same as the value returned from an
902 HTTP::DAV::method. For instance:
903 # This will always evaluate to true
905 ($d->lock($url) eq $d->is_success) ?
906 You may want to use the is_success method if you didn't capture the
908 return value immediately. But in most circumstances you're better
909 off just evaluating as follows:
910 if($d->lock($url)) { ... }
911 get_last_response
913 Takes no arguments and returns the last seen "HTTP::DAV::Response"
914 object.
915 You may want to use this if you have just called a propfind and
917 need the individual error messages returned in a MultiStatus.
918 If you find that you're using get_last_response() method a lot, you
920 may be better off using the more advanced "HTTP::DAV" interface and
921 interacting with the HTTP::DAV::* interfaces directly as discussed
922 in the intro. For instance, if you find that you're always wanting
923 a detailed understanding of the server's response headers or
924 messages, then you're probably better off using the
925 "HTTP::DAV::Resource" methods and interpreting the
926 "HTTP::DAV::Response" directly.
927 To perform detailed analysis of the server's response (if for
929 instance you got back a multistatus response) you can call
930 "get_last_response()" which will return to you the most recent
931 response object (always the result of the last operation, PUT,
932 PROPFIND, etc). With the returned HTTP::DAV::Response object you
933 can handle multi-status responses.
934 For example:
936 # Print all of the messages in a multistatus response
938 if (! $d->unlock($url) ) {
939 $response = $d->get_last_response();
940 if ($response->is_multistatus() ) {
941 foreach $num ( 0 .. $response->response_count() ) {
942 ($err_code,$mesg,$url,$desc) =
943 $response->response_bynum($num);
944 print "$mesg ($err_code) for $url\n";
945 }
946 }
947 }
948 ADVANCED METHODS
950 new_resource
951 Creates a new resource object with which to play. This is the
952 preferred way of creating an "HTTP::DAV::Resource" object if
953 required. Why? Because each Resource object needs to sit within a
954 global HTTP::DAV client. Also, because the new_resource routine
955 checks the "HTTP::DAV" locked resource list before creating a new
956 object.
957 $dav->new_resource( -uri => "http://..." );
959 set_workingresource(URL)
961 Sets the current working resource to URL.
962 You shouldn't need this method. Call open or cwd to set the working
964 resource.
965 You CAN call "set_workingresource()" but you will need to perform a
967 "propfind" immediately following it to ensure that the working
968 resource is valid.
969
971 [OUTDATED]
972 Please see the primary HTTP::DAV webpage at
974 (http://www.webdav.org/perldav/http-dav/) or the README file in this
975 library.
976
978 You'll want to also read:
979 "HTTP::DAV::Response"
981 "HTTP::DAV::Resource"
982 "dave"
983 and maybe if you're more inquisitive:
985 "LWP::UserAgent"
987 "HTTP::Request"
988 "HTTP::DAV::Comms"
989 "HTTP::DAV::Lock"
990 "HTTP::DAV::ResourceList"
991 "HTTP::DAV::Utils"
992
994 This module is Copyright (C) 2001-2008 by
995 Patrick Collins
997 G03 Gloucester Place, Kensington
998 Sydney, Australia
999 Email: pcollins@cpan.org
1001 Phone: +61 2 9663 4916
1002 All rights reserved.
1004 Current co-maintainer of the module is Cosimo Streppone for Opera
1006 Software ASA, opera@cpan.org.
1007 You may distribute this module under the terms of either the GNU
1009 General Public License or the Artistic License, as specified in the
1010 Perl README file.
1011
1013 Hey! The above document had some coding errors, which are explained
1014 below:
1015 Around line 1964:
1017 =over should be: '=over' or '=over positive_number'
1018 Around line 1976:
1020 =over should be: '=over' or '=over positive_number'
1021perl v5.12.1 2010-01-26 DAV(3)