HTTP::DAV(3pm)

1HTTP::DAV(3)          User Contributed Perl Documentation         HTTP::DAV(3)
2
3
4

NAME

6       HTTP::DAV - A WebDAV client library for Perl5
7

SYNOPSIS

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
13          use HTTP::DAV;
14
15          $d = HTTP::DAV->new();
16          $url = "http://host.org:8080/dav/";
17
18          $d->credentials(
19             -user  => "pcollins",
20             -pass  => "mypass",
21             -url   => $url,
22             -realm => "DAV Realm"
23          );
24
25          $d->open( -url => $url )
26             or die("Couldn't open $url: " .$d->message . "\n");
27
28          # Make a null lock on newdir
29          $d->lock( -url => "$url/newdir", -timeout => "10m" )
30             or die "Won't put unless I can lock for 10 minutes\n";
31
32          # Make a new directory
33          $d->mkcol( -url => "$url/newdir" )
34             or die "Couldn't make newdir at $url\n";
35
36          # Upload multiple files to newdir.
37          if ( $d->put( -local => "/tmp/*.html", -url => $url ) ) {
38             print "successfully uploaded multiple files to $url\n";
39          } else {
40             print "put failed: " . $d->message . "\n";
41          }
42
43          $d->unlock( -url => $url );
44

DESCRIPTION

