diff options
Diffstat (limited to 'libical/doc/UsingLibical.lyx')
| -rw-r--r-- | libical/doc/UsingLibical.lyx | 2256 |
1 files changed, 2256 insertions, 0 deletions
diff --git a/libical/doc/UsingLibical.lyx b/libical/doc/UsingLibical.lyx new file mode 100644 index 0000000000..afc5b0608d --- /dev/null +++ b/libical/doc/UsingLibical.lyx @@ -0,0 +1,2256 @@ +#This file was created by <eric> Sat Feb 19 10:33:21 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 \LyXTable +multicol5 +5 2 0 0 -1 -1 -1 -1 +1 0 0 0 +1 0 0 0 +1 0 0 0 +1 0 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.15, does not implement iRip or CAP. + ) +\layout Standard + +This documentation assumes that you are familiar with the iCalendar standards + RFC2445 and RFC2446. + these specifications are online on the CALSCH webpage at: +\layout Verbatim + +http://www.imc.org/ietf-calendar/ +\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 Verbatim + +http://softwarestudio.org/libical/index.html +\layout Standard + +and a mailing list that you can join by sending the following mail: +\layout Verbatim + +To: minimalist@softwarestudio.org +\layout Verbatim + +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 Verbatim + +$Id: UsingLibical.lyx,v 1.4 2000/05/15 06:18:16 ericb Exp $ +\layout Section + +Building the Library +\layout Standard + +Libical uses autoconf to generate makefiles, although it uses none of the + autoconf flags to influence the compilation. + It should built with no adjustments on Linux, FreeBSD and Solaris. + +\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 Verbatim + +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 Standard +\added_space_bottom 0.3cm +\begin_float fig +\layout Standard + + +\begin_inset Figure size 180 147 +file icaluml.eps +flags 13 + +\end_inset + + +\end_float +When a component is send across a network, if it is un-encrypted, it will + look something like: +\layout Code + +BEGIN:VEVENT +\layout Code + +DTSTAMP:19980309T231000Z +\layout Code + +UID:guid-1.host1.com +\layout Code + +ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com +\layout Code + +ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP: +\layout Code + + +\protected_separator + MAILTO:employee-A@host.com +\layout Code + +DESCRIPTION:Project XYZ Review Meeting +\layout Code + +CATEGORIES:MEETING +\layout Code + +CLASS:PUBLIC +\layout Code + +CREATED:19980309T130000Z +\layout Code + +SUMMARY:XYZ Project Review +\layout Code + +DTSTART;TZID=US-Eastern:19980312T083000 +\layout Code + +DTEND;TZID=US-Eastern:19980312T093000 +\layout Code + +LOCATION:1CP Conference Room 4350 +\layout Code + +END:VEVENT +\layout Subsection + +Core iCal classes +\layout Subsubsection + +Components +\layout Subsubsection + +Properties +\layout Subsubsection + +Values +\layout Subsubsection + +Parameters +\layout Subsection + +Other elements of libical +\layout Standard + +In addition to the core iCal classes, libical has many other types, structures, + classes that aid in creating and using iCal components. + +\layout Subsubsection + +Enumerations +\layout Subsubsection + +Types +\layout Subsubsection + +The Parser +\layout Subsubsection + +Restrictions +\layout Subsubsection + +Error objects +\layout Subsubsection + +Memory Management +\layout Subsubsection + +Storage classes +\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. + For instanace, the timezone properties associated with daylight savings + time 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,this grouping is represented by the + XDAYLIGHT component. + Standard iCAL components all start with the letter +\begin_inset Quotes eld +\end_inset + +V, +\begin_inset Quotes erd +\end_inset + + while pseudo components start with +\begin_inset Quotes erd +\end_inset + +X. +\begin_inset Quotes erd +\end_inset + + +\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 Verbatim + +CATEGORIES: work, home +\layout Standard + +becomes in libical's internal representation +\layout Verbatim + +CATEGORIES: work +\layout Verbatim + +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 + +icalcomponent *event; +\layout Code + +icalproperty *prop; +\layout Code + +icalparameter *param; +\layout Code + +struct icaltimetype atime; +\layout Code + +event = icalcomponent_new(ICAL_VEVENT_COMPONENT); +\layout Code + +prop = icalproperty_new_dtstamp(atime) ; +\layout Code + +icalcomponent_add_property(event, prop); +\layout Code + +prop = icalproperty_new_uid(strdup("guid-1.host1.com")) ); +\layout Code + +icalcomponent_add_property(event,prop); +\layout Code + +prop=icalproperty_new_organizer(strdup("mrbig@host.com")); +\layout Code + +param = icalparameter_new_role(ICAL_ROLE_CHAIR) +\layout Code + +icalproperty_add_parameter(prop, param); +\layout Code + +icalcomponent_add_property(event,prop); +\layout Standard + +While we are on this example, you should notice that libical uses a semi-object- +oriented style of interface. + Most things you work with are objects, that are instantiated with a constructor + that has +\begin_inset Quotes eld +\end_inset + +new +\begin_inset Quotes erd +\end_inset + + in the name. + Also note that, other than the object reference, most structure data is + passed in to libical routines by value. + Strings, of course, are passed in by reference, but libical will take ownership + of the memory, so you had beter strdup() the data unless you want a core + dump when the memory is freed for the second time. + Libical has some complex bu very regular memory handling rules. + These are detailed in section +\begin_inset LatexCommand \ref{sec:memory} + +\end_inset + +. +\layout Standard + +If any of the constructors fail, they will return 0. + If you try to insert 0 into a property or component, or use a zero-valued + object reference, libical will either silently ignore the error or will + abort with an error message. + This behavior is controlled by a compile time flag (ICAL_ERRORS_ARE_FATAL), + and will abort by default. + +\layout Subsubsection + +vaargs Constructors +\layout Standard + +There is another way to create complex components, which is arguable more + elegant, if you are not horrified by vaargs. + The vaargs constructor interface all you to create intricate components + in a single block of text. + +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + calendar = +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +icalcomponent_vanew( +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + ICAL_VCALENDAR_COMPONENT, +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + icalproperty_new_version(strdup("2.0")), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + icalproperty_new_prodid(strdup("-//RDU Software//NONSGML HandCal//EN")), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + icalcomponent_vanew( +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +ICAL_VEVENT_COMPONENT, +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty_new_dtstamp(atime), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty_new_uid(strdup("guid-1.host1.com")), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty_vanew_organizer( +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + strdup("mrbig@host.com"), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + icalparameter_new_role(ICAL_ROLE_CHAIR), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + 0 +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty_vanew_attendee( +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + strdup("employee-A@host.com"), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + icalparameter_new_role(ICAL_ROLE_REQPARTICIPANT), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + icalparameter_new_rsvp(1), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + icalparameter_new_cutype(ICAL_CUTYPE_GROUP), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + 0 +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + ), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty_new_location(strdup("1CP Conference Room 4350")), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +0 +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +), +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + 0 +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + ); +\layout Standard + +This form is similar to the regular constructor, except that they have +\begin_inset Quotes eld +\end_inset + +vanew +\begin_inset Quotes erd +\end_inset + + instead of +\begin_inset Quotes eld +\end_inset + +new +\begin_inset Quotes erd +\end_inset + + in the name. + The arguments are similar too, except that the component contstructor can + have a list of properties, and the property constructor can have a list + or parameters. + Be sure to terminate every list with a '0', or your code will crash, if + you are lucky. + +\layout Subsubsection + +Parsing Text Files +\layout Standard + +The final way to create components will probably be the most common; you + can create components from RFC2445 compliant text. + If you have the string in memory, use +\layout Verbatim + +icalcomponent* icalparser_parse_string(char* str); +\layout Standard + +This may seem wasteful if you want to pull a large component off of the + network; you may prefer to parse the component line by line. + This is possible too, with +\layout Verbatim + +icalcomponent* icalparser_parse(char*(*line_gen_func)(char *s, size_t size, + void *d)); +\layout Standard + +This routine takes a pointer to a function that copies 'size' characters + to 's'. + The routine returns 's', similar to fgets(). + See string_line_generator in icalparser.c for an example. + +\layout Subsection + +Accessing Components +\layout Standard + +Given a reference to a component, you probably will want to access the propertie +s, parameters and values inside. + +\layout Subsubsection + +Finding Components +\layout Standard + +To find a sub-component of a component, use: +\layout Verbatim + +icalproperty* icalcomponent_get_first_component( +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +icalcomponent* component, +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +icalcomponent_kind kind); +\layout Standard + +This routine will return a reference to the first component of the type + 'kind.' The key kind values, listed in icalenums.h are: +\layout Code + +ICAL_ANY_COMPONENT +\layout Code + +ICAL_VEVENT_COMPONENT +\layout Code + +ICAL_VTODO_COMPONENT +\layout Code + +ICAL_VJOURNAL_COMPONENT +\layout Code + +ICAL_VCALENDAR_COMPONENT +\layout Code + +ICAL_VFREEBUSY_COMPONENT +\layout Code + +ICAL_VALARM_COMPONENT +\layout Standard + +These are only the most common components; there are many more listed in + icalenums.h. +\layout Standard + +As you might guess, if there is more than one subcomponent of the type you + have chosen, this routine will return only the first. + to get at the others, you need to iterate through the component. + +\layout Subsubsection + +Interating Through Components +\layout Standard + +Iteration requires a second routine to get the next subcomponent after the + first: +\layout Verbatim + +icalcomponent* icalcomponent_get_next_component(icalcomponent* component, + +\layout Verbatim + +icalcomponent_kind kind); +\layout Standard + +With the 'first' and 'next' routines, you can create a for loop to iterate + through all of a components subcomponents +\layout Code + + +\protected_separator + for(c = icalcomponent_get_first_component(comp,ICAL_ANY_COMPONENT); +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +c != 0; +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +c = icalcomponent_get_next_component(comp,ICAL_ANY_COMPONENT)) +\layout Code + +{ +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + do_something(c); +\layout Code + +} +\layout Standard + +This code bit wil iterate through all of the subcomponents in 'comp' but + you can select a specific type of component by changing ICAL_ANY_COMPONENT + to another component type. +\layout Subsubsection + +Removing Components +\layout Standard + +Libical component have internal iterators, so you can only have one iteration + over a component at a time. + 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 + +\protected_separator + +\protected_separator + +\protected_separator +c != 0; +\layout Code + + +\protected_separator + +\protected_separator + +\protected_separator + +\protected_separator +c = next +\layout Code + +{ +\protected_separator + +\protected_separator + +\layout Code + + +\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 + +Working with properties and parameters +\layout Standard + +Finding, iterating and removing properties works the same as it does for + components, using the property-specific or parameter-specific interfaces: + +\layout Verbatim + +icalproperty* icalcomponent_get_first_property( +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalcomponent* component, +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty_kind kind); +\layout Verbatim + +icalproperty* icalcomponent_get_next_property( +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalcomponent* component, +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty_kind kind); +\layout Verbatim + +void icalcomponent_add_property( +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalcomponent* component, +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty* property); +\layout Verbatim + +void icalcomponent_remove_property( +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalcomponent* component, +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty* property); +\layout Verbatim + +icalparameter* icalproperty_get_first_parameter( +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty* prop, +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalparameter_kind kind); +\layout Verbatim + +icalparameter* icalproperty_get_next_parameter( +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty* prop, +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalparameter_kind kind); +\layout Verbatim + +void icalproperty_add_parameter( +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty* prop, +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalparameter* parameter); +\layout Verbatim + +void icalproperty_remove_parameter( +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalproperty* prop, +\layout Verbatim + + +\protected_separator + +\protected_separator + +\protected_separator +icalparameter_kind kind); +\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 + + +\begin_inset LatexCommand \label{sec:memory} + +\end_inset + +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. + X-LIC-ERROR +\layout Subsubsection + +Return values +\layout Subsubsection + +icalerrno +\layout Subsubsection + +Component errors +\layout Subsubsection + +icalerror_stop_here +\layout Subsubsection + +X-LIC-ERROR +\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 + +_PARAMETER +\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 another + list. + +\layout Standard + +Finding compliance errors +\layout Section + +Performance +\layout Standard + +Checking restrictions is computationally expensive +\layout Section + +Hacks and Bugs +\the_end |