1Net::DAVTalk(3)       User Contributed Perl Documentation      Net::DAVTalk(3)
2
3
4

NAME

6       Net::DAVTalk - Interface to talk to DAV servers
7

VERSION

9       Version 0.18
10

SYNOPSIS

12       Net::DAVTalk is was originally designed as a service module for
13       Net::CalDAVTalk and Net::DAVTalk, abstracting the process of connecting
14       to a DAV server and parsing the XML responses.
15
16       Example:
17
18           use Net::DAVTalk;
19           use XML::Spice;
20
21           my $davtalk = Net::DAVTalk->new(
22               url => "https://dav.example.com/",
23               user => "foo\@example.com",
24               password => "letmein",
25           );
26
27           $davtalk->Request(
28               'MKCALENDAR',
29               "$calendarId/",
30               x('C:mkcalendar', $Self->NS(),
31                   x('D:set',
32                        x('D:prop', @Properties),
33                   ),
34               ),
35           );
36
37           $davtalk->Request(
38               'DELETE',
39               "$calendarId/",
40           );
41

SUBROUTINES/METHODS

43   $class->new(%Options)
44       Options:
45
46           url: either full https?:// url, or relative base path on the
47           server to the DAV endpoint
48
49           host, scheme and port: alternative to using full URL.
50           If URL doesn't start with https?:// then these will be used to
51           construct the endpoint URI.
52
53           expandurl and wellknown: if these are set, then the wellknown
54           name (caldav and carddav are both defined) will be used to
55           resolve /.well-known/$wellknown to find the current-user-principal
56           URI, and then THAT will be resovlved to find the $wellknown-home-set
57           URI, which will be used as the URL for all further actions on
58           this object.
59
60           user and password: if these are set, perform basic authentication.
61           user and access_token: if these are set, perform Bearer (OAUTH2)
62           authentication.
63
64   my $ua = $Self->ua(); =head2 $Self->ua($setua);
65       Get or set the useragent (HTTP::Tiny or compatible) that will be used
66       to make the requests:
67
68       e.g.
69
70           my $ua = $Self->ua();
71
72           $Self->ua(HTTP::Tiny->new(agent => "MyAgent/1.0", timeout => 5));
73
74   $Self->SetURL($url)
75       Change the endpoint URL for an existing connection.
76
77   $Self->SetPrincipalURL($url)
78       Set the URL to the DAV Principal
79
80   $Self->fullpath($shortpath)
81       Convert from a relative path to a full path:
82
83       e.g
84           my $path = $Dav->fullpath('Default');
85           ## /dav/calendars/user/foo/Default
86
87       NOTE: a you can pass a non-relative full path (leading /) to this
88       function and it will be returned unchanged.
89
90   $Self->shortpath($fullpath)
91       Convert from a full path to a relative path
92
93       e.g
94           my $path = $Dav->fullpath('/dav/calendars/user/foo/Default');
95           ## Default
96
97       NOTE: if the full path is outside the basepath of the object, it will
98       be unchanged.
99
100           my $path = $Dav->fullpath('/dav/calendars/user/bar/Default');
101           ## /dav/calendars/user/bar/Default
102
103   $Self->Request($method, $path, $content, %headers)
104       The whole point of the module!  Perform a DAV request against the
105       endpoint, returning the response as a parsed hash.
106
107          method: http method, i.e. GET, PROPFIND, MKCOL, DELETE, etc
108
109          path: relative to base url.  With a leading slash, relative to
110                server root, i.e. "Default/", "/dav/calendars/user/foo/Default".
111
112          content: if the method takes a body, raw bytes to send
113
114          headers: additional headers to add to request, i.e (Depth => 1)
115
116   $Self->GetProps($Path, @Props)
117       perform a propfind on a particular path and get the properties back
118
119   $Self->GetPropsArray($Path, @Props)
120       perform a propfind on a particular path and get the properties back as
121       an array of one or more items
122
123   $Self->GetCurrentUserPrincipal() =head2
124       $class->GetCurrentUserPrincipal(%Args)
125       Can be called with the same args as new() as a class method, or on an
126       existing object.  Either way it will use the .well-known URI to find
127       the path to the current-user-principal.
128
129       Returns a string with the path.
130
131   $Self->GetHomeSet =head2 $class->GetHomeSet(%Args)
132       Can be called with the same args as new() as a class method, or on an
133       existing object.  Either way it assumes that the created object has a
134       'url' parameter pointing at the current user principal URL (see
135       GetCurrentUserPrincipal above)
136
137       Returns a string with the path to the home set.
138
139   $Self->genuuid()
140       Helper to generate a uuid string.  Returns a UUID, e.g.
141
142           my $uuid = $DAVTalk->genuuid(); # 9b9d68af-ad13-46b8-b7ab-30ab70da14ac
143
144   $Self->auth_header()
145       Generate the authentication header to use on requests:
146
147       e.g:
148
149           $Headers{'Authorization'} = $Self->auth_header();
150
151   $Self->request_url()
152       Generate the authentication header to use on requests:
153
154       e.g:
155
156           $Headers{'Authorization'} = $Self->auth_header();
157
158   $Self->NS()
159       Returns a hashref of the 'xmlns:shortname' => 'full namespace' items
160       for use in XML::Spice body generation, e.g.
161
162           $DAVTalk->Request(
163               'MKCALENDAR',
164               "$calendarId/",
165               x('C:mkcalendar', $Self->NS(),
166                   x('D:set',
167                        x('D:prop', @Properties),
168                   ),
169               ),
170           );
171
172           # { 'xmlns:C' => 'urn:ietf:params:xml:ns:caldav', 'xmlns:D' => 'DAV:' }
173
174   $Self->ns($key, $value)
175       Get or set namespace aliases, e.g
176
177         $Self->ns(C => 'urn:ietf:params:xml:ns:caldav');
178         my $NS_C = $Self->ns('C'); # urn:ietf:params:xml:ns:caldav
179
180   function2

