2257 lines
36 KiB
Plaintext
2257 lines
36 KiB
Plaintext
#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
|