ICAL_PARSE(3)

NAME
ical_parse - parse an iCalendar file

LIBRARY
libkcaldav

SYNOPSIS
#include <libkcaldav.h>
struct ical *
ical_parse(const, char, *file, const, char, *cp, size_t, len, size_t, *pos, char, **er);

DESCRIPTION
Parse an iCalendar file given in cp, which may not be NULL, of length sz, and optionally starting at pos or zero if pos is NULL. If file is not NULL, it is used for reporting errors only. The er, if not NULL, is filled in with an error message on parse failure.

The parsed iCalendar file must be freed with ical_free(3). If errors occur and er is set, the error string must be freed with free(3).

The returned struct ical structure has the following members:

unsigned int bits
    Bit-mask of components covered by the object. May be one or more of ICAL_VCALENDAR, ICAL_VEVENT, ICAL_VTODO, ICAL_VJOURNAL, ICAL_VFREEBUSY, ICAL_VTIMEZONE, or ICAL_VALARM. The ICAL_VCALENDAR is always set. There may be more than one of each of of these components.

struct icalnode *first
    A pointer to the first raw parsed properties.

struct icalcomp *comps[]
    All components, grouped by type. There may be more than one component per bucket in a linked list format. If the component is unspecified, it's NULL.

Each calendar component is represented by struct icalcomp as follows.

struct icalcomp *next
    The next component of the same type or NULL if this is the last.

enum icaltype type
    The type of the component.

struct icaltm created
    The parsed CREATED value.

struct icaltm lastmod
    The parsed LASTMODIFIED value.

struct icaltm dtstamp
    The parsed DTSTAMP component.

struct icalrrule rrule
    The RRULE or all zeroes, if not specified.

struct icaltime dtstart
    The DTSTART or all zeroes, if not specified.

struct icaltime dtend
    The DTEND or all zeroes, if not specified.

struct icaldur duration
    The DURATION or all zeroes, if not specified.

struct icaltz *tzs
    The timezone rules or NULL if not specified.

size_t tzsz
    The number of elements in tzs.

const char *uid
    The UID of the component of NULL if not specified.

const char *tzid
    The TZID of the component.

Date-time pairs in iCalendar are represented with struct icaltime:

const struct icalcomp *tz
    The parsed time-zone component. This is NULL if the date is in UTC format.

struct icaltm time
    The time component.

char *tzstr
    String equivalent of tz or NULL if not associated with a time-zone.

Time-zone components in struct icalcomp have either or both daylight and standard struct icaltz:

enum icaltztype type
    Type of time-zone definition.

int tzfrom
    Seconds from.

int tzto
    Seconds to.

struct icaltm dtstart
    When the definition is in effect.

struct icalrrule rrule
    Either the recursive definition or all zeroes if not set.

Recursive rules are parsed into struct icalrrule:

int set
    Non-zero if the structure has been set, zero otherwise.

enum icalfreq freq
    The FREQ value.

struct icaltm until
    The UNTIL value or zeroes if unset.

unsigned long count
    The COUNT value or zero if unset.

unsigned long interval
    The INTERVAL value or zero if unset.

unsigned long *bhr
    The BYHOUR values or NULL if not set.

size_t bhrsz
    The number of elements in bhr.

unsigned long *bmin
    The BYMINUTE values or NULL if not set.

size_t bminsz
    The number of elements in bmin.

long *bmnd
    The BYMONTHDAY values or NULL if not set.

size_t bmndsz
    The number of elements in bmnd.

unsigned long *bmon
    The BYMONTH values or NULL if not set.

size_t bmonsz
    The number of elements in bmon.

unsigned long *bsec
    The BYSECOND values or NULL if not set.

size_t bsecsz
    The number of elements in bsec.

long *bsp
    The BYSETPOS values or NULL if not set.

size_t bspsz
    The number of elements in bsp.

struct icalwk *bwkd
    The BYDAY values or NULL if not set.

size_t bwkdsz
    The number of elements in bwkd.

long *bwkn
    The BYWEEKNO values or NULL if not set.

size_t bwknsz
    The number of elements in bwkn.

long *byrd
    The BYYEARDAY values or NULL if not set.

size_t byrdsz
    The number of elements in byrd.

enum icalwkday wkst
    The weekday value.

Durations are encoded as struct icaldur:

int sign
    If greater than zero, a positive duration; ir less than zero, negative. This is zero if the duration has not been set.

unsigned long day
    The number of days starting at zero.

unsigned long week
    The number of weeks starting at zero.

unsigned long hour
    The number of hours starting at zero.

unsigned long min
    The number of minutes starting at zero.

unsigned long sec
    The number of seconds starting at zero.

Various components depend upon a simple time value in struct icaltm:

time_t tm
    The UNIX epoch value. Note: this may be replaced by a native 64-bit value so that 32-bit time systems aren't affected.

enum icaldatet type
    If ICAL_DT_UNSET, the date-time has no been set. Otherwise, the format of the date-time: a date (ICAL_T_DATE), date and time (ICAL_T_DATETIME), or UTC date and time (ICAL_T_DATETIMEUTC).

Weekday values are set in struct icalwk:

long wk
    The week number or zero if not set.

enum icalwkday wkday
    Zero if not set or the day of week.

The raw parsed but unprocessed properties are held in a linked list of struct icalnode:

char *name
    The name of the property.

char *param
    Additional parameters of the property. This may be NULL.

char *val
    The value of the property.

struct icalnode *next
    The next property in the sequence or NULL if there are no more.

RETURN VALUES
Returns the parse object on success. It must be freed with ical_free(3). If pos is not NULL, it is updated to the current position in the buffer.

On failure, returns NULL.

The er pointer, if not NULL, is provided an error message. If the error message is NULL, memory allocation has failed. The error string pointer must be freed by the caller.

SEE ALSO
ical_free(3)

STANDARDS
The iCalendar format is specified in RFC 5545, (Internet Calendaring and Scheduling Core Object).