AUTHOR

182       Bron Gondwana, "<brong at cpan.org>"
183

BUGS

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

SUPPORT

192       You can find documentation for this module with the perldoc command.
193
194           perldoc Net::DAVTalk
195
196       You can also look for information at:
197
198       ·   RT: CPAN's request tracker (report bugs here)
199
200           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-DAVTalk>
201
202       ·   AnnoCPAN: Annotated CPAN documentation
203
204           <http://annocpan.org/dist/Net-DAVTalk>
205
206       ·   CPAN Ratings
207
208           <http://cpanratings.perl.org/d/Net-DAVTalk>
209
210       ·   Search CPAN
211
212           <http://search.cpan.org/dist/Net-DAVTalk/>
213

ACKNOWLEDGEMENTS

216       Copyright 2015 FastMail Pty. Ltd.
217
218       This program is free software; you can redistribute it and/or modify it
219       under the terms of the the Artistic License (2.0). You may obtain a
220       copy of the full license at:
221
222       <http://www.perlfoundation.org/artistic_license_2_0>
223
224       Any use, modification, and distribution of the Standard or Modified
225       Versions is governed by this Artistic License. By using, modifying or
226       distributing the Package, you accept this license. Do not use, modify,
227       or distribute the Package, if you do not accept this license.
228
229       If your Modified Version has been derived from a Modified Version made
230       by someone other than you, you are nevertheless required to ensure that
231       your Modified Version complies with the requirements of this license.
232
233       This license does not grant you the right to use any trademark, service
234       mark, tradename, or logo of the Copyright Holder.
235
236       This license includes the non-exclusive, worldwide, free-of-charge
237       patent license to make, have made, use, offer to sell, sell, import and
238       otherwise transfer the Package with respect to any patent claims
239       licensable by the Copyright Holder that are necessarily infringed by
240       the Package. If you institute patent litigation (including a cross-
241       claim or counterclaim) against any party alleging that the Package
242       constitutes direct or contributory patent infringement, then this
243       Artistic License to you shall terminate on the date that such
244       litigation is filed.
245
246       Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER
247       AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
248       THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
249       PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY
250       YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR
251       CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR
252       CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE,
253       EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
254
255
256
257perl v5.30.2                      2020-04-07                   Net::DAVTalk(3)
Impressum