NAME

SYNOPSIS

($ok, $chgs) =
icalparse($ical, $calref, $etags, $hrefmap, $local);

$bool =
icalitemadd($item, $calref, $etags, $hrefmap, $local);

icalitemdelete($id, $calref, $local);

$bool =
icalitemloadmisc($id, $calref);

$tzone =
icalitemtzone($item);

$bool =
icalalldayevent($id, $calref);

$evt_list =
icalitemtimes($id, $calref, $pstart, $pfinish);

$rule =
icalrruleparse($rrule);

$rule =
icalrdateparse($rdate);

DESCRIPTION

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 tdlist() or tdlist_filter().

icalparse() is the top-level calendar parser, accepting a comlpete iCalendar VCALENDAR in $ical. icalparse() separates out individual calendar items and passes them to icalitemadd() for addition to the calendar. See that function, below, for descriptions of the arguments. The return value from icalparse() has two components: $ok is a boolean that indicates whether the parsing of the data in $ical, completed without errors, and $chgs is a boolean that indicates if any changes (additions, deletions, updates) were made to the existing calendar. Note that both changes and errors are possible at the same time: icalparse() will continue processing the whole calendar even if errors are found in individual items. If changes are indicated, most likely a call to cachesave() is warranted. If $ok is $false indicating errors were detected, they should be displayed to the user or logged.

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 accessed using 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: In the event of invalid calendar data in an item to be added from a non-local source, icalitemadd() will adjust the internal values to make sense. This will allow the event to be accepted and displayed. The user will then be able to edit the item to correct the errors. If the item were rejected, it would cause repeated errors each time that calendar was re-synced. 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 item from 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 ‘yyyymnddhhmmss’.

The icalrruleparse() and 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.

DATA TYPES

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 $id.

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 synchronization efforts.

RETURN VALUES

icalparse() and 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 tdcalref() and tdcalevent() functions.

icalitemdelete() does not return a value.

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 stored in TDcal internal format and can be accessed using the tdcalevent() function.

icalitemtimes() returns a hashref keyed by individual event instance start times.

icalrruleparse() and icalrdateparse() return a hashref to repetition rule data. They return ‘undef’ if the repetition rule or dates could not be parsed.

SEE ALSO

STANDARDS

HISTORY