reparing damage from removing files

svn path=/trunk/; revision=3042

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