46       HTTP::DAV is a Perl API for interacting with and modifying content on
47       webservers using the WebDAV protocol. Now you can LOCK, DELETE and PUT
48       files and much more on a DAV-enabled webserver.
49
50       HTTP::DAV is part of the PerlDAV project hosted at
51       http://www.webdav.org/perldav/ and has the following features:
52
53       ·   Full RFC2518 method support. OPTIONS, TRACE, GET, HEAD, DELETE,
54           PUT, COPY, MOVE, PROPFIND, PROPPATCH, LOCK, UNLOCK.
55
56       ·   A fully object-oriented API.
57
58       ·   Recursive GET and PUT for site backups and other scripted
59           transfers.
60
61       ·   Transparent lock handling when performing LOCK/COPY/UNLOCK
62           sequences.
63
64       ·   http and https support (https requires the Crypt::SSLeay library).
65           See INSTALLATION.
66
67       ·   Basic AND Digest authentication support (Digest auth requires the
68           MD5 library). See INSTALLATION.
69
70       ·   "dave", a fully-functional ftp-style interface written on top of
71           the HTTP::DAV API and bundled by default with the HTTP::DAV
72           library. (If you've already installed HTTP::DAV, then dave will
73           also have been installed (probably into /usr/local/bin). You can
74           see it's man page by typing "perldoc dave" or going to
75           http://www.webdav.org/perldav/dave/.
76
77       ·   It is built on top of the popular LWP (Library for WWW access in
78           Perl). This means that HTTP::DAV inherits proxy support, redirect
79           handling, basic (and digest) authorization and many other HTTP
80           operations. See "LWP" for more information.
81
82       ·   Popular server support. HTTP::DAV has been tested against the
83           following servers: mod_dav, IIS5, Xythos webfile server and
84           mydocsonline. The library is growing an impressive interoperability
85           suite which also serves as useful "sample scripts". See "make test"
86           and t/*.
87
88       "HTTP::DAV" essentially has two API's, one which is accessed through
89       this module directly (HTTP::DAV) and is a simple abstraction to the
90       rest of the HTTP::DAV::* Classes. The other interface consists of the
91       HTTP::DAV::* classes which if required allow you to get "down and
92       dirty" with your DAV and HTTP interactions.
93
94       The methods provided in "HTTP::DAV" should do most of what you want.
95       If, however, you need more control over the client's operations or need
96       more info about the server's responses then you will need to understand
97       the rest of the HTTP::DAV::* interfaces. A good place to start is with
98       the "HTTP::DAV::Resource" and "HTTP::DAV::Response" documentation.
99

METHODS

101   METHOD CALLING: Named vs Unnamed parameters
102       You can pass parameters to "HTTP::DAV" methods in one of two ways:
103       named or unnamed.
104
105       Named parameters provides for a simpler/easier to use interface. A
106       named interface affords more readability and allows the developer to
107       ignore a specific order on the parameters. (named parameters are also
108       case insensitive)
109
110       Each argument name is preceded by a dash.  Neither case nor order
111       matters in the argument list.  -url, -Url, and -URL are all acceptable.
112       In fact, only the first argument needs to begin with a dash.  If a dash
113       is present in the first argument, "HTTP::DAV" assumes dashes for the
114       subsequent ones.
115
116       Each method can also be called with unnamed parameters which often
117       makes sense for methods with only one parameter. But the developer will
118       need to ensure that the parameters are passed in the correct order (as
119       listed in the docs).
120
121        Doc:     method( -url=>$url, [-depth=>$depth] )
122        Named:   $d->method( -url=>$url, -depth=>$d ); # VALID
123        Named:   $d->method( -Depth=>$d, -Url=>$url ); # VALID
124        Named:   $d->method( Depth=>$d,  Url=>$url );  # INVALID (needs -)
125        Named:   $d->method( -Arg2=>$val2 ); # INVALID, ARG1 is not optional
126        Unnamed: $d->method( $val1 );        # VALID
127        Unnamed: $d->method( $val2,$val1 );  # INVALID, ARG1 must come first.
128
129       IMPORTANT POINT!!!! If you specify a named parameter first but then
130       forget for the second and third parameters, you WILL get weird things
131       happen. E.g. this is bad:
132
133        $d->method( -url=>$url, $arg2, $arg3 ); # BAD BAD BAD
134
135   THINGS YOU NEED TO KNOW
136       In all of the methods specified in "PUBLIC METHODS" there are some
137       common concepts you'll need to understand:
138
139       ·   URLs represent an absolute or relative URI.
140
141             -url=>"host.org/dav_dir/"  # Absolute
142             -url=>"/dav_dir/"          # Relative
143             -url=>"file.txt"           # Relative
144
145           You can only use a relative URL if you have already "open"ed an
146           absolute URL.
147
148           The HTTP::DAV module now consistently uses the named parameter:
149           URL. The lower-level HTTP::DAV::Resource interface inconsistently
150           interchanges URL and URI. I'm working to resolve this, in the
151           meantime, you'll just need to remember to use the right one by
152           checking the documentation if you need to mix up your use of both
153           interfaces.
154
155       ·   GLOBS
156
157           Some methods accept wildcards in the URL. A wildcard can be used to
158           indicate that the command should perform the command on all
159           Resources that match the wildcard. These wildcards are called
160           GLOBS.
161
162           The glob may contain the characters "*", "?" and the set operator
163           "[...]" where ... contains multiple characters ([1t2]) or a range
164           such ([1-5]). For the curious, the glob is converted to a regex and
165           then matched: "*" to ".*", "?" to ".", and the [] is left
166           untouched.
167
168           It is important to note that globs only operate at the leaf-level.
169           For instance "/my_dir/*/file.txt" is not a valid glob.
170
171           If a glob matches no URL's the command will fail (which normally
172           means returns 0).
173
174           Globs are useful in conjunction with CALLBACKS to provide feedback
175           as each operation completes.
176
177           See the documentation for each method to determine whether it
178           supports globbing.
179
180           Globs are useful for interactive style applications (see the source
181           code for "dave" as an example).
182
183           Example globs:
184
185              $dav1->delete(-url=>"/my_dir/file[1-3]");     # Matches file1, file2, file3
186              $dav1->delete(-url=>"/my_dir/file[1-3]*.txt");# Matches file1*.txt,file2*.txt,file3*.txt
187              $dav1->delete(-url=>"/my_dir/*/file.txt");    # Invalid. Can only match at leaf-level
188
189       ·   CALLBACKS
190
191           Callbacks are used by some methods (primarily get and put) to give
192           the caller some insight as to how the operation is progressing. A
193           callback allows you to define a subroutine as defined below and
194           pass a reference (\&ref) to the method.
195
196           The rationale behind the callback is that a recursive get/put or an
197           operation against many files (using a "glob") can actually take a
198           long time to complete.
199
200           Example callback:
201
202              $d->get( -url=>$url, -to=>$to, -callback=>\&mycallback );
203
204           Your callback function MUST accept arguments as follows:
205              sub cat_callback {
206                 my($status,$mesg,$url,$so_far,$length,$data) = @_;
207                 ...
208              }
209
210           The "status" argument specifies whether the operation has succeeded
211           (1), failed (0), or is in progress (-1).
212
213           The "mesg" argument is a status message. The status message could
214           contain any string and often contains useful error messages or
215           success messages.
216
217           The "url" the remote URL.
218
219           The "so_far", "length" - these parameters indicate how many bytes
220           have been downloaded and how many we should expect. This is useful
221           for doing "56% to go" style-gauges.
222
223           The "data" parameter - is the actual data transferred. The "cat"
224           command uses this to print the data to the screen. This value will
225           be empty for "put".
226
227           See the source code of "dave" for a useful sample of how to setup a
228           callback.
229
230           Note that these arguments are NOT named parameters.
231
232           All error messages set during a "multi-operation" request (for
233           instance a recursive get/put) are also retrievable via the
234           "errors()" function once the operation has completed. See "ERROR
235           HANDLING" for more information.
236
237   PUBLIC METHODS
238       new(USERAGENT)
239       new(USERAGENT, HEADERS)
240           Creates a new "HTTP::DAV" client
241
242            $d = HTTP::DAV->new();
243
244           The "-useragent" parameter allows you to pass your own user agent
245           object and expects an "HTTP::DAV::UserAgent" object. See the "dave"
246           program for an advanced example of a custom UserAgent that
247           interactively prompts the user for their username and password.
248
249           The "-headers" parameter allows you to specify a list of headers to
250           be sent along with all requests. This can be either a hashref like:
251
252             { "X-My-Header" => "value", ... }
253
254           or a HTTP::Headers object.
255
256       credentials(USER,PASS,[URL],[REALM])
257           sets authorization credentials for a "URL" and/or "REALM".
258
259           When the client hits a protected resource it will check these
260           credentials to see if either the "URL" or "REALM" match the
261           authorization response.
262
263           Either "URL" or "REALM" must be provided.
264
265           returns no value
266
267           Example:
268
269            $d->credentials( -url=>'myhost.org:8080/test/',
270                             -user=>'pcollins',
271                             -pass=>'mypass');
272
273       DebugLevel($val)
274           sets the debug level to $val. 0=off 3=noisy.
275
276           $val default is 0.
277
278           returns no value.
279
280           When the value is greater than 1, the "HTTP::DAV::Comms" module
281           will log all of the client<=>server interactions into
282           /tmp/perldav_debug.txt.
283
284   DAV OPERATIONS
285       For all of the following operations, URL can be absolute
286       (http://host.org/dav/) or relative (../dir2/). The only operation that
287       requires an absolute URL is open.
288
289       copy(URL,DEST,[OVERWRITE],[DEPTH])
290           copies one remote resource to another
291
292           "-url"
293               is the remote resource you'd like to copy. Mandatory
294
295           "-dest"
296               is the remote target for the copy command. Mandatory
297
298           "-overwrite"
299               optionally indicates whether the server should fail if the
300               target exists. Valid values are "T" and "F" (1 and 0 are
301               synonymous). Default is T.
302
303           "-depth"
304               optionally indicates whether the server should do a recursive
305               copy or not. Valid values are 0 and (1 or "infinity"). Default
306               is "infinity" (1).
307
308           The return value is always 1 or 0 indicating success or failure.
309
310           Requires a working resource to be set before being called. See
311           "open".
312
313           Note: if either 'URL' or 'DEST' are locked by this dav client, then
314           the lock headers will be taken care of automatically. If the either
315           of the two URL's are locked by someone else, the server should
316           reject the request.
317
318           copy examples:
319
320             $d->open(-url=>"host.org/dav_dir/");
321
322           Recursively copy dir1/ to dir2/
323
324             $d->copy(-url=>"dir1/", -dest=>"dir2/");
325
326           Non-recursively and non-forcefully copy dir1/ to dir2/
327
328             $d->copy(-url=>"dir1/", -dest=>"dir2/",-overwrite=>0,-depth=>0);
329
330           Create a copy of dir1/file.txt as dir2/file.txt
331
332             $d->cwd(-url=>"dir1/");
333             $d->copy("file.txt","../dir2");
334
335           Create a copy of file.txt as dir2/new_file.txt
336
337             $d->copy("file.txt","/dav_dir/dir2/new_file.txt")
338
339       cwd(URL)
340           changes the remote working directory.
341
342           This is synonymous to open except that the URL can be relative and
343           may contain a "glob" (the first match in a glob will be used).
344
345             $d->open("host.org/dav_dir/dir1/");
346             $d->cwd("../dir2");
347             $d->cwd(-url=>"../dir1");
348
349           The return value is always 1 or 0 indicating success or failure.
350
351           Requires a working resource to be set before being called. See
352           "open".
353
354           You can not cwd to files, only collections (directories).
355
356       delete(URL)
357           deletes a remote resource.
358
359             $d->open("host.org/dav_dir/");
360             $d->delete("index.html");
361             $d->delete("./dir1");
362             $d->delete(-url=>"/dav_dir/dir2/file*",-callback=>\&mycallback);
363
364       "-url"
365           is the remote resource(s) you'd like to delete. It can be a file,
366           directory or "glob".
367
368       "-callback"
369       is a reference to a callback function which will be called everytime a
370       file is deleted. This is mainly useful when used in conjunction with
371       GLOBS deletes. See callbacks
372           The return value is always 1 or 0 indicating success or failure.
373
374           Requires a working resource to be set before being called. See
375           "open".
376
377           This command will recursively delete directories. BE CAREFUL of
378           uninitialised file variables in situation like this:
379           $d->delete("$dir/$file"). This will trash your $dir if $file is not
380           set.
381
382       get(URL,[TO],[CALLBACK])
383           downloads the file or directory at "URL" to the local location
384           indicated by "TO".
385
386           "-url"
387               is the remote resource you'd like to get. It can be a file or
388               directory or a "glob".
389
390           "-to"
391               is where you'd like to put the remote resource. The -to
392               parameter can be:
393
394                - a B<filename> indicating where to save the contents.
395
396                - a B<FileHandle reference>.
397
398                - a reference to a B<scalar object> into which the contents will be saved.
399
400               If the "-url" matches multiple files (via a glob or a directory
401               download), then the "get" routine will return an error if you
402               try to use a FileHandle reference or a scalar reference.
403
404           "-callback"
405               is a reference to a callback function which will be called
406               everytime a file is completed downloading. The idea of the
407               callback function is that some recursive get's can take a very
408               long time and the user may require some visual feedback. See
409               CALLBACKS for an examples and how to use a callback.
410
411           The return value of get is always 1 or 0 indicating whether the
412           entire get sequence was a success or if there was ANY failures. For
413           instance, in a recursive get, if the server couldn't open 1 of the
414           10 remote files, for whatever reason, then the return value will be
415           0. This is so that you can have your script call the "errors()"
416           routine to handle error conditions.
417
418           Previous versions of HTTP::DAV allowed the return value to be the
419           file contents if no -to attribute was supplied. This functionality
420           is deprecated.
421
422           Requires a working resource to be set before being called. See
423           "open".
424
425           get examples:
426
427             $d->open("host.org/dav_dir/");
428
429           Recursively get remote my_dir/ to .
430
431             $d->get("my_dir/",".");
432
433           Recursively get remote my_dir/ to /tmp/my_dir/ calling
434           &mycallback($success,$mesg) everytime a file operation is
435           completed.
436
437             $d->get("my_dir","/tmp",\&mycallback);
438
439           Get remote my_dir/index.html to /tmp/index.html
440
441             $d->get(-url=>"/dav_dir/my_dir/index.html",-to=>"/tmp");
442
443           Get remote index.html to /tmp/index1.html
444
445             $d->get("index.html","/tmp/index1.html");
446
447           Get remote index.html to a filehandle
448
449             my $fh = new FileHandle;
450             $fh->open(">/tmp/index1.html");
451             $d->get("index.html",\$fh);
452
453           Get remote index.html as a scalar (into the string $file_contents):
454
455             my $file_contents;
456             $d->get("index.html",\$file_contents);
457
458           Get all of the files matching the globs file1* and file2*:
459
460             $d->get("file[12]*","/tmp");
461
462           Get all of the files matching the glob file?.html:
463
464             $d->get("file?.html","/tmp"); # downloads file1.html and file2.html but not file3.html or file1.txt
465
466           Invalid glob:
467
468             $d->get("/dav_dir/*/index.html","/tmp"); # Can not glob like this.
469
470       lock([URL],[OWNER],[DEPTH],[TIMEOUT],[SCOPE],[TYPE])
471           locks a resource. If URL is not specified, it will lock the current
472           working resource (opened resource).
473
474              $d->lock( -url     => "index.html",
475                        -owner   => "Patrick Collins",
476                        -depth   => "infinity",
477                        -scope   => "exclusive",
478                        -type    => "write",
479                        -timeout => "10h" )
480
481           See "HTTP::DAV::Resource" lock() for details of the above
482           parameters.
483
484           The return value is always 1 or 0 indicating success or failure.
485
486           Requires a working resource to be set before being called. See
487           "open".
488
489           When you lock a resource, the lock is held against the current
490           HTTP::DAV object. In fact, the locks are held in a
491           "HTTP::DAV::ResourceList" object. You can operate against all of
492           the locks that you have created as follows:
493
494             ## Print and unlock all locks that we own.
495             my $rl_obj = $d->get_lockedresourcelist();
496             foreach $resource ( $rl_obj->get_resources() ) {
497                 @locks = $resource->get_locks(-owned=>1);
498                 foreach $lock ( @locks ) {
499                   print $resource->get_uri . "\n";
500                   print $lock->as_string . "\n";
501                 }
502                 ## Unlock them?
503                 $resource->unlock;
504             }
505
506           Typically, a simple $d->unlock($uri) will suffice.
507
508           lock example
509
510             $d->lock($uri, -timeout=>"1d");
511             ...
512             $d->put("/tmp/index.html",$uri);
513             $d->unlock($uri);
514
515       mkcol(URL)
516           make a remote collection (directory)
517
518           The return value is always 1 or 0 indicating success or failure.
519
520           Requires a working resource to be set before being called. See
521           "open".
522
523             $d->open("host.org/dav_dir/");
524             $d->mkcol("new_dir");                  # Should succeed
525             $d->mkcol("/dav_dir/new_dir");         # Should succeed
526             $d->mkcol("/dav_dir/new_dir/xxx/yyy"); # Should fail
527
528       move(URL,DEST,[OVERWRITE],[DEPTH])
529           moves one remote resource to another
530
531           "-url"
532               is the remote resource you'd like to move. Mandatory
533
534           "-dest"
535               is the remote target for the move command. Mandatory
536
537           "-overwrite"
538               optionally indicates whether the server should fail if the
539               target exists. Valid values are "T" and "F" (1 and 0 are
540               synonymous). Default is T.
541
542           Requires a working resource to be set before being called. See
543           "open".
544
545           The return value is always 1 or 0 indicating success or failure.
546
547           Note: if either 'URL' or 'DEST' are locked by this dav client, then
548           the lock headers will be taken care of automatically. If either of
549           the two URL's are locked by someone else, the server should reject
550           the request.
551
552           move examples:
553
554             $d->open(-url=>"host.org/dav_dir/");
555
556           move dir1/ to dir2/
557
558             $d->move(-url=>"dir1/", -dest=>"dir2/");
559
560           non-forcefully move dir1/ to dir2/
561
562             $d->move(-url=>"dir1/", -dest=>"dir2/",-overwrite=>0);
563
564           Move dir1/file.txt to dir2/file.txt
565
566             $d->cwd(-url=>"dir1/");
567             $d->move("file.txt","../dir2");
568
569           move file.txt to dir2/new_file.txt
570
571             $d->move("file.txt","/dav_dir/dir2/new_file.txt")
572
573       open(URL)
574           opens the directory (collection resource) at URL.
575
576           open will perform a propfind against URL. If the server does not
577           understand the request then the open will fail.
578
579           Similarly, if the server indicates that the resource at URL is NOT
580           a collection, the open command will fail.
581
582       options([URL])
583           Performs an OPTIONS request against the URL or the working resource
584           if URL is not supplied.
585
586           Requires a working resource to be set before being called. See
587           "open".
588
589           The return value is a string of comma separated OPTIONS that the
590           server states are legal for URL or undef otherwise.
591
592           A fully compliant DAV server may offer as many methods as: OPTIONS,
593           TRACE, GET, HEAD, DELETE, PUT, COPY, MOVE, PROPFIND, PROPPATCH,
594           LOCK, UNLOCK
595
596           Note: IIS5 does not support PROPPATCH or LOCK on collections.
597
598           Example:
599
600            $options = $d->options($url);
601            print $options . "\n";
602            if ($options=~ /\bPROPPATCH\b/) {
603               print "OK to proppatch\n";
604            }
605
606           Or, put more simply:
607
608            if ( $d->options($url) =~ /\bPROPPATCH\b/ ) {
609               print "OK to proppatch\n";
610            }
611
612       propfind([URL],[DEPTH])
613           Perform a propfind against URL at DEPTH depth.
614
615           "-depth" can be used to specify how deep the propfind goes. "0" is
616           collection only. "1" is collection and it's immediate members (This
617           is the default value). "infinity" is the entire directory tree.
618           Note that most DAV compliant servers deny "infinity" depth
619           propfinds for security reasons.
620
621           Requires a working resource to be set before being called. See
622           "open".
623
624           The return value is an "HTTP::DAV::Resource" object on success or 0
625           on failure.
626
627           The Resource object can be used for interrogating properties or
628           performing other operations.
629
630            ## Print collection or content length
631            if ( $r=$d->propfind( -url=>"/my_dir", -depth=>1) ) {
632               if ( $r->is_collection ) {
633                  print "Collection\n"
634                  print $r->get_resourcelist->as_string . "\n"
635               } else {
636                  print $r->get_property("getcontentlength") ."\n";
637               }
638            }
639
640           Please note that although you may set a different namespace for a
641           property of a resource during a set_prop, HTTP::DAV currently
642           ignores all XML namespaces so you will get clashes if two
643           properties have the same name but in different namespaces.
644           Currently this is unavoidable but I'm working on the solution.
645
646       proppatch([URL],[NAMESPACE],PROPNAME,PROPVALUE,ACTION,[NSABBR])
647           If "-action" equals "set" then we set a property named "-propname"
648           to "-propvalue" in the namespace "-namespace" for "-url".
649
650           If "-action" equals "remove" then we unset a property named
651           "-propname" in the namespace "-namespace" for "-url".
652
653           If no action is supplied then the default action is "set".
654
655           The return value is an "HTTP::DAV::Resource" object on success or 0
656           on failure.
657
658           The Resource object can be used for interrogating properties or
659           performing other operations.
660
661           To explicitly set a namespace in which to set the propname then you
662           can use the "-namespace" and "-nsabbr" (namespace abbreviation)
663           parameters. But you're welcome to play around with DAV namespaces.
664
665           Requires a working resource to be set before being called. See
666           "open".
667
668           It is recommended that you use "set_prop" and "unset_prop" instead
669           of proppatch for readability.
670
671           "set_prop" simply calls "proppatch(-action="set)> and "unset_prop"
672           calls "proppatch(-action=""remove")>
673
674           See "set_prop" and "unset_prop" for examples.
675
676       put(LOCAL,[URL],[CALLBACK],[HEADERS])
677           uploads the files or directories at "-local" to the remote
678           destination at "-url".
679
680           "-local" points to a file, directory or series of files or
681           directories (indicated by a glob).
682
683           If the filename contains any of the characters `*',  `?' or  `['
684           it is a candidate for filename substitution, also  known  as
685           ``globbing''.   This word  is  then regarded as a pattern
686           (``glob-pattern''), and replaced with an alphabetically sorted list
687           of  file  names which match the pattern.
688
689           One can upload/put a string by passing a reference to a scalar in
690           the -local parameter. See example below.
691
692           put requires a working resource to be set before being called. See
693           "open".
694
695           The return value is always 1 or 0 indicating success or failure.
696
697           See get() for a description of what the optional callback parameter
698           does.
699
700           You can also pass a "-headers" argument. That allows one to specify
701           custom HTTP headers. It can be either a hashref with header names
702           and values, or a HTTP::Headers object.
703
704           put examples:
705
706           Put a string to the server:
707
708             my $myfile = "This is the contents of a file to be uploaded\n";
709             $d->put(-local=>\$myfile,-url=>"http://www.host.org/dav_dir/file.txt");
710
711           Put a local file to the server:
712
713             $d->put(-local=>"/tmp/index.html",-url=>"http://www.host.org/dav_dir/");
714
715           Put a series of local files to the server:
716
717             In these examples, /tmp contains file1.html, file1, file2.html,
718             file2.txt, file3.html, file2/
719
720             $d->put(-local=>"/tmp/file[12]*",-url=>"http://www.host.org/dav_dir/");
721
722             uploads file1.html, file1, file2.html, file2.txt and the directory file2/ to dav_dir/.
723
724       set_prop([URL],[NAMESPACE],PROPNAME,PROPVALUE)
725           Sets a property named "-propname" to "-propvalue" in the namespace
726           "-namespace" for "-url".
727
728           Requires a working resource to be set before being called. See
729           "open".
730
731           The return value is an "HTTP::DAV::Resource" object on success or 0
732           on failure.
733
734           The Resource object can be used for interrogating properties or
735           performing other operations.
736
737           Example:
738
739            if ( $r = $d->set_prop(-url=>$url,
740                         -namespace=>"dave",
741                         -propname=>"author",
742                         -propvalue=>"Patrick Collins"
743                        ) ) {
744               print "Author property set\n";
745            } else {
746               print "set_prop failed:" . $d->message . "\n";
747            }
748
749           See the note in propfind about namespace support in HTTP::DAV.
750           They're settable, but not readable.
751
752       steal([URL])
753           forcefully steals any locks held against URL.
754
755           steal will perform a propfind against URL and then, any locks that
756           are found will be unlocked one by one regardless of whether we own
757           them or not.
758
759           Requires a working resource to be set before being called. See
760           "open".
761
762           The return value is always 1 or 0 indicating success or failure. If
763           multiple locks are found and unlocking one of them fails then the
764           operation will be aborted.
765
766            if ($d->steal()) {
767               print "Steal succeeded\n";
768            } else {
769               print "Steal failed: ". $d->message() . "\n";
770            }
771
772       unlock([URL])
773           unlocks any of our locks on URL.
774
775           Requires a working resource to be set before being called. See
776           "open".
777
778           The return value is always 1 or 0 indicating success or failure.
779
780            if ($d->unlock()) {
781               print "Unlock succeeded\n";
782            } else {
783               print "Unlock failed: ". $d->message() . "\n";
784            }
785
786       unset_prop([URL],[NAMESPACE],PROPNAME)
787           Unsets a property named "-propname" in the namespace "-namespace"
788           for "-url".  Requires a working resource to be set before being
789           called. See "open".
790
791           The return value is an "HTTP::DAV::Resource" object on success or 0
792           on failure.
793
794           The Resource object can be used for interrogating properties or
795           performing other operations.
796
797           Example:
798
799            if ( $r = $d->unset_prop(-url=>$url,
800                         -namespace=>"dave",
801                         -propname=>"author",
802                        ) ) {
803               print "Author property was unset\n";
804            } else {
805               print "set_prop failed:" . $d->message . "\n";
806            }
807
808           See the note in propfind about namespace support in HTTP::DAV.
809           They're settable, but not readable.
810
811   ACCESSOR METHODS
812       get_user_agent
813           Returns the clients' working "HTTP::DAV::UserAgent" object.
814
815           You may want to interact with the "HTTP::DAV::UserAgent" object to
816           modify request headers or provide advanced authentication
817           procedures. See dave for an advanced authentication procedure.
818
819       get_last_request
820           Takes no arguments and returns the clients' last outgoing
821           "HTTP::Request" object.
822
823           You would only use this to inspect a request that has already
824           occurred.
825
826           If you would like to modify the "HTTP::Request" BEFORE the HTTP
827           request takes place (for instance to add another header), you will
828           need to get the "HTTP::DAV::UserAgent" using "get_user_agent" and
829           interact with that.
830
831       get_workingresource
832           Returns the currently "opened" or "working" resource
833           ("HTTP::DAV::Resource").
834
835           The working resource is changed whenever you open a url or use the
836           cwd command.
837
838           e.g.
839             $r = $d->get_workingresource
840             print "pwd: " . $r->get_uri . "\n";
841
842       get_workingurl
843           Returns the currently "opened" or "working" "URL".
844
845           The working resource is changed whenever you open a url or use the
846           cwd command.
847
848             print "pwd: " . $d->get_workingurl . "\n";
849
850       get_lockedresourcelist
851           Returns an "HTTP::DAV::ResourceList" object that represents all of
852           the locks we've created using THIS dav client.
853
854             print "pwd: " . $d->get_workingurl . "\n";
855
856       get_absolute_uri(REL_URI,[BASE_URI])
857           This is a useful utility function which joins "BASE_URI" and
858           "REL_URI" and returns a new URI.
859
860           If "BASE_URI" is not supplied then the current working resource (as
861           indicated by get_workingurl) is used. If "BASE_URI" is not set and
862           there is no current working resource the "REL_URI" will be
863           returned.
864
865           For instance:
866            $d->open("http://host.org/webdav/dir1/");
867
868            # Returns "http://host.org/webdav/dir2/"
869            $d->get_absolute_uri(-rel_uri=>"../dir2");
870
871            # Returns "http://x.org/dav/dir2/file.txt"
872            $d->get_absolute_uri(-rel_uri  =>"dir2/file.txt",
873                                 ->base_uri=>"http://x.org/dav/");
874
875           Note that it subtly takes care of trailing slashes.
876
877   ERROR HANDLING METHODS
878       message
879           "message" gets the last success or error message.
880
881           The return value is always a scalar (string) and will change
882           everytime a dav operation is invoked (lock, cwd, put, etc).
883
884           See also "errors" for operations which contain multiple error
885           messages.
886
887       errors
888           Returns an @array of error messages that had been set during a
889           multi-request operation.
890
891           Some of "HTTP::DAV"'s operations perform multiple request to the
892           server. At the time of writing only put and get are considered
893           multi-request since they can operate recursively requiring many
894           HTTP requests.
895
896           In these situations you should check the errors array if to
897           determine if any of the requests failed.
898
899           The "errors" function is used for multi-request operations and not
900           to be confused with a multi-status server response. A multi-status
901           server response is when the server responds with multiple error
902           messages for a SINGLE request. To deal with multi-status responses,
903           see "HTTP::DAV::Response".
904
905            # Recursive put
906            if (!$d->put( "/tmp/my_dir", $url ) ) {
907               # Get the overall message
908               print $d->message;
909               # Get the individual messages
910               foreach $err ( $d->errors ) { print "  Error:$err\n" }
911            }
912
913       is_success
914           Returns the status of the last DAV operation performed through the
915           HTTP::DAV interface.
916
917           This value will always be the same as the value returned from an
918           HTTP::DAV::method. For instance:
919
920             # This will always evaluate to true
921             ($d->lock($url) eq $d->is_success) ?
922
923           You may want to use the is_success method if you didn't capture the
924           return value immediately. But in most circumstances you're better
925           off just evaluating as follows:
926             if($d->lock($url)) { ... }
927
928       get_last_response
929           Takes no arguments and returns the last seen "HTTP::DAV::Response"
930           object.
931
932           You may want to use this if you have just called a propfind and
933           need the individual error messages returned in a MultiStatus.
934
935           If you find that you're using get_last_response() method a lot, you
936           may be better off using the more advanced "HTTP::DAV" interface and
937           interacting with the HTTP::DAV::* interfaces directly as discussed
938           in the intro. For instance, if you find that you're always wanting
939           a detailed understanding of the server's response headers or
940           messages, then you're probably better off using the
941           "HTTP::DAV::Resource" methods and interpreting the
942           "HTTP::DAV::Response" directly.
943
944           To perform detailed analysis of the server's response (if for
945           instance you got back a multistatus response) you can call
946           "get_last_response()" which will return to you the most recent
947           response object (always the result of the last operation, PUT,
948           PROPFIND, etc). With the returned HTTP::DAV::Response object you
949           can handle multi-status responses.
950
951           For example:
952
953              # Print all of the messages in a multistatus response
954              if (! $d->unlock($url) ) {
955                 $response = $d->get_last_response();
956                 if ($response->is_multistatus() ) {
957                   foreach $num ( 0 .. $response->response_count() ) {
958                      ($err_code,$mesg,$url,$desc) =
959                         $response->response_bynum($num);
960                      print "$mesg ($err_code) for $url\n";
961                   }
962                 }
963              }
964
965   ADVANCED METHODS
966       new_resource
967           Creates a new resource object with which to play.  This is the
968           preferred way of creating an "HTTP::DAV::Resource" object if
969           required.  Why? Because each Resource object needs to sit within a
970           global HTTP::DAV client.  Also, because the new_resource routine
971           checks the "HTTP::DAV" locked resource list before creating a new
972           object.
973
974               $dav->new_resource( -uri => "http://..." );
975
976       set_workingresource(URL)
977           Sets the current working resource to URL.
978
979           You shouldn't need this method. Call open or cwd to set the working
980           resource.
981
982           You CAN call "set_workingresource()" but you will need to perform a
983           "propfind" immediately following it to ensure that the working
984           resource is valid.
985

INSTALLATION, TODO, MAILING LISTS and REVISION HISTORY

987       [OUTDATED]
988
989       Please see the primary HTTP::DAV webpage at
990       (http://www.webdav.org/perldav/http-dav/) or the README file in this
991       library.
992

AUTHOR AND COPYRIGHT

1010       This module is Copyright (C) 2001-2008 by
1011
1012           Patrick Collins
1013           G03 Gloucester Place, Kensington
1014           Sydney, Australia
1015
1016           Email: pcollins@cpan.org
1017           Phone: +61 2 9663 4916
1018
1019       All rights reserved.
1020
1021       Current co-maintainer of the module is Cosimo Streppone for Opera
1022       Software ASA, opera@cpan.org.
1023
1024       You may distribute this module under the terms of either the GNU
1025       General Public License or the Artistic License, as specified in the
1026       Perl README file.
1027
1028
1029
1030perl v5.32.0                      2020-07-28                      HTTP::DAV(3)

NAME

SYNOPSIS

DESCRIPTION

METHODS

INSTALLATION, TODO, MAILING LISTS and REVISION HISTORY

SEE ALSO

AUTHOR AND COPYRIGHT