This commit was manufactured by cvs2svn to create tagGNOME_UTILS_1_1_0

'GNOME_UTILS_1_1_0'.

svn path=/tags/GNOME_UTILS_1_1_0/; revision=2567

1 files changed, 0 insertions, 2256 deletions

diff --git a/libical/doc/UsingLibical.lyx b/libical/doc/UsingLibical.lyx
deleted file mode 100644
index b55cbb5909..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.2 2000/04/18 18:17:03 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