1Net::CalDAVTalk(3) User Contributed Perl Documentation Net::CalDAVTalk(3)
2
6 Net::CalDAVTalk - Module to talk CalDAV and give a JSON interface to
7 the data
8
10 Version 0.12
11
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 See Net::DAVTalk for details on how to specify hosts and paths.
19 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 or using DNS:
31 my $domain = $user;
33 $domain =~ s/.*\@//;
34 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 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 my $foo = Net::CalDAVTalk->new(
52 user => $user,
53 password => $password,
54 url => $url,
55 expandurl => 1,
56 );
57
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 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 $self->tz($name)
70 Returns a DateTime::TimeZone object for the given name, but caches the
71 result for speed.
72 $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 e.g.
78 $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 $self->DeleteCalendar($calendarId)
86 Delete the named calendar from the server (shorturl - see Net::DAVTalk)
87 $Cal->DeleteCalendar($calendarId)
89 Delete the calendar with collection name $calendarId (full or relative
90 path)
91 e.g.
93 $Cal->DeleteCalendar('Default');
95 $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 e.g
102 my $Calendar = $CalDAV->GetCalendar('Default');
103 $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 e.g
109 my $Calendars = $CalDAV->GetCalendars();
111 foreach my $Cal (@$Calendars) {
112 # do stuff
113 }
114 $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 e.g.
124 my $Id = $CalDAV->NewCalendar({name => 'My Calendar', color => 'aqua'});
126 (Color names will be translated based on the CSS name list)
128 $self->UpdateCalendar($Args)
130 Like 'NewCalendar', but updates an existing calendar, and 'id' is
131 required. Returns the id, just like NewCalendar.
132 $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 Returns true.
138 $self->GetEvents($calendarId, %Args)
140 Fetches some or all of the events in a calendar.
141 Supported args:
143 href => [] - perform a multi-get on just these fullpath urls.
145 after+before => ISO8601 - date range to query
146 In scalar context returns an arrayref of events. In list context
148 returns both an arrayref of events and an arrayref of errors:
149 e.g.
151 my ($Events, $Errors) = $CalDAV->GetEvents('Default');
153 $self->GetEventsMulti($calendarId, $Urls, %Args)
155 Fetches the events in Urs from the calendar
156 Supported args:
158 * ContentType
160 * Version
161 For the calendar-data response
163 In scalar context returns an arrayref of events. In list context
165 returns an array of:
166 * arrayref of events * arrayref of errors: * hash of href to getetag
168 $self->GetEventLinks($calendarId, %Args)
170 Fetches the URLs of calendar events in a calendar.
171 Supported args:
173 after+before => ISO8601 - date range to query
175 returns a hash of href to etag
177 $self->GetEvent($href)
179 Just get a single event (calls GetEvents with that href)
180 $self->GetFreeBusy($calendarId, %Args)
182 Like 'GetEvents' but uses a free-busy-query and then generates
183 synthetic events out of the result.
184 Doesn't have a 'href' parameter, just the before/after range.
186 $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 In scalar context still just returns new events, in list context
193 returns Events, Removed and Errors.
194 e.g.
196 my ($Events, $Removed, $Errors) = $CalDAV->SyncEvents('Default', syncToken => '...');
198 $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 In scalar context still just returns Added, in list context returns
205 Added, Removed, Errors and new token:
206 * 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 e.g.
212 my ($Added, $Removed, $Errors, $NewToken)
214 = $CalDAV->SyncEventLinks('Default', syncToken => '...');
215 $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 Returns the href, but also updates 'uid' in $Args.
222 Also updates 'sequence'.
224 e.g.
226 my $href = $CalDAV->NewEvent('Default', $Args);
228 my $newuid = $Args->{uid};
229 $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 $self->AnnotateEvent($href, $Args)
236 Instead of actually changing an event itself, use proppatch to add or
237 remove properties on the event.
238 $self->MoveEvent($href, $newCalendarId)
240 Move an event into a new calendar. Returns the new href.
241 $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 Net::CalDAVTalk->CompareEvents($Event1, $Event2);
247 Returns true if the events are identical
248 $self->vcalendarToEvents($Data)
250 Convert a text vcalendar (either a single event or an entire ical file)
251 into an array of events.
252 Returns an array (not arrayref) of Events in UID order.
254 e.g.
256 foreach my $Event ($CalDAV->vcalendarToEvents($Data)) {
258 # ...
259 }
260 $self->UpdateAddressSet($DisplayName, $EmailAddress)
262 Set the address set and display name for the calendar user (if
263 supported)
264 $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
270 Bron Gondwana, "<brong at cpan.org>"
271
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
280 You can find documentation for this module with the perldoc command.
281 perldoc Net::CalDAVTalk
283 You can also look for information at:
285 • RT: CPAN's request tracker (report bugs here)
287 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-CalDAVTalk>
289 • AnnoCPAN: Annotated CPAN documentation
291 <http://annocpan.org/dist/Net-CalDAVTalk>
293 • CPAN Ratings
295 <http://cpanratings.perl.org/d/Net-CalDAVTalk>
297 • Search CPAN
299 <http://search.cpan.org/dist/Net-CalDAVTalk/>
301
304 Copyright 2015 FastMail Pty Ltd.
305 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 <http://www.perlfoundation.org/artistic_license_2_0>
311 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 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 This license does not grant you the right to use any trademark, service
322 mark, tradename, or logo of the Copyright Holder.
323 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 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.
342perl v5.36.0 2023-01-20 Net::CalDAVTalk(3)