|TDcal(3)||FreeBSD Library Functions Manual||TDcal(3)|
use TDcal qw($tdprog
($cals_read, $cals_deleted, $eventcount) =
($start, $cal, $id) =
TDcalis the Perl programming API for the TDcal(7) calendar system.
TDcal API allows calendar applications
to be developed. Programs can interface with the
TDcal calendars and can discover and load calendars,
add and delete events, list events occuring within date ranges, synchronize
calendars with remote servers and manage new calendars discovered from
TDcalAPI functions use or return the following varibales:
TDcal library makes the following
variables available for export:
$tderr is used to return error condition
information. If any
TDcal function returns an error
indication, $tderr will contain one or multiple lines
of error messages. These can be given to
store in the log file or to
prepends the program name suitable for display to the user as standard error
$tdprog contains the current program name
and $tdvflag contains the verbose flag. These are both
tdsetvflag() which is usually invoked
early in an application. The program name is used in log and error messages
and the verbose flag controls whether the library functions emit additional
verbose messages on standard error.
$tdtzone is the local calendar timezone. It
affects the times in which events are displayed to the user. Internally,
TDcal stores all event times in
The following variables reflect the user's global configuration settings:
The following variables say a bit about the author and are used in help and about messages:
$tdprodid is the RFC5545 iCalendar PRODID
string that is included in all calendars exported by
$tdicondir are the paths of the directories containing
TDcal TDcal help files and icons,
These are the
TDcal library functions:
tdrcload() initializes the calendar
structures from the
TDcal configuraton file named by
$rcfile. With no argument,
tdrcload() reads the main configuration file; with
an argument, it reads the configuration file specified. Modification times
of the config files are recorded and
returns without doing anything if a config file is unchanged since it was
last read - this allows it to be invoked from a repeating idle loop to
reload the config files if they changed. The $encoding
argument specifies the character set of the configuration file with
utf-8’ used if unset.
tdrcload() returns a tri-value set to
$error in the event that an error occurred, e.g., the
configuration file does not exist or cannot be read,
$false if all is OK but no configuration was read
because nothing changed since last time, and $true if
one or more configuration files were (re)read.
tdrcsave() saves a calendar's individual
configuration file. There is no mechanism at the moment to save the main
configuration file - this must be edited and updated using a text
tdread() reads calendar cache files for
the calendars learned from an earlier call to
tdrcload() and initializes the event structures. It
returns counts of the number of calendars successfully read, the number of
calendars that were deleted and the total number events actually read. Note,
however, that if
tdrcload() is also invoked prior to
remove any calendars that have been deleted so
tdread() will no longer see them and will report 0
tdcals() returns a list of calendars. Each
list value can be used as a $cal argument in the other functions.
tdcalref() returns a hashref to a
calendar. This can be used as a $calref argument in the other functions.
tdcalevent() returns a hashref to an
event. This can be used as a $event argument in the other functions.
tdcalsetattrib() are used to get and set calendar
attributes. Values for the $attrib argument correspond
to calendar attributes specified in the configuration file read in using
tdrcload() and also learned when synchronizing with
a CalDAV server using
tdsync(). Attributes are
things like a calendar's color or tzone
tdeventadd() adds a new event to a
calendar or updates an existing event.
tdeventdelete() deletes an event from a
tdeventcopy() copies the details of an
event out of a calendar and returns a hashref to the copy. Any changes made
to an event copy must be re-added to a calendar using
tdeventmove() changes the start and finish
times of an individual event such as returned by
tdeventcopy(). If the event has repetition dates or
exclusion dates, those are adjusted too. After calling
tdeventmove(), the changed event must be re-added to
a calendar using
tdeventtimes() expands a single event and
returns a hashref of event instances keyed by
tag’. That is, it expands an event to
all its repetition instances within the period indicated by
$pstart to $pfinish.
tdxtag() make and extract $tag
values. Tags are strings containing an event instance's start time, its
calendar name and its id and these tag strings are widely used as hash keys
in to store event details.
tdlist() searches calendars and returns a
hashref of events keyed by ‘
Repeating events are evaluated to find all instances of the event within the
desired search period; there may be multiple instances of an event present
in the return value for repeating events. All of the arguments may have the
undef value; if all four are undefined,
tdlist() returns all events in all calendars.
Providing a $cals argument limits the search to just
those calendars. Providing a $patt argument limits the
search to events whose summary or description matches the pattern (matched
case-independently). Providing $pstart and
$pfinish arguments restricts the result to events
within the specified period. Note that because repeating events without end
COUNT or UNTIL specifiers continue infinitely into the future,
tdlist() limits searches with an undefined
$pfinish to 100 years in the future. To search beyond
then, an explicit $pfinish value must be provided.
tdlist() returns a hashref of events.
tdlist_filter() further filters an
existing list returned by a prior call to
tdlist_filter() on an existing list is faster
than re-evaluating all events in a new search. For example, use
tdlist() to get all events in a specific month, then
tdlist_filter() to get events for a specific day
from the month list.
tdlist_filter() also returns a
hashref of events.
tdalldayevent() checks if an event is an
trepeatingevent() checks if an event is a
tdicalimport() parses an iCalendar file
and imports all events found into the calendar. $cal
must be a reference to a single calendar, $file names
the file to be imported and $encoding names the
character set of the input file with
utf-8’ used if unset.
tdicalexport() takes a list of event ids
and produces an iCalendar file contining all the events.
$cals must be a reference to one or more calendars
which will be searched for the events. $idlist is an
arrayref to a list of event ids to be included in the generated calendar.
tdicalexport(), events can be exported from
multiple calendars into a single new calendar.
tdicalexport() returns the generated calendar in
$ical which will be undef if errors were
tdeventloadmisc() reads an event's
iCalendar file and loads additional details that are not also stored in the
calendar's cache file. See the description of the
$event hash, below, for what is currently loaded by
this function. $cal must be a reference to a single
calendar and $id is the id of the event to be
tdsync() synchronizes the referenced
calendars with their remote servers. Events and storage directories
calendars no longer present on their remote servers are removed locally.
$cals is a reference to one or more calendars to be
synchronized. Note that if a CalDAV collection is given, all calendars under
that collection on the server will be synchronized.
tdgetactivecal() reutrns the calendar
which has the ‘
active’ attribute set.
active’ is an attribute flag that can
be set on a calendar using
indicate the user's choice of active calendar, i.e., the calendar which new
events should be created in.
tdsetvflag() sets the program name and the
logging verbosity for
TDcal library functions.
$prog sets the program name which is used in error
messages and in verbose logging messages. $vflag sets
or clears verbose logging flag - typically this is used when the user
-v flag or other similar request for
tdlog() writes messages to the
TDcal log file. $prog and
$module indicate the source of the message and
$msgs is a string containing one or more lines of
messages to be logged. $msgs is split into lines of
individual $msg messages and each message logged will
be of the form:
yyyy/mn/dd hh:mm:ss $prog: $module $msg
If verbose mode is enabled,
writes the same $msg messages to standard error but
without the date and time.
tderrstr() takes a
$msgs error string which may contain one or multiple
lines of error messages and formats it by prepending the program name to
each line. The program name is set using an earlier call to
tdsetvflag(). Double newlines and also trailing
newlines are removed from the formatted result. The formatted result is
suitable for display to the user.
TDcalconfiguration file or as learned from a CalDAV server.
To access calendar data, a reference to the calendar's individual
hash is first obtained using: $calref =
tdcalref($cal);. The calendar
data can then be accessed using the following fields or using
$id is an event's id string. It can take any
form, as determined by whatever software created the event in the first
place. When generating new id strings, care must be taken to ensure that
they are unique in the calendar across all hosts and clients.
TDcal events' iCalendar data is stored in the
calendar storage directory in spearate files named by the id. Filesystem
characters in id names (e.g., ‘
hex encoded before use.
$idlist is an arrayref of $id calendar ids:
$event is a hashref with the details of one
event. An event reference is obtained using: $event =
$id);. Event hashes have the following contents. These
correspond to the event's iCalendar data records of the same (or similar)
Client-specific data can also stored. Clients typically use this field as a hashref with their own additional data items:
And some data obtained from the server:
As well as iCalendar data that is not used by
TDcal itself but which is saved and can be loaded by
tdeventloadmisc() typically before an event is
updated or exported:
$evt_list is a hashref of $event events referenced by their $tag values:
$tag values are strings containing an event
instance's start time, its calendar name and its ID. They are created using
tdmktag() and extracted using
$pstart and $pfinish
are date strings in the format
Functions returning $bool return a boolean $true or $false value.
Functions returning $err return $true on success, undef on error.
Functions returning $cals return a hashref of calendars.
Functions returning @cals return a list of calendars.
Functions returning $evt_list return a
hashref of events indexed by
The functions use an error return variable,
$tderr to store one or multiple lines of error
messages. It is intended that $tderr is either logged
tdlog() or formatted using
tderrstr() and displayed to the user in the event of
an error. It should be noted that several functions loop through calendars
or through events and may return many lines of error messages in
$tderr, possibly hundreds or even thousands for large
calendars, so care should be taken when displaying any errors in a GUI to
use a scrolling window.
TDcalerror handling, logging and verbose mode.
While many functions do set the $tderr error string variable, some do not.
The functions that make permanent changes to the calendar store, such as creating and removing calendar directories as well as creating, updating and removing events, and also the functions that perform network operations, all log what they are doing directly in the log file. These are status messages, not error messages. Of course, such operations can fail and error messages are then generated too. Errors from these functions are typically also logged directly to the log file rather than being returned to the caller in $tderr. In such cases, only an error return is given to the caller.
This proved necessary in order to be able to watch the log file and see the status messages and errors happening in real time. Returning errors to the caller meant long delays before errors are displayed (due to some functions looping to process multiple events or multiple calendars each with multiple events and also due to network timeouts sometimes taking a long time) and it meant that status messages and associated error messages ended up being displayed out of order. Having these functions enter their errors directly in the log was much more useful (and much simpler) than returning lists of status messages and errors.
It should also be noted that these functions are typically called by daemons that do not have a means of displaying errors to users and which would just log the error anyway.
|July 22, 2013||FreeBSD 13.0-RELEASE|