METHOD CALLING: Named vs Unnamed parameters

You can pass parameters to "HTTP::DAV" methods in one of two ways: named or unnamed.

Named parameters provides for a simpler/easier to use interface. A named interface affords more readability and allows the developer to ignore a specific order on the parameters. (named parameters are also case insensitive)

Each argument name is preceded by a dash. Neither case nor order matters in the argument list. -url, -Url, and -URL are all acceptable. In fact, only the first argument needs to begin with a dash. If a dash is present in the first argument, "HTTP::DAV" assumes dashes for the subsequent ones.

Each method can also be called with unnamed parameters which often makes sense for methods with only one parameter. But the developer will need to ensure that the parameters are passed in the correct order (as listed in the docs).

 Doc:     method( -url=>$url, [-depth=>$depth] )
 Named:   $d->method( -url=>$url, -depth=>$d ); # VALID
 Named:   $d->method( -Depth=>$d, -Url=>$url ); # VALID
 Named:   $d->method( Depth=>$d,  Url=>$url );  # INVALID (needs -)
 Named:   $d->method( -Arg2=>$val2 ); # INVALID, ARG1 is not optional
 Unnamed: $d->method( $val1 );        # VALID
 Unnamed: $d->method( $val2,$val1 );  # INVALID, ARG1 must come first.

IMPORTANT POINT!!!! If you specify a named parameter first but then forget for the second and third parameters, you WILL get weird things happen. E.g. this is bad:

 $d->method( -url=>$url, $arg2, $arg3 ); # BAD BAD BAD

THINGS YOU NEED TO KNOW

In all of the methods specified in "PUBLIC METHODS" there are some common concepts you'll need to understand:

• URLs represent an absolute or relative URI.

    -url=>"host.org/dav_dir/"  # Absolute
    -url=>"/dav_dir/"          # Relative
    -url=>"file.txt"           # Relative
      

  You can only use a relative URL if you have already "open"ed an absolute URL.

  The HTTP::DAV module now consistently uses the named parameter: URL. The lower-level HTTP::DAV::Resource interface inconsistently interchanges URL and URI. I'm working to resolve this, in the meantime, you'll just need to remember to use the right one by checking the documentation if you need to mix up your use of both interfaces.

• GLOBS

  Some methods accept wildcards in the URL. A wildcard can be used to indicate that the command should perform the command on all Resources that match the wildcard. These wildcards are called GLOBS.

  The glob may contain the characters "*", "?" and the set operator "[...]" where ... contains multiple characters ([1t2]) or a range such ([1-5]). For the curious, the glob is converted to a regex and then matched: "*" to ".*", "?" to ".", and the [] is left untouched.

  It is important to note that globs only operate at the leaf-level. For instance "/my_dir/*/file.txt" is not a valid glob.

  If a glob matches no URL's the command will fail (which normally means returns 0).

  Globs are useful in conjunction with CALLBACKS to provide feedback as each operation completes.

  See the documentation for each method to determine whether it supports globbing.

  Globs are useful for interactive style applications (see the source code for "dave" as an example).

  Example globs:

     $dav1->delete(-url=>"/my_dir/file[1-3]");     # Matches file1, file2, file3
     $dav1->delete(-url=>"/my_dir/file[1-3]*.txt");# Matches file1*.txt,file2*.txt,file3*.txt
     $dav1->delete(-url=>"/my_dir/*/file.txt");    # Invalid. Can only match at leaf-level
      

• CALLBACKS

  Callbacks are used by some methods (primarily get and put) to give the caller some insight as to how the operation is progressing. A callback allows you to define a subroutine as defined below and pass a reference (\&ref) to the method.

  The rationale behind the callback is that a recursive get/put or an operation against many files (using a "glob") can actually take a long time to complete.

  Example callback:

     $d->get( -url=>$url, -to=>$to, -callback=>\&mycallback );
      

  Your callback function MUST accept arguments as follows:
  sub cat_callback {
  my($status,$mesg,$url,$so_far,$length,$data) = @_;
  ...
  }

  The "status" argument specifies whether the operation has succeeded (1), failed (0), or is in progress (-1).

  The "mesg" argument is a status message. The status message could contain any string and often contains useful error messages or success messages.

  The "url" the remote URL.

  The "so_far", "length" - these parameters indicate how many bytes have been downloaded and how many we should expect. This is useful for doing "56% to go" style-gauges.

  The "data" parameter - is the actual data transferred. The "cat" command uses this to print the data to the screen. This value will be empty for "put".

  See the source code of "dave" for a useful sample of how to setup a callback.

  Note that these arguments are NOT named parameters.

  All error messages set during a "multi-operation" request (for instance a recursive get/put) are also retrievable via the "errors()" function once the operation has completed. See "ERROR HANDLING" for more information.

