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, 0 insertions, 1339 deletions
diff --git a/libical/doc/UsingLibical.lyx b/libical/doc/UsingLibical.lyx deleted file mode 100644 index 20eaffd288..0000000000 --- a/libical/doc/UsingLibical.lyx +++ /dev/null @@ -1,719 +0,0 @@ -#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 deleted file mode 100644 index d967bd860c..0000000000 --- a/libical/doc/UsingLibical.sgml +++ /dev/null @@ -1,318 +0,0 @@ -<!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 deleted file mode 100644 index f80ea31121..0000000000 --- a/libical/doc/UsingLibical.txt +++ /dev/null @@ -1,302 +0,0 @@ - - -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 |