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

NAME

6       Net::CalDAVTalk - Module to talk CalDAV and give a JSON interface to
7       the data
8

VERSION

10       Version 0.12
11

SYNOPSIS

13       This module is the initial release of the code used at FastMail for
14       talking to CalDAV servers.  It's quite specific to an early version of
15       our API, so while it might be useful to others, it's being pushed to
16       CPAN more because the Cassandane test suite needs it.
17
18       See Net::DAVTalk for details on how to specify hosts and paths.
19
20           my $CalDAV = Net::CalDAVTalk->new(
21               user => $service->user(),
22               password => $service->pass(),
23               host => $service->host(),
24               port => $service->port(),
25               scheme => 'http',
26               url => '/',
27               expandurl => 1,
28           );
29
30       or using DNS:
31
32           my $domain = $user;
33           $domain =~ s/.*\@//;
34
35           my $url;
36           my ($reply) = $Resolver->search("_caldavs._tcp.$domain", "srv");
37           if ($reply) {
38             my @d = $reply->answer;
39             if (@d) {
40               my $host = $d[0]->target();
41               my $port = $d[0]->port();
42               $url = "https://$host";
43               $url .= ":$port" unless $port eq 443;
44             }
45           }
46
47       This will use the '/.well-known/caldav' address to find the actual
48       current user principal, and from there the calendar-home-set for
49       further operations.
50
51           my $foo = Net::CalDAVTalk->new(
52              user => $user,
53              password => $password,
54              url => $url,
55              expandurl => 1,
56           );
57

SUBROUTINES/METHODS