PUBLIC METHODS

new(USERAGENT)

new(USERAGENT, HEADERS)

Creates a new "HTTP::DAV" client

 $d = HTTP::DAV->new();
    

The "-useragent" parameter allows you to pass your own user agent object and expects an "HTTP::DAV::UserAgent" object. See the "dave" program for an advanced example of a custom UserAgent that interactively prompts the user for their username and password.

The "-headers" parameter allows you to specify a list of headers to be sent along with all requests. This can be either a hashref like:

  { "X-My-Header" => "value", ... }
    

or a HTTP::Headers object.

credentials(USER,PASS,[URL],[REALM])

sets authorization credentials for a "URL" and/or "REALM".

When the client hits a protected resource it will check these credentials to see if either the "URL" or "REALM" match the authorization response.

Either "URL" or "REALM" must be provided.

returns no value

Example:

 $d->credentials( -url=>'myhost.org:8080/test/',
                  -user=>'pcollins',
                  -pass=>'mypass');
    

DebugLevel($val)

sets the debug level to $val. 0=off 3=noisy.

$val default is 0.

returns no value.

When the value is greater than 1, the "HTTP::DAV::Comms" module will log all of the client<=>server interactions into /tmp/perldav_debug.txt.

DAV OPERATIONS

For all of the following operations, URL can be absolute (http://host.org/dav/) or relative (../dir2/). The only operation that requires an absolute URL is open.

copy(URL,DEST,[OVERWRITE],[DEPTH])

copies one remote resource to another

  $d->open(-url=>"host.org/dav_dir/");

  $d->copy(-url=>"dir1/", -dest=>"dir2/");

  $d->copy(-url=>"dir1/", -dest=>"dir2/",-overwrite=>0,-depth=>0);

  $d->cwd(-url=>"dir1/");
  $d->copy("file.txt","../dir2");

  $d->copy("file.txt","/dav_dir/dir2/new_file.txt")

cwd(URL)

changes the remote working directory.

This is synonymous to open except that the URL can be relative and may contain a "glob" (the first match in a glob will be used).

  $d->open("host.org/dav_dir/dir1/");
  $d->cwd("../dir2");
  $d->cwd(-url=>"../dir1");
    

The return value is always 1 or 0 indicating success or failure.

Requires a working resource to be set before being called. See "open".

You can not cwd to files, only collections (directories).

delete(URL)

deletes a remote resource.

  $d->open("host.org/dav_dir/");
  $d->delete("index.html");
  $d->delete("./dir1");
  $d->delete(-url=>"/dav_dir/dir2/file*",-callback=>\&mycallback);
    

"-url"

is the remote resource(s) you'd like to delete. It can be a file, directory or "glob".

"-callback" is a reference to a callback function which will be called everytime a file is deleted. This is mainly useful when used in conjunction with GLOBS deletes. See callbacks

The return value is always 1 or 0 indicating success or failure.

Requires a working resource to be set before being called. See "open".

This command will recursively delete directories. BE CAREFUL of uninitialised file variables in situation like this: $d->delete("$dir/$file"). This will trash your $dir if $file is not set.

get(URL,[TO],[CALLBACK])

downloads the file or directory at "URL" to the local location indicated by "TO".

  $d->open("host.org/dav_dir/");

  $d->get("my_dir/",".");

  $d->get("my_dir","/tmp",\&mycallback);

  $d->get(-url=>"/dav_dir/my_dir/index.html",-to=>"/tmp");

  $d->get("index.html","/tmp/index1.html");

  my $fh = new FileHandle;
  $fh->open(">/tmp/index1.html");
  $d->get("index.html",\$fh);

  my $file_contents;
  $d->get("index.html",\$file_contents);

  $d->get("file[12]*","/tmp");

  $d->get("file?.html","/tmp"); # downloads file1.html and file2.html but not file3.html or file1.txt

  $d->get("/dav_dir/*/index.html","/tmp"); # Can not glob like this.

lock([URL],[OWNER],[DEPTH],[TIMEOUT],[SCOPE],[TYPE])

locks a resource. If URL is not specified, it will lock the current working resource (opened resource).

   $d->lock( -url     => "index.html",
             -owner   => "Patrick Collins",
             -depth   => "infinity",
             -scope   => "exclusive",
             -type    => "write",
             -timeout => "10h" )
    

See "HTTP::DAV::Resource" lock() for details of the above parameters.

The return value is always 1 or 0 indicating success or failure.

Requires a working resource to be set before being called. See "open".

When you lock a resource, the lock is held against the current HTTP::DAV object. In fact, the locks are held in a "HTTP::DAV::ResourceList" object. You can operate against all of the locks that you have created as follows:

  ## Print and unlock all locks that we own.
  my $rl_obj = $d->get_lockedresourcelist();
  foreach $resource ( $rl_obj->get_resources() ) {
      @locks = $resource->get_locks(-owned=>1);
      foreach $lock ( @locks ) { 
        print $resource->get_uri . "\n";
        print $lock->as_string . "\n";
      }
      ## Unlock them?
      $resource->unlock;
  }
    

Typically, a simple $d->unlock($uri) will suffice.

lock example

  $d->lock($uri, -timeout=>"1d");
  ...
  $d->put("/tmp/index.html",$uri);
  $d->unlock($uri);
    

mkcol(URL)

make a remote collection (directory)

The return value is always 1 or 0 indicating success or failure.

Requires a working resource to be set before being called. See "open".

  $d->open("host.org/dav_dir/");
  $d->mkcol("new_dir");                  # Should succeed
  $d->mkcol("/dav_dir/new_dir");         # Should succeed
  $d->mkcol("/dav_dir/new_dir/xxx/yyy"); # Should fail
    

move(URL,DEST,[OVERWRITE],[DEPTH])

moves one remote resource to another

  $d->open(-url=>"host.org/dav_dir/");

  $d->move(-url=>"dir1/", -dest=>"dir2/");

  $d->move(-url=>"dir1/", -dest=>"dir2/",-overwrite=>0);

  $d->cwd(-url=>"dir1/");
  $d->move("file.txt","../dir2");

  $d->move("file.txt","/dav_dir/dir2/new_file.txt")

open(URL)

opens the directory (collection resource) at URL.

open will perform a propfind against URL. If the server does not understand the request then the open will fail.

Similarly, if the server indicates that the resource at URL is NOT a collection, the open command will fail.

options([URL])

Performs an OPTIONS request against the URL or the working resource if URL is not supplied.

Requires a working resource to be set before being called. See "open".

The return value is a string of comma separated OPTIONS that the server states are legal for URL or undef otherwise.

A fully compliant DAV server may offer as many methods as: OPTIONS, TRACE, GET, HEAD, DELETE, PUT, COPY, MOVE, PROPFIND, PROPPATCH, LOCK, UNLOCK

Note: IIS5 does not support PROPPATCH or LOCK on collections.

Example:

 $options = $d->options($url);
 print $options . "\n";
 if ($options=~ /\bPROPPATCH\b/) {
    print "OK to proppatch\n";
 }
    

Or, put more simply:

 if ( $d->options($url) =~ /\bPROPPATCH\b/ ) {
    print "OK to proppatch\n";
 }
    

propfind([URL],[DEPTH])

Perform a propfind against URL at DEPTH depth.

"-depth" can be used to specify how deep the propfind goes. "0" is collection only. "1" is collection and it's immediate members (This is the default value). "infinity" is the entire directory tree. Note that most DAV compliant servers deny "infinity" depth propfinds for security reasons.

Requires a working resource to be set before being called. See "open".

The return value is an "HTTP::DAV::Resource" object on success or 0 on failure.

The Resource object can be used for interrogating properties or performing other operations.

 ## Print collection or content length
 if ( $r=$d->propfind( -url=>"/my_dir", -depth=>1) ) {
    if ( $r->is_collection ) {
       print "Collection\n" 
       print $r->get_resourcelist->as_string . "\n"
    } else {
       print $r->get_property("getcontentlength") ."\n";
    }
 }
    

Please note that although you may set a different namespace for a property of a resource during a set_prop, HTTP::DAV currently ignores all XML namespaces so you will get clashes if two properties have the same name but in different namespaces. Currently this is unavoidable but I'm working on the solution.

proppatch([URL],[NAMESPACE],PROPNAME,PROPVALUE,ACTION,[NSABBR])

If "-action" equals "set" then we set a property named "-propname" to "-propvalue" in the namespace "-namespace" for "-url".

If "-action" equals "remove" then we unset a property named "-propname" in the namespace "-namespace" for "-url".

If no action is supplied then the default action is "set".

The return value is an "HTTP::DAV::Resource" object on success or 0 on failure.

The Resource object can be used for interrogating properties or performing other operations.

To explicitly set a namespace in which to set the propname then you can use the "-namespace" and "-nsabbr" (namespace abbreviation) parameters. But you're welcome to play around with DAV namespaces.

Requires a working resource to be set before being called. See "open".

It is recommended that you use "set_prop" and "unset_prop" instead of proppatch for readability.

"set_prop" simply calls "proppatch(-action="set)> and "unset_prop" calls "proppatch(-action=""remove")>

