diff options
Diffstat (limited to 'libical/doc')
| -rw-r--r-- | libical/doc/UsingLibical.lyx | 719 | ||||
| -rw-r--r-- | libical/doc/UsingLibical.sgml | 318 | ||||
| -rw-r--r-- | libical/doc/UsingLibical.txt | 302 |
3 files changed, 1339 insertions, 0 deletions
diff --git a/libical/doc/UsingLibical.lyx b/libical/doc/UsingLibical.lyx new file mode 100644 index 0000000000..20eaffd288 --- /dev/null +++ b/libical/doc/UsingLibical.lyx @@ -0,0 +1,719 @@ +#This file was created by <eric> Mon Feb 7 20:19:42 2000 +#LyX 1.0 (C) 1995-1999 Matthias Ettrich and the LyX Team +\lyxformat 2.15 +\textclass linuxdoc +\language default +\inputencoding default +\fontscheme default +\graphics default +\paperfontsize default +\spacing single +\papersize Default +\paperpackage a4 +\use_geometry 0 +\use_amsmath 0 +\paperorientation portrait +\secnumdepth 3 +\tocdepth 3 +\paragraph_separation indent +\defskip medskip +\quotes_language english +\quotes_times 2 +\papercolumns 1 +\papersides 1 +\paperpagestyle default + +\layout Title + +Using Libical +\layout Author + +Eric Busboom (eric@softwarestudio.org) +\layout Date + +January 2000 +\layout Section + +Introduction +\layout Standard + +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. + +\layout Standard + +Libical implements the following specifications and protocols +\layout Standard +\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable +multicol5 +5 2 0 0 -1 -1 -1 -1 +1 1 0 0 +1 1 0 0 +1 1 0 0 +1 1 0 0 +1 1 0 0 +8 1 0 "" "" +8 1 1 "" "" +0 8 1 0 0 0 0 "" "" +0 8 1 0 0 0 0 "" "" +0 8 1 0 0 0 0 "" "" +0 8 1 0 0 0 0 "" "" +0 8 1 0 0 0 0 "" "" +0 8 1 0 0 0 0 "" "" +0 8 1 0 0 0 0 "" "" +0 8 1 0 0 0 0 "" "" +0 8 1 0 0 0 0 "" "" +0 8 1 0 0 0 0 "" "" + +iCal Core +\newline +2445 +\newline +iTIP +\newline +2446 +\newline +iMIP +\newline +2447 +\newline +iRIP +\newline +draft +\newline +CAP +\newline +draft +\layout Standard + +(The current version, 0.14, does not implement iRip or CAP. + ) +\layout Standard + +This documentation assumes that you are familiar with the iCalendar standards + RFC2445 and RFC2446. +\layout Subsection + +The libical project +\layout Standard + +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 +\layout Quote + +http://softwarestudio.org/libical/index.html +\layout Standard + +and a mailing list that you can join by sending the following mail: +\layout Code + +To: minimalist@softwarestudio.org +\layout Code + +Subject: subscribe libical +\layout Subsection + +License +\layout Standard + +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. +\layout Standard + +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. +\layout Subsection + +Purpose & Goals +\layout Subsection + +Document version +\layout Standard + +$Id: UsingLibical.lyx,v 1.1 2000/02/17 18:02:36 alves Exp $ +\layout Section + +Building the Library +\layout Section + +Structure +\layout Standard + +The iCal calendar model is based on four types of objects: components, propertie +s, values and parameters. + +\layout Standard + +Properties are the fundamental unit of information in iCal, and they work + a bit like a hash entry, with a constant key and a variable value. + Properties may also have modifiers, called parameters. + In the iCal content line +\layout Code + +ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com +\layout Standard + +The property name is +\begin_inset Quotes eld +\end_inset + +ORGANIZER, +\begin_inset Quotes erd +\end_inset + + the value of the property is +\begin_inset Quotes eld +\end_inset + +mrbig@host.com +\begin_inset Quotes erd +\end_inset + + and the +\begin_inset Quotes eld +\end_inset + +ROLE +\begin_inset Quotes erd +\end_inset + + parameter specifies that Mr Big is the chair of the meetings associated + with this property. + +\layout Standard + +Components are groups of properties that represent the core objects of a + calendar system, such as events or timezones. + +\layout Standard + +The central goal of libical is to parse iTIP data into an internal representatio +n of Components, Properties, Parameters an Values, and to allow the user + to manipulate the data in various ways +\layout Subsection + +Components +\layout Subsection + +Properties +\layout Subsection + +Values +\layout Subsection + +Parameters +\layout Subsection + +Enumerations +\layout Subsection + +Types +\layout Subsection + +The Parser +\layout Subsection + +Restrictions +\layout Subsection + +Memory Management +\layout Section + +Differences From RFCs +\layout Standard + +Libical has been designed to follow the standards as closely as possible, + so that the key objects in the standards are also keey objects in the library. + However, there are a few areas where the specifications are (arguably) + irregular, and following them exactly would result in an unfriendly interface. + These deviations make libical easier to use by maintaining a self-similar + interface. + +\layout Subsection + +Pseudo Components +\layout Standard + +Libical defines 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_inset Quotes eld +\end_inset + +BEGIN:DAYLIGHT +\begin_inset Quotes erd +\end_inset + + and ends with +\begin_inset Quotes eld +\end_inset + +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. + +\layout Standard + +There are also pseudo components that 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. + +\layout Standard + +For instance, if a VALARM component has an ACTION property with the value + of +\begin_inset Quotes eld +\end_inset + +AUDIO, +\begin_inset Quotes erd +\end_inset + + the component must also have an +\begin_inset Quotes eld +\end_inset + +ATTACH +\begin_inset Quotes erd +\end_inset + + property. + However, if the ACTION value is +\begin_inset Quotes eld +\end_inset + +DISPLAY, +\begin_inset Quotes erd +\end_inset + + the component must have a DESCRIPTION property. + +\layout Standard + +To handle these various, complex restrictions, libical has pseudo components + for each type of alarm: XAUDIOALARM, XDISPLAYALARM, XEMAILALARM and XPROCEDUREA +LARM. + +\layout Subsection + +Combined Values +\layout Standard + +Many values can take more than one type. + TRIGGER, for instance, can have a value type of with DURATION or of DATE-TIME. + These multiple types make it difficult to create routines to return the + value associated with a property. + +\layout Standard + +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. + For instance, in libical, the value of the TRIGGER property resolves to + +\noun on +struct icaltriggertype +\noun default +. + This type is a union of a DURATION and a DATE-TIME. + +\layout Subsection + +Multi-Valued Properties +\layout Standard + +Some properties, such as CATEGORIES have only one value type, but each CATEGORIE +S property can have multiple value instances. + This also results in a cumbersome interface -- CATEGORIES accessors would + have to return a list while 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. + That is, an input line like, +\layout Code + +CATEGORIES: work, home +\layout Standard + +becomes in libical's internal representation +\layout Code + +CATEGORIES: work +\layout Code + +CATEGORIES: home +\layout Standard + +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. + +\layout Section + +Implementation Limitations +\layout Section + +Using libical +\layout Subsection + +Creating Components +\layout Standard + +There are three ways to create components in Libical: creating individual + objects and assembling them, building entire objects in massive vaargs + calls, and parsing a text file containing iCalendar data. + +\layout Subsubsection + +Constructor Interfaces +\layout Standard + +Using constructor interfaces, you create each of the objects seperately + and them assemble them in to components: +\layout Code + +event = icalcomponent_new(ICAL_VEVENT_COMPONENT); +\layout Code + +icalcomponent_add_property(event, icalproperty_new_dtstamp(atime) ); +\layout Code + +icalcomponent_add_property(event,icalproperty_new_uid(strdup("guid-1.host1.com")) + ); +\layout Code + +property=icalproperty_new_organizer(strdup("mrbig@host.com")); +\layout Code + +icalproperty_add_parameter(property,icalparameter_new_role(ICAL_ROLE_CHAIR) + ); +\layout Code + +icalcomponent_add_property(event,property); +\layout Subsubsection + +vaargs Constructors +\layout Subsubsection + +Parsing Text Files +\layout Subsection + +Accessing Components +\layout Subsubsection + +Finding Components +\layout Subsubsection + +Removing Components +\layout Standard + +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: +\layout Code + +for(c = icalcomponent_get_first_component(parent_comp,ICAL_ANY_COMPONENT); + +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +c != 0; +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +c = next +\layout Code + +{ +\layout Code + + +\protected_separator + +\protected_separator + next = icalcomponent_get_next_component(parent_comp,ICAL_ANY_COMPONENT); +\layout Code + + +\protected_separator + +\protected_separator + icalcomponent_remove_component(parent_comp,c); +\layout Code + +} +\layout Subsubsection + +Finding Properties +\layout Subsubsection + +Removing Properties +\layout Subsubsection + +Getting Values +\layout Subsubsection + +Setting Values +\layout Subsubsection + +Getting Parameters +\layout Subsubsection + +Setting Parameters +\layout Subsubsection + +Removing Parameters +\layout Subsubsection + +Checking Component Validity +\layout Subsection + +Storing Objects +\layout Standard + +The libical distribution inclues a seperate library, libicalss, that allows + you to store iCal component data to disk in a variety of ways. + This library is documented seperately. + +\layout Subsection + +Memory Management +\layout Standard + +Libical relies heavily on dynamic allocation for both the core objects and + for the strings used to hold values. + Some of this memory the library caller owns and must free, and some of + the memory is managed by the library. + Here is a summary of the memory rules. + +\layout Description + +1) If the function name has "new" in it, the caller gets control of the + memory. + ( such as icalcomponent_new(), or icalproperty_new_clone() ) +\layout Description + +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()) + +\layout Description + +3) If the function name has "add" in it, the caller is transfering control + of the memory to the routine. + ( icalproperty_add_parameter() ) +\layout Description + +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. + +\layout Description + +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. + +\layout Subsection + +Error Handling +\layout Standard + +icalerror_errno. + Return values. + #defines. + icalerror_stop_here +\layout Subsubsection + +Return values +\layout Subsubsection + +icalerrno +\layout Subsubsection + +Component errors +\layout Subsection + +Naming Standard +\layout Standard + +Structures that you access with the +\begin_inset Quotes eld +\end_inset + +struct +\begin_inset Quotes erd +\end_inset + + keyword, such as +\begin_inset Quotes eld +\end_inset + +struct icaltimetype +\begin_inset Quotes erd +\end_inset + + are things that you are allowed to see inside and poke at. + +\layout Standard + +Structures that you access though a typedef, such as +\begin_inset Quotes eld +\end_inset + +icalcomponent +\begin_inset Quotes erd +\end_inset + + are things where all of the data is hidden. + +\layout Standard + +Component names that start with +\begin_inset Quotes eld +\end_inset + +V +\begin_inset Quotes erd +\end_inset + + are part of RFC 2445 or another iCal standard. + Component names that start with +\begin_inset Quotes eld +\end_inset + +X +\begin_inset Quotes erd +\end_inset + + 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 +\begin_inset Quotes eld +\end_inset + +XLIC +\begin_inset Quotes erd +\end_inset + + or +\begin_inset Quotes eld +\end_inset + +X-LIC +\begin_inset Quotes erd +\end_inset + + are not part of any iCal spec. + They are used internally by libical. + +\layout Standard + +Enums that identify a component, property, value or parameter end with +\begin_inset Quotes eld +\end_inset + +_COMPONENT, +\begin_inset Quotes erd +\end_inset + + +\begin_inset Quotes eld +\end_inset + +_PROPERTY, +\begin_inset Quotes erd +\end_inset + + +\begin_inset Quotes eld +\end_inset + +_VALUE, +\begin_inset Quotes erd +\end_inset + + or +\begin_inset Quotes eld +\end_inset + +_PAAMETER +\begin_inset Quotes erd +\end_inset + +s +\layout Standard + +Enums that identify a parameter value have the name of the parameter as + the second word. + For instance: ICAL_ROLE_REQPARTICIPANT or ICAL_PARTSTAT_ACCEPTED. +\layout Standard + +The enums for the parts of a recurarance rule and request statuses are irregular. + +\layout Section + +Useful Recipies +\layout Standard + +Iteration +\layout Standard + +Copying components. + Remember that you must clone or remove an object before putting in on anothr + list. + +\layout Standard + +Finding compliance errors +\layout Section + +Performance +\layout Standard + +Checking restrictions is computationally expensive +\layout Section + +Hacks and Bugs +\the_end diff --git a/libical/doc/UsingLibical.sgml b/libical/doc/UsingLibical.sgml new file mode 100644 index 0000000000..d967bd860c --- /dev/null +++ b/libical/doc/UsingLibical.sgml @@ -0,0 +1,318 @@ +<!doctype linuxdoc system> + +<!-- LinuxDoc file was created by LyX 1.0 (C) 1995-1999 by <eric> Wed Jan 5 22:30:06 2000 + --> + <article> + <title> +Using Libical + </title> + <author> +Eric Busboom (eric@softwarestudio.org) + </author> + <date> +January 2000 + </date> + <sect> +Introduction + <p> +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. + </p> + <p> +Libical implements the following specifications and protocols + </p> + <p> +iCal Core +2445 +iTIP +2446 +iMIP +2447 +iRIP +draft +CAP +draft + </p> + <p> +(The current version, 0.14, does not implement iRip or CAP. ) + </p> + <p> +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 + </p> + <p> + <quote> +http://softwarestudio.org/libical/index.html + </quote> +</p> <p> +and a mailing list that you can join by sending the following mail: + </p> + <p> + <code> +------------ +To: minimalist@softwarestudio.org +Subject: subscribe libical +------------ + </code> +</p> <p> +$Id: UsingLibical.lyx,v 1.3 2000/01/06 06:20:06 eric Exp eric $ + </p> + <sect1> +License + <p> +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. + </p> + <p> +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. + </p> + <sect1> +Purpose & Goals + <sect> +Building the Library + <sect> +Structure + <p> +The iCal calendar model is based on four types of objects: components, + properties, values and parameters. + </p> + <p> +Components are the fundamental grouping of calendar information + </p> + <p> +Properties are the fundamental unit of information. Each property is composed + of a type, a value and collection of parameters. + </p> + <sect1> +Components + <p> +Components are named clusters of properties + </p> + <sect1> +Properties + <sect1> +Values + <sect1> +Parameters + <sect1> +Storage + <sect2> +Cluster + <sect2> +Store + <sect2> +Calendar + <sect1> +Other bits + <p> +Restrictions + </p> + <p> +Types + </p> + <sect> +Differences From RFCs + <p> +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. + </p> + <sect1> +Pseudo Components + <p> +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. + + </p> + <p> +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. + </p> + <p> +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. + </p> + <p> +To handle these various, complex restrictions, libical has pseudo components + for each type of alarm: XAUDIOALARM, XDISPLAYALARM, XEMAILALARM and XPROCEDUREALARM. + + </p> + <sect1> +Combined Values + <p> +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 + </p> + <p> +struct icaltriggertype + </p> + <p> +This type is a union of a DURATION and a DATE-TIME. + </p> + <sect1> +Multi-Valued Properties + <p> +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, + </p> + <p> + <code> +CATEGORIES: work, home + </code> +</p> <p> +becomes in libical's internal representation + </p> + <p> + <code> +CATEGORIES: work +CATEGORIES: home + </code> +</p> <p> +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. + </p> + <sect> +Implementation Limitations + <sect> +Using libical + <sect1> +Creating Components + <sect2> +Constructor interfaces + <sect2> +vaargs Constructors + <sect2> +Parsing Text Files + <sect1> +Accessing Components + <sect2> +Finding Components + <sect2> +Removing Components + <p> +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: + </p> + <p> + <code> +for(c = icalcomponent_get_first_component(s); + c != 0; + c = next) +{ + next = icalcomponent_get_next_component(s); + icalcomponent_remove_component(s,c); +} + </code> +</p> <sect2> +Finding Properties + <sect2> +Removing Properties + <sect2> +Getting Values + <sect2> +Setting Values + <sect2> +Getting Parameters + <sect2> +Setting Parameters + <sect2> +Removing Parameters + <sect1> +Storing Objects + <p> +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. + ) + </p> + <sect1> +Memory Management + <p> +Here are the memory rules for the C library: + </p> + <p> + <descrip> + <tag> +1)</tag>If the function name has "new" in it, the caller gets + control of the memory. ( such as icalcomponent_new(), or icalproperty_new_clone() + ) + <tag> +2)</tag>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()) + <tag> +3)</tag>If the function name has "add" in it, the caller is + transfering control of the memory to the routine. ( icalproperty_add_parameter() + ) + <tag> +4)</tag>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. + <tag> +5)</tag>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. + </descrip> +</p> <sect1> +Error Handling + <sect2> +Return values + <sect2> +icalerrno + <sect2> +Component errors + <sect1> +Naming Standard + <p> +Structures that you access with the "struct" keyword, such as "struct icaltimetype" + are things that you are allowed to see inside and poke at. + </p> + <p> +Structures that you access though a typedef, such as "icalcomponent" are + things where all of the data is hidden. + </p> + <p> +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. + </p> + <sect> +Hacks and Bugs + + + </article> diff --git a/libical/doc/UsingLibical.txt b/libical/doc/UsingLibical.txt new file mode 100644 index 0000000000..f80ea31121 --- /dev/null +++ b/libical/doc/UsingLibical.txt @@ -0,0 +1,302 @@ + + +Using Libical + +Eric Busboom (eric@softwarestudio.org) + +January 2000 + +1 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 documentation assumes that you are familiar with the iCalendar +standards RFC2445 and RFC2446. + +1.1 The libical project + +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 + +------------ + +1.2 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. + +1.3 Purpose & Goals + +1.4 Document version + +$Id$ + +2 Building the Library + +3 Structure + +The iCal calendar model is based on four types of objects: components, +properties, values and parameters. + +Properties are the fundamental unit of information in iCal, and they +work a bit like a hash entry, with a constant key and a variable value. +Properties may also have modifiers, called parameters. In the iCal +content line + +ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com + +The property name is ``ORGANIZER,'' the value of the property is ``mrbig@host.com'' +and the ``ROLE'' parameter specifies that Mr Big is the chair of the +meetings associated with this property. + +Components are groups of properties that represent the core objects +of a calendar system, such as events or timezones. + +The central goal of libical is to parse iTIP data into an internal +representation of Components, Properties, Parameters an Values, and +to allow the user to manipulate the data in various ways + +3.1 Components + +3.2 Properties + +3.3 Values + +3.4 Parameters + +3.5 Enumerations + +3.6 Types + +3.7 The Parser + +3.8 Restrictions + +3.9 Memory Management + +4 Differences From RFCs + +Libical has been designed to follow the standards as closely as possible, +so that the key objects in the standards are also keey objects in +the library. However, there are a few areas where the specifications +are (arguably) irregular, and following them exactly would result +in an unfriendly interface. These deviations make libical easier to +use by maintaining a self-similar interface. + +4.1 Pseudo Components + +Libical defines 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 components that 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. + +4.2 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. These multiple +types make it difficult to create routines to return the value associated +with a property. + +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. For instance, +in libical, the value of the TRIGGER property resolves to struct icaltriggertype. +This type is a union of a DURATION and a DATE-TIME. + +4.3 Multi-Valued Properties + +Some properties, such as CATEGORIES have only one value type, but each +CATEGORIES property can have multiple value instances. This also results +in a cumbersome interface -- CATEGORIES accessors would have to return +a list while 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. +That is, an input line like, + +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. + +5 Implementation Limitations + +6 Using libical + +6.1 Creating Components + +6.1.1 Constructor Interfaces + +6.1.2 vaargs Constructors + +6.1.3 Parsing Text Files + +6.2 Accessing Components + +6.2.1 Finding Components + +6.2.2 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); + +} + +6.2.3 Finding Properties + +6.2.4 Removing Properties + +6.2.5 Getting Values + +6.2.6 Setting Values + +6.2.7 Getting Parameters + +6.2.8 Setting Parameters + +6.2.9 Removing Parameters + +6.2.10 Checking Component Validity + +6.3 Storing Objects + +The libical distribution inclues a seperate library, libicalss, that +allows you to store iCal component data to disk in a variety of ways. +This library is documented seperately. + +6.4 Memory Management + +Here are the memory rules for the 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. + +6.5 Error Handling + +6.5.1 Return values + +6.5.2 icalerrno + +6.5.3 Component errors + +6.6 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. + +7 Hacks and Bugs |