HTTP-DAV
view release on metacpan or search on metacpan
doc/html/HTTP-DAV.html view on Meta::CPAN
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>HTTP::DAV - A WebDAV client library for Perl5</title>
<link rel="stylesheet" href="perldav_plain.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>
<body>
<h1 id="NAME">NAME</h1>
<p>HTTP::DAV - A WebDAV client library for Perl5</p>
<h1 id="SYNOPSIS">SYNOPSIS</h1>
<pre><code> # DAV script that connects to a webserver, safely makes
# a new directory and uploads all html files in
# the /tmp directory.
use HTTP::DAV;
$d = HTTP::DAV->new();
$url = "http://host.org:8080/dav/";
$d->credentials(
-user => "pcollins",
-pass => "mypass",
-url => $url,
-realm => "DAV Realm"
);
$d->open( -url => $url )
or die("Couldn't open $url: " .$d->message . "\n");
# Make a null lock on newdir
$d->lock( -url => "$url/newdir", -timeout => "10m" )
or die "Won't put unless I can lock for 10 minutes\n";
# Make a new directory
$d->mkcol( -url => "$url/newdir" )
or die "Couldn't make newdir at $url\n";
# Upload multiple files to newdir.
if ( $d->put( -local => "/tmp/*.html", -url => $url ) ) {
print "successfully uploaded multiple files to $url\n";
} else {
print "put failed: " . $d->message . "\n";
}
$d->unlock( -url => $url );</code></pre>
<h1 id="DESCRIPTION">DESCRIPTION</h1>
<p>HTTP::DAV is a Perl API for interacting with and modifying content on webservers using the WebDAV protocol. Now you can LOCK, DELETE and PUT files and much more on a DAV-enabled webserver.</p>
<p>HTTP::DAV is part of the PerlDAV project hosted at http://www.webdav.org/perldav/ and has the following features:</p>
<ul>
<li><p>Full RFC2518 method support. OPTIONS, TRACE, GET, HEAD, DELETE, PUT, COPY, MOVE, PROPFIND, PROPPATCH, LOCK, UNLOCK.</p>
</li>
<li><p>A fully object-oriented API.</p>
</li>
<li><p>Recursive GET and PUT for site backups and other scripted transfers.</p>
</li>
<li><p>Transparent lock handling when performing LOCK/COPY/UNLOCK sequences.</p>
</li>
<li><p>http and https support (https requires the Crypt::SSLeay library). See INSTALLATION.</p>
</li>
<li><p>Basic AND Digest authentication support (Digest auth requires the MD5 library). See INSTALLATION.</p>
</li>
<li><p><code>dave</code>, a fully-functional ftp-style interface written on top of the HTTP::DAV API and bundled by default with the HTTP::DAV library. (If you've already installed HTTP::DAV, then dave will also have been installed (probably into...
</li>
<li><p>It is built on top of the popular LWP (Library for WWW access in Perl). This means that HTTP::DAV inherits proxy support, redirect handling, basic (and digest) authorization and many other HTTP operations. See <code>LWP</code> for more informa...
</li>
<li><p>Popular server support. HTTP::DAV has been tested against the following servers: mod_dav, IIS5, Xythos webfile server and mydocsonline. The library is growing an impressive interoperability suite which also serves as useful "sample script...
doc/html/HTTP-DAV.html view on Meta::CPAN
<pre><code>$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</code></pre>
</li>
<li><p>CALLBACKS</p>
<p>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.</p>
<p>The rationale behind the callback is that a recursive get/put or an operation against many files (using a <code>glob</code>) can actually take a long time to complete.</p>
<p>Example callback:</p>
<pre><code>$d->get( -url=>$url, -to=>$to, -callback=>\&mycallback );</code></pre>
<p>Your callback function MUST accept arguments as follows: sub cat_callback { my($status,$mesg,$url,$so_far,$length,$data) = @_; ... }</p>
<p>The <code>status</code> argument specifies whether the operation has succeeded (1), failed (0), or is in progress (-1).</p>
<p>The <code>mesg</code> argument is a status message. The status message could contain any string and often contains useful error messages or success messages.</p>
<p>The <code>url</code> the remote URL.</p>
<p>The <code>so_far</code>, <code>length</code> - 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.</p>
<p>The <code>data</code> parameter - is the actual data transferred. The <code>cat</code> command uses this to print the data to the screen. This value will be empty for <code>put</code>.</p>
<p>See the source code of <code>dave</code> for a useful sample of how to setup a callback.</p>
<p>Note that these arguments are NOT named parameters.</p>
<p>All error messages set during a "multi-operation" request (for instance a recursive get/put) are also retrievable via the <code>errors()</code> function once the operation has completed. See <code>ERROR HANDLING</code> for more informati...
</li>
</ul>
<h2 id="PUBLIC-METHODS">PUBLIC METHODS</h2>
<dl>
<dt id="new-USERAGENT"><b>new(USERAGENT)</b></dt>
<dd>
</dd>
<dt id="new-USERAGENT-HEADERS"><b>new(USERAGENT, HEADERS)</b></dt>
<dd>
<p>Creates a new <code>HTTP::DAV</code> client</p>
<pre><code>$d = HTTP::DAV->new();</code></pre>
<p>The <code>-useragent</code> parameter allows you to pass your own <b>user agent object</b> and expects an <code>HTTP::DAV::UserAgent</code> object. See the <code>dave</code> program for an advanced example of a custom UserAgent that interactively ...
<p>The <code>-headers</code> parameter allows you to specify a list of headers to be sent along with all requests. This can be either a hashref like:</p>
<pre><code>{ "X-My-Header" => "value", ... }</code></pre>
<p>or a <a>HTTP::Headers</a> object.</p>
</dd>
<dt id="credentials-USER-PASS-URL-REALM"><b>credentials(USER,PASS,[URL],[REALM])</b></dt>
<dd>
<p>sets authorization credentials for a <code>URL</code> and/or <code>REALM</code>.</p>
<p>When the client hits a protected resource it will check these credentials to see if either the <code>URL</code> or <code>REALM</code> match the authorization response.</p>
<p>Either <code>URL</code> or <code>REALM</code> must be provided.</p>
<p>returns no value</p>
<p>Example:</p>
<pre><code>$d->credentials( -url=>'myhost.org:8080/test/',
-user=>'pcollins',
-pass=>'mypass');</code></pre>
</dd>
<dt id="DebugLevel-val"><b>DebugLevel($val)</b></dt>
<dd>
<p>sets the debug level to <code>$val</code>. 0=off 3=noisy.</p>
<p><code>$val</code> default is 0.</p>
<p>returns no value.</p>
<p>When the value is greater than 1, the <code>HTTP::DAV::Comms</code> module will log all of the client<=>server interactions into /tmp/perldav_debug.txt.</p>
</dd>
</dl>
<h2 id="DAV-OPERATIONS">DAV OPERATIONS</h2>
<p>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.</p>
<dl>
<dt id="copy-URL-DEST-OVERWRITE-DEPTH"><b>copy(URL,DEST,[OVERWRITE],[DEPTH])</b></dt>
<dd>
<p>copies one remote resource to another</p>
<dl>
<dt id="url"><code>-url</code></dt>
<dd>
<p>is the remote resource you'd like to copy. Mandatory</p>
</dd>
<dt id="dest"><code>-dest</code></dt>
<dd>
<p>is the remote target for the copy command. Mandatory</p>
</dd>
<dt id="overwrite"><code>-overwrite</code></dt>
<dd>
<p>optionally indicates whether the server should fail if the target exists. Valid values are "T" and "F" (1 and 0 are synonymous). Default is T.</p>
</dd>
<dt id="depth"><code>-depth</code></dt>
<dd>
<p>optionally indicates whether the server should do a recursive copy or not. Valid values are 0 and (1 or "infinity"). Default is "infinity" (1).</p>
</dd>
</dl>
<p>The return value is always 1 or 0 indicating success or failure.</p>
<p>Requires a working resource to be set before being called. See <code>open</code>.</p>
( run in 0.652 second using v1.01-cache-2.11-cpan-39bf76dae61 )