See "set_prop" and "unset_prop" for examples.

put(LOCAL,[URL],[CALLBACK],[HEADERS])

uploads the files or directories at "-local" to the remote destination at "-url".

"-local" points to a file, directory or series of files or directories (indicated by a glob).

If the filename contains any of the characters `*', `?' or `[' it is a candidate for filename substitution, also known as ``globbing''. This word is then regarded as a pattern (``glob-pattern''), and replaced with an alphabetically sorted list of file names which match the pattern.

One can upload/put a string by passing a reference to a scalar in the -local parameter. See example below.

put requires a working resource to be set before being called. See "open".

The return value is always 1 or 0 indicating success or failure.

See get() for a description of what the optional callback parameter does.

You can also pass a "-headers" argument. That allows one to specify custom HTTP headers. It can be either a hashref with header names and values, or a HTTP::Headers object.

put examples:

Put a string to the server:

  my $myfile = "This is the contents of a file to be uploaded\n";
  $d->put(-local=>\$myfile,-url=>"http://www.host.org/dav_dir/file.txt");
    

Put a local file to the server:

  $d->put(-local=>"/tmp/index.html",-url=>"http://www.host.org/dav_dir/");
    

Put a series of local files to the server:

  In these examples, /tmp contains file1.html, file1, file2.html, 
  file2.txt, file3.html, file2/
  $d->put(-local=>"/tmp/file[12]*",-url=>"http://www.host.org/dav_dir/");
  
  uploads file1.html, file1, file2.html, file2.txt and the directory file2/ to dav_dir/.
    

