diff options
Diffstat (limited to 'libical/doc/UsingLibical.lyx')
| -rw-r--r-- | libical/doc/UsingLibical.lyx | 2256 |
1 files changed, 0 insertions, 2256 deletions
diff --git a/libical/doc/UsingLibical.lyx b/libical/doc/UsingLibical.lyx deleted file mode 100644 index 1742e3af00..0000000000 --- a/libical/doc/UsingLibical.lyx +++ /dev/null @@ -1,2256 +0,0 @@ -#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.5 2000/06/06 22:48:07 alves 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 |