TDcal::CalDAV(3) FreeBSD Library Functions Manual TDcal::CalDAV(3)

TDcal Perl programming library

use TDcal::CalDAV;

($bool, $cals) =

($ok, $upcount, $ical, $etags, $hrefmap) =
caldavsync($calref, $calcollref);

$bool =

$bool =

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.

TDcal(3), TDcal::iCalendar(3), td(5), TDcal(7).

See TDcal(7).

See TDcal(7).
August 18, 2013 FreeBSD 13.0-RELEASE