set_prop([URL],[NAMESPACE],PROPNAME,PROPVALUE)

Sets a property named "-propname" to "-propvalue" in the namespace "-namespace" for "-url".

Requires a working resource to be set before being called. See "open".

The return value is an "HTTP::DAV::Resource" object on success or 0 on failure.

The Resource object can be used for interrogating properties or performing other operations.

Example:

 if ( $r = $d->set_prop(-url=>$url,
              -namespace=>"dave",
              -propname=>"author",
              -propvalue=>"Patrick Collins"
             ) ) {
    print "Author property set\n";
 } else {
    print "set_prop failed:" . $d->message . "\n";
 }
    

See the note in propfind about namespace support in HTTP::DAV. They're settable, but not readable.

steal([URL])

forcefully steals any locks held against URL.

steal will perform a propfind against URL and then, any locks that are found will be unlocked one by one regardless of whether we own them or not.

Requires a working resource to be set before being called. See "open".

The return value is always 1 or 0 indicating success or failure. If multiple locks are found and unlocking one of them fails then the operation will be aborted.

 if ($d->steal()) {
    print "Steal succeeded\n";
 } else {
    print "Steal failed: ". $d->message() . "\n";
 }
    

unlock([URL])

unlocks any of our locks on URL.

Requires a working resource to be set before being called. See "open".

The return value is always 1 or 0 indicating success or failure.

 if ($d->unlock()) {
    print "Unlock succeeded\n";
 } else {
    print "Unlock failed: ". $d->message() . "\n";
 }
    

unset_prop([URL],[NAMESPACE],PROPNAME)

Unsets a property named "-propname" in the namespace "-namespace" for "-url". Requires a working resource to be set before being called. See "open".

The return value is an "HTTP::DAV::Resource" object on success or 0 on failure.

The Resource object can be used for interrogating properties or performing other operations.

Example:

 if ( $r = $d->unset_prop(-url=>$url,
              -namespace=>"dave",
              -propname=>"author",
             ) ) {
    print "Author property was unset\n";
 } else {
    print "set_prop failed:" . $d->message . "\n";
 }
    

See the note in propfind about namespace support in HTTP::DAV. They're settable, but not readable.

ACCESSOR METHODS

get_user_agent

Returns the clients' working "HTTP::DAV::UserAgent" object.

You may want to interact with the "HTTP::DAV::UserAgent" object to modify request headers or provide advanced authentication procedures. See dave for an advanced authentication procedure.

get_last_request

Takes no arguments and returns the clients' last outgoing "HTTP::Request" object.

You would only use this to inspect a request that has already occurred.

If you would like to modify the "HTTP::Request" BEFORE the HTTP request takes place (for instance to add another header), you will need to get the "HTTP::DAV::UserAgent" using "get_user_agent" and interact with that.

get_workingresource