59   new(%args)
60       Takes the same arguments as Net::DAVTalk and adds the caldav namespaces
61       and some Cyrus specific namespaces for all XML requests.
62
63         A => 'http://apple.com/ns/ical/'
64         C => 'urn:ietf:params:xml:ns:caldav'
65         CY => 'http://cyrusimap.org/ns/'
66         UF => 'http://cyrusimap.org/ns/userflag/'
67         SF => 'http://cyrusimap.org/ns/sysflag/'
68
69   $self->tz($name)
70       Returns a DateTime::TimeZone object for the given name, but caches the
71       result for speed.
72
73   $self->logger(sub { })
74       Sets a function to receive all log messages.  Gets called with the
75       first argument being a level name, and then a list of items to log:
76
77       e.g.
78
79          $CalDAV->logger(sub {
80             my $level = shift;
81             return if ($level eq 'debug' and not $ENV{DEBUG_CALDAV});
82             warn "LOG $level: $_\n" for @_;
83          });
84
85   $self->DeleteCalendar($calendarId)
86       Delete the named calendar from the server (shorturl - see Net::DAVTalk)
87
88   $Cal->DeleteCalendar($calendarId)
89       Delete the calendar with collection name $calendarId (full or relative
90       path)
91
92       e.g.
93
94           $Cal->DeleteCalendar('Default');
95
96   $self->GetCalendar($calendarId)
97       Get a single calendar from the server by calendarId (currently
98       implemented very inefficiently as a get of all calendars.  Returns
99       undef if the calendar doesn't exist.
100
101       e.g
102          my $Calendar = $CalDAV->GetCalendar('Default');
103
104   $self->GetCalendars(Properties => [])
105       Fetch all the calendars on the server.  You can request additional
106       properties, but they aren't parsed well yet.
107
108       e.g
109
110          my $Calendars = $CalDAV->GetCalendars();
111          foreach my $Cal (@$Calendars) {
112             # do stuff
113          }
114
115   $self->NewCalendar($Args)
116       Create a new calendar.  The Args are the as the things returned by
117       GetCalendars, except that if you don't provide 'id' (same as shorturl),
118       then a UUID will be generated for you.  It's recommended to not provide
119       'id' unless you need to create a specific path for compatibility with
120       other things, and to use 'name' to identify the calendar for users.
121       'name' is stored as DAV:displayname.
122
123       e.g.
124
125          my $Id = $CalDAV->NewCalendar({name => 'My Calendar', color => 'aqua'});
126
127       (Color names will be translated based on the CSS name list)
128
129   $self->UpdateCalendar($Args)
130       Like 'NewCalendar', but updates an existing calendar, and 'id' is
131       required.  Returns the id, just like NewCalendar.
132
133   $self->DeleteEvent($Event|$href)
134       Given a single event or the href to the event, delete that event,
135       delete it from the server.
136
137       Returns true.
138
139   $self->GetEvents($calendarId, %Args)
140       Fetches some or all of the events in a calendar.
141
142       Supported args:
143
144         href => [] - perform a multi-get on just these fullpath urls.
145         after+before => ISO8601 - date range to query
146
147       In scalar context returns an arrayref of events.  In list context
148       returns both an arrayref of events and an arrayref of errors:
149
150       e.g.
151
152           my ($Events, $Errors) = $CalDAV->GetEvents('Default');
153
154   $self->GetEventsMulti($calendarId, $Urls, %Args)
155       Fetches the events in Urs from the calendar
156
157       Supported args:
158
159         * ContentType
160         * Version
161
162       For the calendar-data response
163
164       In scalar context returns an arrayref of events.  In list context
165       returns an array of:
166
167       * arrayref of events * arrayref of errors: * hash of href to getetag
168
169   $self->GetEventLinks($calendarId, %Args)
170       Fetches the URLs of calendar events in a calendar.
171
172       Supported args:
173
174         after+before => ISO8601 - date range to query
175
176       returns a hash of href to etag
177
178   $self->GetEvent($href)
179       Just get a single event (calls GetEvents with that href)
180
181   $self->GetFreeBusy($calendarId, %Args)
182       Like 'GetEvents' but uses a free-busy-query and then generates
183       synthetic events out of the result.
184
185       Doesn't have a 'href' parameter, just the before/after range.
186
187   $self->SyncEvents($calendarId, %Args)
188       Like GetEvents, but if you pass a syncToken argument, then it will
189       fetch changes since that token (obtained from an earlier GetCalendars
190       call).
191
192       In scalar context still just returns new events, in list context
193       returns Events, Removed and Errors.
194
195       e.g.
196
197          my ($Events, $Removed, $Errors) = $CalDAV->SyncEvents('Default', syncToken => '...');
198
199   $self->SyncEventLinks($calendarId, %Args)
200       Like GetEventLinks, but if you pass a syncToken argument, then it will
201       fetch changes since that token (obtained from an earlier GetCalendars
202       or SyncEvent* call).
203
204       In scalar context still just returns Added, in list context returns
205       Added, Removed, Errors and new token:
206
207       * Added: hash of href to etag - added or changed * Removed: array of
208       href * Errors: array of descritive string * NewToken: scalar opaque
209       DAV:sync-token
210
211       e.g.
212
213          my ($Added, $Removed, $Errors, $NewToken)
214             = $CalDAV->SyncEventLinks('Default', syncToken => '...');
215
216   $self->NewEvent($calendarId, $Args)
217       Create a new event in the named calendar.  If you don't specify 'uid'
218       then a UUID will be created.  You should only specify the UID if you
219       need to for syncing purposes - it's better to auto-generate otherwise.
220
221       Returns the href, but also updates 'uid' in $Args.
222
223       Also updates 'sequence'.
224
225       e.g.
226
227           my $href = $CalDAV->NewEvent('Default', $Args);
228           my $newuid = $Args->{uid};
229
230   $self->UpdateEvent($href, $Args)
231       Like NewEvent, but you only need to specify keys that you want to
232       change, and it takes the full href to the card instead of the
233       containing calendar.
234
235   $self->AnnotateEvent($href, $Args)
236       Instead of actually changing an event itself, use proppatch to add or
237       remove properties on the event.
238
239   $self->MoveEvent($href, $newCalendarId)
240       Move an event into a new calendar.  Returns the new href.
241
242   $NewEvent = Net::CalDAVTalk->NormaliseEvent($Event);
243       Doesn't change the original event, but removes any keys which are the
244       same as their default value
245
246   Net::CalDAVTalk->CompareEvents($Event1, $Event2);
247       Returns true if the events are identical
248
249   $self->vcalendarToEvents($Data)
250       Convert a text vcalendar (either a single event or an entire ical file)
251       into an array of events.
252
253       Returns an array (not arrayref) of Events in UID order.
254
255       e.g.
256
257           foreach my $Event ($CalDAV->vcalendarToEvents($Data)) {
258               # ...
259           }
260
261   $self->UpdateAddressSet($DisplayName, $EmailAddress)
262       Set the address set and display name for the calendar user (if
263       supported)
264
265   $self->GetICal($calendarId, $isFreeBusy)
266       Given a calender, fetch all the events and generate an ical format file
267       suitable for import into a client.
268

AUTHOR

270       Bron Gondwana, "<brong at cpan.org>"
271

BUGS

273       Please report any bugs or feature requests to "bug-net-caldavtalk at
274       rt.cpan.org", or through the web interface at
275       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-CalDAVTalk>.  I
276       will be notified, and then you'll automatically be notified of progress
277       on your bug as I make changes.
278

SUPPORT

280       You can find documentation for this module with the perldoc command.
281
282           perldoc Net::CalDAVTalk
283
284       You can also look for information at:
285
286       ·   RT: CPAN's request tracker (report bugs here)
287
288           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-CalDAVTalk>
289
290       ·   AnnoCPAN: Annotated CPAN documentation
291
292           <http://annocpan.org/dist/Net-CalDAVTalk>
293
294       ·   CPAN Ratings
295
296           <http://cpanratings.perl.org/d/Net-CalDAVTalk>
297
298       ·   Search CPAN
299
300           <http://search.cpan.org/dist/Net-CalDAVTalk/>
301

ACKNOWLEDGEMENTS

304       Copyright 2015 FastMail Pty Ltd.
305
306       This program is free software; you can redistribute it and/or modify it
307       under the terms of the the Artistic License (2.0). You may obtain a
308       copy of the full license at:
309
310       <http://www.perlfoundation.org/artistic_license_2_0>
311
312       Any use, modification, and distribution of the Standard or Modified
313       Versions is governed by this Artistic License. By using, modifying or
314       distributing the Package, you accept this license. Do not use, modify,
315       or distribute the Package, if you do not accept this license.
316
317       If your Modified Version has been derived from a Modified Version made
318       by someone other than you, you are nevertheless required to ensure that
319       your Modified Version complies with the requirements of this license.
320
321       This license does not grant you the right to use any trademark, service
322       mark, tradename, or logo of the Copyright Holder.
323
324       This license includes the non-exclusive, worldwide, free-of-charge
325       patent license to make, have made, use, offer to sell, sell, import and
326       otherwise transfer the Package with respect to any patent claims
327       licensable by the Copyright Holder that are necessarily infringed by
328       the Package. If you institute patent litigation (including a cross-
329       claim or counterclaim) against any party alleging that the Package
330       constitutes direct or contributory patent infringement, then this
331       Artistic License to you shall terminate on the date that such
332       litigation is filed.
333
334       Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER
335       AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
336       THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
337       PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY
338       YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR
339       CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR
340       CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE,
341       EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
342
343
344
345perl v5.28.0                      2017-11-15                Net::CalDAVTalk(3)
Impressum