|TDcal::iCalendar(3)||FreeBSD Library Functions Manual||TDcal::iCalendar(3)|
TDcal::iCalendarprovides functions to parse and manipulate iCalendar calendar data into
TDcalcalendars. These functions take RFC5545 standard calendar data, parse it into individual events and parse each event into event data which is stored in
TDcal's internal storage format.
Throughout these functions, argument $id
refers to an event id. This is a locally generated string or one obtained
from a remote server download. id values for events stored in the calendar
can be obtained by parsing $tag values obtained from
icalparse() is the top-level calendar
parser, accepting a comlpete iCalendar VCALENDAR in
out individual calendar items and passes them to
icalitemadd() for addition to the calendar. See that
function, below, for descriptions of the arguments.
icalitemadd() is the calendar item parser,
accepting in $item an individual VEVENT or other
calendar item and parsing it into event data. Events are stored in
TDcal's internal calendar storage where they can be
tdcalevent(). If the event already
exists, its data is overwritten. If the change has originated locally and if
the calendar has a remote server configured, an entry is made in the
synchronization queue so that the updated data will be sent to the server on
the next synchronization run. Note:
TDcal really only supports VEVENTs at the moment.
Other calendar data may be accepted but will be discarded. The
$etags and $hrefmap arguments
contain the entity-tag hash and the
href’ URL hash which are further
described below in DATA TYPES.
$local is a boolean flag to indicate if events are
being created locally. This is used to determine if a change is to be queued
for transmission to the server or if it was just recived from the server. It
is also used to indicate whether the etag and href information should be
generated for new events.
icalitemdelete() deletes a stored calendar
TDcal's internal storage.
$local is a boolean flag to indicate if the deletion
originated locally. If the deletion was originated locally and if the
calendar has a remote server configured, an entry is made in the
synchronization queue so that the deletion will be sent to the server on the
next synchronization run.
icalitemloadmisc() is used to load all
additional RFC5545 data fields for a calendar item.
TDcal uses only a subset of the full RFC5545
calendar data itself, but all data received when an item is downloaded is
stored. When an item is updated and needs to be sent back to the server,
icalitemloadmisc() is used to load the additional
data fields for the event so that the complete event can be uploaded.
icalitemtzone() parses a VTIMEZONE item
and extracts the timezone name. It converts Microsoft timezone names to
standard Olson timezone names.
icalalldayevent() determines whether an
event is an all-day event or not. All-day events are events which have
iCalendar start and end dates which are in 8-character DATE format rather
than 14-character DATE-TIME format and where the start and end dates are one
day or more apart. However, note that some calendar servers emit all-day
events with 14-character DATE-TIME start and finishes on day boundaries, or
with start and finish set to the same date, so
icalalldayevent() attempts to detect those too.
icalitemtimes() is the repetition date
expander. It is used to expand an item's start date and repetition rule to
the set of dates on which the event will occur. The
$pstart and $pfinish arguments
denote the UTC start and finish period of interest as strings in the format
icalrdateparse() functions take an RFC5545 RRULE or
RDATE value and expand it to the internally broken-out repetition
information. These also work with the EXDATE value and the deprecated EXRULE
value. These two functions are used by the
icalitemtimes() repetition date expander but are
also available to applications in order to syntactically validate a
repetition rule or date-set provided by the user.
TDcaluses an event's $id (which is its iCalendar UID value) to refer to the event. Events are stored in files named by the $id and the $id is used when manipulating events using the td(1) command-line interface. UID values are any string chosen by
TDcalor other calendar client software to uniquely identify an event. However, during a CalDAV dialog, events are referred to using their URL ‘
href’ which is a server-generated string which may, or may not, bear any similarity to the event's $id. When receiving new events from the server, these ‘
href’ values are stored in the $hrefmap hash. This is keyed by event $id with values being the corresponding server ‘
icalparse() passes the $hrefmap to
icalitemadd() which stores the learned ‘
href’ values in the calendar events themselves.
The $etags hash stores the server's
entity-tags which are change strings for an event. These are not sequence
numbers, but arbitrary strings which could be sequence numbers, hashes or
any other value the server chooses. When an event is changed on the server,
the entity-tag changes. These entity-tags are stored in
$etags which is keyed by the event's
href’ — not by its
Both the entity-tags and the
href’ values are stored in the
calendar event and are saved to the calendar cache. This makes them
available to other applications which can then avoid duplication of
TDcallog file, see
tdlog(). They do not set $tderr in the event of an error return.
icalitemadd() return a boolean value to indicate
success or failure. The actual parsed calendar data is stored in
TDcal internal format and can be accessed using the
icalitemdelete() does not return a
icalitemtzone returns a timezone name or undef if none found.
icalitemloadmisc() returns a boolean value
to indicate success or failure. The actual loaded miscellaneous data is
TDcal internal format and can be accessed
icalitemtimes() returns a hashref keyed by
individual event instance start times.
icalrdateparse() return a hashref to repetition rule
data. They return ‘
undef’ if the
repetition rule or dates could not be parsed.
|August 18, 2013||FreeBSD 13.0-RELEASE|