Returns the currently "opened" or "working" resource ("HTTP::DAV::Resource").

The working resource is changed whenever you open a url or use the cwd command.

e.g.
$r = $d->get_workingresource
print "pwd: " . $r->get_uri . "\n";

get_workingurl

Returns the currently "opened" or "working" "URL".

The working resource is changed whenever you open a url or use the cwd command.

  print "pwd: " . $d->get_workingurl . "\n";
    

get_lockedresourcelist

Returns an "HTTP::DAV::ResourceList" object that represents all of the locks we've created using THIS dav client.

  print "pwd: " . $d->get_workingurl . "\n";
    

get_absolute_uri(REL_URI,[BASE_URI])

This is a useful utility function which joins "BASE_URI" and "REL_URI" and returns a new URI.

If "BASE_URI" is not supplied then the current working resource (as indicated by get_workingurl) is used. If "BASE_URI" is not set and there is no current working resource the "REL_URI" will be returned.

For instance:
$d->open("http://host.org/webdav/dir1/");

 # Returns "http://host.org/webdav/dir2/"
 $d->get_absolute_uri(-rel_uri=>"../dir2");
 # Returns "http://x.org/dav/dir2/file.txt"
 $d->get_absolute_uri(-rel_uri  =>"dir2/file.txt",
                      ->base_uri=>"http://x.org/dav/");
    

Note that it subtly takes care of trailing slashes.

ERROR HANDLING METHODS

message

"message" gets the last success or error message.

The return value is always a scalar (string) and will change everytime a dav operation is invoked (lock, cwd, put, etc).

See also "errors" for operations which contain multiple error messages.

errors

Returns an @array of error messages that had been set during a multi-request operation.

Some of "HTTP::DAV"'s operations perform multiple request to the server. At the time of writing only put and get are considered multi-request since they can operate recursively requiring many HTTP requests.

In these situations you should check the errors array if to determine if any of the requests failed.

The "errors" function is used for multi-request operations and not to be confused with a multi-status server response. A multi-status server response is when the server responds with multiple error messages for a SINGLE request. To deal with multi-status responses, see "HTTP::DAV::Response".

 # Recursive put
 if (!$d->put( "/tmp/my_dir", $url ) ) {
    # Get the overall message
    print $d->message;
    # Get the individual messages
    foreach $err ( $d->errors ) { print "  Error:$err\n" }
 }
    

is_success

Returns the status of the last DAV operation performed through the HTTP::DAV interface.

This value will always be the same as the value returned from an HTTP::DAV::method. For instance:

  # This will always evaluate to true
  ($d->lock($url) eq $d->is_success) ?
    

You may want to use the is_success method if you didn't capture the return value immediately. But in most circumstances you're better off just evaluating as follows:
if($d->lock($url)) { ... }

get_last_response

Takes no arguments and returns the last seen "HTTP::DAV::Response" object.

You may want to use this if you have just called a propfind and need the individual error messages returned in a MultiStatus.

If you find that you're using get_last_response() method a lot, you may be better off using the more advanced "HTTP::DAV" interface and interacting with the HTTP::DAV::* interfaces directly as discussed in the intro. For instance, if you find that you're always wanting a detailed understanding of the server's response headers or messages, then you're probably better off using the "HTTP::DAV::Resource" methods and interpreting the "HTTP::DAV::Response" directly.

To perform detailed analysis of the server's response (if for instance you got back a multistatus response) you can call "get_last_response()" which will return to you the most recent response object (always the result of the last operation, PUT, PROPFIND, etc). With the returned HTTP::DAV::Response object you can handle multi-status responses.

For example:

   # Print all of the messages in a multistatus response
   if (! $d->unlock($url) ) {
      $response = $d->get_last_response();
      if ($response->is_multistatus() ) {
        foreach $num ( 0 .. $response->response_count() ) {
           ($err_code,$mesg,$url,$desc) =
              $response->response_bynum($num);
           print "$mesg ($err_code) for $url\n";
        }
      }
   }
    

ADVANCED METHODS

new_resource

Creates a new resource object with which to play. This is the preferred way of creating an "HTTP::DAV::Resource" object if required. Why? Because each Resource object needs to sit within a global HTTP::DAV client. Also, because the new_resource routine checks the "HTTP::DAV" locked resource list before creating a new object.

    $dav->new_resource( -uri => "http://..." );
    

set_workingresource(URL)

Sets the current working resource to URL.

You shouldn't need this method. Call open or cwd to set the working resource.

You CAN call "set_workingresource()" but you will need to perform a "propfind" immediately following it to ensure that the working resource is valid.