/ 
Net-DAVTalk-0.25
/ Net::DAVTalk

NAME

Net::DAVTalk - Interface to talk to DAV servers

VERSION

Version 0.24

SYNOPSIS

Net::DAVTalk is was originally designed as a service module for Net::CalDAVTalk and Net::CardDAVTalk, abstracting the process of connecting to a DAV server and parsing the XML responses.

Example:

use Net::DAVTalk;
use XML::Spice;

my $davtalk = Net::DAVTalk->new(
    url => "https://dav.example.com/",
    user => "foo\@example.com",
    password => "letmein",
    headers => { Cookie => "123", Referer => "456" },
);

$davtalk->Request(
    'MKCALENDAR',
    "$calendarId/",
    x('C:mkcalendar', $Self->NS(),
        x('D:set',
             x('D:prop', @Properties),
        ),
    ),
);

$davtalk->Request(
    'DELETE',
    "$calendarId/",
);

SUBROUTINES/METHODS

$class->new(%Options)

Options:

url: either full https?:// url, or relative base path on the
server to the DAV endpoint

host, scheme and port: alternative to using full URL.
If URL doesn't start with https?:// then these will be used to
construct the endpoint URI.

expandurl and wellknown: if these are set, then the wellknown
name (caldav and carddav are both defined) will be used to
resolve /.well-known/$wellknown to find the current-user-principal
URI, and then THAT will be resovlved to find the $wellknown-home-set
URI, which will be used as the URL for all further actions on
this object.

user and password: if these are set, perform basic authentication.
user and access_token: if these are set, perform Bearer (OAUTH2)
authentication.

headers: a hashref of additional headers to add to every request

SSL_options: a hashref of SSL options to pass down to the default
user agent

my $ua = $Self->ua(); =head2 $Self->ua($setua);

Get or set the useragent (HTTP::Tiny or compatible) that will be used to make the requests:

e.g.

my $ua = $Self->ua();

$Self->ua(HTTP::Tiny->new(agent => "MyAgent/1.0", timeout => 5));

$Self->SetURL($url)

Change the endpoint URL for an existing connection.

$Self->SetPrincipalURL($url)

Set the URL to the DAV Principal

$Self->fullpath($shortpath)

Convert from a relative path to a full path:

e.g my $path = $Dav->fullpath('Default'); ## /dav/calendars/user/foo/Default

NOTE: a you can pass a non-relative full path (leading /) to this function and it will be returned unchanged.

$Self->shortpath($fullpath)

Convert from a full path to a relative path

e.g my $path = $Dav->fullpath('/dav/calendars/user/foo/Default'); ## Default

NOTE: if the full path is outside the basepath of the object, it will be unchanged.

my $path = $Dav->fullpath('/dav/calendars/user/bar/Default');
## /dav/calendars/user/bar/Default

$Self->Request($method, $path, $content, %headers)

The whole point of the module! Perform a DAV request against the endpoint, returning the response as a parsed hash.

method: http method, i.e. GET, PROPFIND, MKCOL, DELETE, etc

path: relative to base url.  With a leading slash, relative to
      server root, i.e. "Default/", "/dav/calendars/user/foo/Default".

content: if the method takes a body, raw bytes to send

headers: additional headers to add to request, i.e (Depth => 1)

In the event of timeout or most HTTP errors, an exception will be raised.

$Self->SafeRequest($method, $path, $content, %headers)

my $Result = $DAVTalk->SafeRequest($method, $path, $content, %headers)

This is mostly Request, but it won't throw an exception on most errors.

Instead, it always returns a reference to a hash with these entries:

payload       - a structured representation of the DAV response, if possible;
                this is the same thing that the ->Request method returns
http_response - the underlying HTTP response from HTTP::Tiny
error         - a string describing the error condition, if any

The Request method uses SafeRequest under the hood, converting error results into exceptions.

$Self->GetProps($Path, @Props)

perform a propfind on a particular path and get the properties back

$Self->GetPropsArray($Path, @Props)

perform a propfind on a particular path and get the properties back as an array of one or more items

$Self->GetCurrentUserPrincipal() =head2 $class->GetCurrentUserPrincipal(%Args)

Can be called with the same args as new() as a class method, or on an existing object. Either way it will use the .well-known URI to find the path to the current-user-principal.

Returns a string with the path.

$Self->GetHomeSet =head2 $class->GetHomeSet(%Args)

Can be called with the same args as new() as a class method, or on an existing object. Either way it assumes that the created object has a 'url' parameter pointing at the current user principal URL (see GetCurrentUserPrincipal above)

Returns a string with the path to the home set.

$Self->genuuid()

Helper to generate a uuid string. Returns a UUID, e.g.

my $uuid = $DAVTalk->genuuid(); # 9b9d68af-ad13-46b8-b7ab-30ab70da14ac

$Self->auth_header()

Generate the authentication header to use on requests:

e.g:

$Headers{'Authorization'} = $Self->auth_header();

$Self->request_url()

Generate the authentication header to use on requests:

e.g:

$Headers{'Authorization'} = $Self->auth_header();

$Self->NS()

Returns a hashref of the 'xmlns:shortname' => 'full namespace' items for use in XML::Spice body generation, e.g.

$DAVTalk->Request(
    'MKCALENDAR',
    "$calendarId/",
    x('C:mkcalendar', $Self->NS(),
        x('D:set',
             x('D:prop', @Properties),
        ),
    ),
);

# { 'xmlns:C' => 'urn:ietf:params:xml:ns:caldav', 'xmlns:D' => 'DAV:' }

$Self->ns($key, $value)

Get or set namespace aliases, e.g

$Self->ns(C => 'urn:ietf:params:xml:ns:caldav');
my $NS_C = $Self->ns('C'); # urn:ietf:params:xml:ns:caldav

function2

AUTHOR

Bron Gondwana, <brong at cpan.org>

BUGS

Please report any bugs or feature requests to bug-net-davtalk at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-DAVTalk. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::DAVTalk

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2015-2026 Fastmail Pty Ltd.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself; that is, either the GNU General Public License as published by the Free Software Foundation (version 1, or at your option any later version), or the Artistic License.

See http://dev.perl.org/licenses/ and the LICENSE file included with this distribution for more information.