webdav(n) 0.2 "webdav"

NAME

webdav - WebDAV client

SYNOPSIS

package require Tcl 8.4
package require webdav ?0.2?

::webdav::open url ?options?
::webdav::close conn
::webdav::enumerate conn path depth
::webdav::getstat conn path
::webdav::getlist conn ?path?
::webdav::get conn path
::webdav::put conn path data
::webdav::copy conn srcpath destpath
::webdav::mkdir conn path
::webdav::delete conn path
::webdav::connect url ?options?

DESCRIPTION

This package implements a client for the WebDAV protocol. DAV stands for "Distributed Authoring and Versioning" - it can be used to browse and modify remote sites such as webservers, treating the hierarchy like a filesystem. See http://www.webdav.org for specifications and details.

Since one of the uses of this package is to support a VFS handler, the terminology used in this package corresponds to that of file systems, i.e. "files" and "directories" (the WebDAV standard uses the terms "resource" and "collection" for these same terms, respectively).

COMMANDS

::webdav::open url ?options?
Set up a new connection to the webdav server identified by url. This webdav package operates conceptually in terms of "connections", although connections are in fact stateless, so this is not entirely accurate. In reality, the open call just verifies that the url is valid and sets things up for all other calls to use the same path and options.

Additional options:

-username name
Username to use for authorization. Must be used in combination with the -password option.

-password pass
Password to use for authorization. Must be used in combination with the -username option.
The return value is a descriptor which can be used for all other functions. The descriptor should be released at the end by calling ::webdav::close.

::webdav::close conn
Closes a previously opened wevdab connection. Since connections are stateless, this only cleans up internal state: no network actions take place, servers are not aware of this closing step.

::webdav::enumerate conn path depth
Returns a pairwise list of all entries in a directory as well as filestat details. The first pair in the list describes the directory itself.

The path argument can be a file or a directory. It can also be "." or "" or absent to use the root of the tree. Use depth 1 to list all items in the directory, or 0 to only return status info about the directory or file itself. This command is mostly for use by ::webdav::getstat and ::webdav::getlist.

See below for a description of the status details.

::webdav::getstat conn path
Returns some information about the specified file or directory.

The return value is a list of key/value pairs, suitable for "array get":

type type
Type of resource, either "file" or "directory".

ctime secs
Creation time of resource.

mtime secs
Modification time of resource.

size bytes
Size of resource (files only).
::webdav::getlist conn ?path?
Returns a list of all entries in a directory. Path should be a subdirectory of the location specified as url during the open call, it can also be "." or "" or absent to use the root of the tree.

::webdav::get conn path
Return the contents of the specified file. Not meaningul for directories.

::webdav::put conn path data
Store new data in the specified file. The file is either created or overwritten.

::webdav::copy conn srcpath destpath
Copy the specified file or directory to a new location. Directories are copied recursively, i.e. including all contents.

::webdav::mkdir conn path
Create a directory in the specified location. Fails if the parent directory does not exist, or if the directory itself already exists.

::webdav::delete conn path
Delete the specified file or directory. Directories are deleted recursively, i.e. including all contents. Fails if the file or directory does not exist.

::webdav::connect url ?options?
This is an OO variant of the ::webdav::open command. See below for an example of use.

EXAMPLES

The following example expects a server with an empty home directory:

 
% set dav [::webdav::open http://some.site/some/dir]
dav1
% ::webdav::put $dav myfile "here is some data"
% ::webdav::getlist $dav
myfile
% puts [::webdav::get $dav myfile]
here is some data
% ::webdav::delete $dav myfile
% ::webdav::close $dav
%

There is also an object-oriented interface in the webdav package. It works by using ::webdav::connect instead of ::webdav::open. The above example can be re-written to do exactly the same in OO style:

 
% set dav [::webdav::connect http://some.site/some/dir]
::webdav::obj::dav1
% $dav put myfile "here is some data"
% $dav getlist
myfile
% puts [$dav get myfile]
here is some data
% $dav delete myfile
% $dav close
%

The choice between commands and OO is a matter of preference. Both calls can be mixed, the OO style is just a thin wrapper.

REFERENCES

  1. RFC 2518 - HTTP Extensions for Distributed Authoring -- WEBDAV (http://www.webdav.org/specs/rfc2518.html)

KEYWORDS

DAV, WebDAV

COPYRIGHT

Copyright © 2004, Jean-Claude Wippler <jcw@equi4.com>