| TDcal::CalDAV(3) | FreeBSD Library Functions Manual | TDcal::CalDAV(3) |
TDcal::CalDAV —
use TDcal::CalDAV;
($bool, $cals) =
caldavgetcals($calref);
($ok, $upcount, $ical, $etags, $hrefmap) =
caldavsync($calref,
$calcollref);
$bool =
caldavlock($calref);
$bool =
caldavunlock($calref);
TDcal::CalDAV provides functions that perform querying
and synchronization with remote CalDAV calendar servers.
In these functions, the agruments $calref
and $calcollref are calendar references as returned by
tdcalref().
caldavgetcals() queries a remote calendar
server to obtain the list of calendars available on that server, together
with details such as their access mode, color, timezone, etc. A series of
queries are made, starting from the calendar URL configured in the
td(5) configuration file. These queries obtain the
principal URL, the calendar home set and the list of calendars available. In
the event of errors, caldavgetcals() logs error
messages directly to the TDcal log file, see
tdlog(). It does not set
$tderr in the event of an error return.
caldavsync() performs synchronization of
an individual CalDAV calendar with its remote server. The areguments are
references to the individual calendar and to its collection.
caldavsync() processes a calendar's
TDcal synchronization queue and sends events that
have been added, changed or deleted to the remote server. It then asks the
server for a list of all events on the server, compares that list with what
is stored locally and requests any updated events from the server and
deletes any local events that were deleted from the server. Extensive use is
made of the server's entity-tags and change-tags in order to avoid
unnecessarily downloading anything that hasn't changed. The synchonization
lock should be held while performing such a synchronization operation. In
the event of errors, caldavsync() logs error
messages directly to the TDcal log file, see
tdlog(). It does not set
$tderr in the event of an error return.
caldavlock() acquires the synchronization
lock for the calendar. If the lock is already held by another process,
caldavlock() will fail.
caldavunlock() releases the
synchronization lock for the calendar.
caldavgetcal() returns a boolean value to indicate
success and $cals, which is a reference to a hash of
calendars if calendar data was obtained or
‘undef’ if no data was obtained.
caldavsync() returns boolean value
$ok indicating the status of the entire
upload/download conversation. Any error causes it to be set to
$false. $upcount contains a
count of the number of items sucessfully sent to the server, i.e., new items
or changed items but not deletions. A count here indicates that new server
etags might be available, so a cachesave() should be
done. $ical contains an iCalendar VCALENDAR if any
changes were received from the server or
‘undef’ if none were received. Note
that $ok shows the overall conversation status; it can
be $false due to an upload failure yet the download
phase may still have worked and have valid new data, so it is important to
check both $ok to to see if there are error messages,
then also check $upcount and
$ical to know if events were uploaded and downloaded
from the server even despite a possible error condition.
caldavsync() also returns the
$etags and $hrefmap data
compiled during the server dialog. $etags is a hashref
used to map event ‘href’ URLs to their
entity-tags which are server change indicators.
$hrefmap is a hashref used to map event
‘href’ URLs to event UIDs. It is
intended that $ical, $etags and
$hrefmap are passed to
icalparse() to incorporate the received changes into
TDcal's current calendar data.
caldavlock() and
caldavunlock() return a boolean value to indicate
success or failure.
| August 18, 2013 | FreeBSD 13.0-RELEASE |