Using Libical

Using Libical Eric Busboom (eric@softwarestudio.org) January 2000 Introduction

Libical is an Open Source implementation of the iCalendar protocols and protocol data units. The iCalendar specification describes how calendar clients can communicate with calendar servers for users can store their calendar data and arrange meetings with other users.

Libical implements the following specifications and protocols

iCal Core 2445 iTIP 2446 iMIP 2447 iRIP draft CAP draft

(The current version, 0.14, does not implement iRip or CAP. )

This code is under active development. If you would like to contribute to the project, you can contact me, Eric Busboom, at eric@softwarestudio.org. The project has a webpage at

http://softwarestudio.org/libical/index.html

and a mailing list that you can join by sending the following mail:

------------ To: minimalist@softwarestudio.org Subject: subscribe libical ------------

$Id: UsingLibical.lyx,v 1.3 2000/01/06 06:20:06 eric Exp eric $

License

The code and datafiles in this distribution are licensed under the Mozilla Public License. See http://www.mozilla.org/NPL/MPL-1.0.html for a copy of the license. Alternately, you may use libical under the terms of the GNU Library General Public License. See http://www.fsf.org/copyleft/lesser.html for a copy of the LGPL.

This dual license ensures that the library can be incorporated into both proprietary code and GPL'd programs, and will benefit from improvements made by programmers in both realms. I will only accept changes into my version of the library if they are similarly dual-licensed.

Purpose & Goals Building the Library Structure

The iCal calendar model is based on four types of objects: components, properties, values and parameters.

Components are the fundamental grouping of calendar information

Properties are the fundamental unit of information. Each property is composed of a type, a value and collection of parameters.

Components

Components are named clusters of properties

Properties Values Parameters Storage Cluster Store Calendar Other bits

Restrictions

Types

Differences From RFCs

Although libical has been design to follow the standards as closely as possible, there are a few areas where the specifications are irregular, and following them exactly would result in an unfriendly interface.

Pseudo Components

Libical defines pseudo components for groups of properties that look and act like components, but are not defined as components in the specification. XDAYLIGHT and XSTANDARD are notable examples. These pseudo components group properties within the VTIMEZONE components. XDAYLIGHT starts with "BEGIN:DAYLIGHT" and ends with "END:DAYLIGHT, just like other components, but is not defined as a component in RFC2445. ( See RFC2445, page 61 ) In Libical, it is a component.

There are also pseudo componentsthat are conceptually derived classess of VALARM. RFC2446 defines what properties may be included in each component, and for VALARM, the set of properties it may have depends on the value of the ACTION property.

For instance, if a VALARM component has an ACTION property with the value of "AUDIO," the component must also have an "ATTACH" property. However, if the ACTION value is "DISPLAY," the component must have a DESCRIPTION property.

To handle these various, complex restrictions, libical has pseudo components for each type of alarm: XAUDIOALARM, XDISPLAYALARM, XEMAILALARM and XPROCEDUREALARM.

Combined Values

Many values can take more than one type. TRIGGER, for instance, can have a value type of with DURATION or of DATE-TIME. It is natural to have interfaces that would return the value of a property, but it is cumbersone for a single routine to return multiple types. So, in libical, properties that can have multiple types are given a single type that is the union of their RFC2445 types. In libical, the value of the TRIGGER property resolves to

struct icaltriggertype

This type is a union of a DURATION and a DATE-TIME.

Multi-Valued Properties

Some properties, such as CATEGORIES, have a single value type, but may have multiple values in a single instance. This also results in a cumbersome interface -- CATEGORIES accessors would have to return a list which all other accessors returned a single value. In libical, all properties have a single value, and multi-valued properties are broken down into multiple single valued properties during parsing. The is,

CATEGORIES: work, home

becomes in libical's internal representation

CATEGORIES: work CATEGORIES: home

Oddly, RFC2445 allows some multi-valued properties ( like FREEBUSY ) to exist as both a multi-values property and as multiple single value properties, while others ( like CATEGORIES ) can only exist as single multi-valued properties. This makes the internal representation for CATEGORIES illegal. However when you convert a component to a string, the library will collect all of the CATEGORIES properties into one.

Implementation Limitations Using libical Creating Components Constructor interfaces vaargs Constructors Parsing Text Files Accessing Components Finding Components Removing Components

Removing an element from a list while iterating through the list can cause problems, since you will probably be removing the element that the internal iterator points to. This will result in the iteration loop terminating immediately after removing the element. To avoid the problem, you will need to step the iterator ahead of the element you are going to remove, like this:

for(c = icalcomponent_get_first_component(s); c != 0; c = next) { next = icalcomponent_get_next_component(s); icalcomponent_remove_component(s,c); }

Finding Properties Removing Properties Getting Values Setting Values Getting Parameters Setting Parameters Removing Parameters Storing Objects

When you store a component to the database with icalstore_add_component, you give the library takes the memory, so the caller does not own the component anymore. If you want to keep ownership, use clone to make a copy. ( See "Memory Management" and "Naming Starndard for more about routines with "add" in the name. )

Memory Management

Here are the memory rules for the C library:

1)If the function name has "new" in it, the caller gets control of the memory. ( such as icalcomponent_new(), or icalproperty_new_clone() ) 2)If you got the memory from a routine with new in it, you must call the corresponding *_free routine to free the memory. ( Use icalcomponent_free() to free objects created with icalcomponent_new()) 3)If the function name has "add" in it, the caller is transfering control of the memory to the routine. ( icalproperty_add_parameter() ) 4)If the function name has "remove" in it, the caller passes in a pointer to an object and after the call returns, the caller owns the object. So, before you call icalcomponent_remove_property(comp,foo), you do not own "foo" and after the call returns, you do. 5)If the routine returns a string, libical owns the memory and will put it on a ring buffer to reclaim later. You'd better strdup it if you want to keep it, and you don't have to delete it.

Error Handling Return values icalerrno Component errors Naming Standard

Structures that you access with the "struct" keyword, such as "struct icaltimetype" are things that you are allowed to see inside and poke at.

Structures that you access though a typedef, such as "icalcomponent" are things where all of the data is hidden.

Component names that start with "V" are part of RFC 2445 or another iCal standard. Component names that start with "X" are also part of the spec, but they are not actually components in the spec. However, they look and act like components, so they are components in libical. Names that start with "XLIC" or "X-LIC" are not part of any iCal spec. They are used internally by libical.

Hacks and Bugs