720 lines
15 KiB
Plaintext
720 lines
15 KiB
Plaintext
#This file was created by <eric> Mon Feb 7 20:19:42 2000
|
|
#LyX 1.0 (C) 1995-1999 Matthias Ettrich and the LyX Team
|
|
\lyxformat 2.15
|
|
\textclass linuxdoc
|
|
\language default
|
|
\inputencoding default
|
|
\fontscheme default
|
|
\graphics default
|
|
\paperfontsize default
|
|
\spacing single
|
|
\papersize Default
|
|
\paperpackage a4
|
|
\use_geometry 0
|
|
\use_amsmath 0
|
|
\paperorientation portrait
|
|
\secnumdepth 3
|
|
\tocdepth 3
|
|
\paragraph_separation indent
|
|
\defskip medskip
|
|
\quotes_language english
|
|
\quotes_times 2
|
|
\papercolumns 1
|
|
\papersides 1
|
|
\paperpagestyle default
|
|
|
|
\layout Title
|
|
|
|
Using Libical
|
|
\layout Author
|
|
|
|
Eric Busboom (eric@softwarestudio.org)
|
|
\layout Date
|
|
|
|
January 2000
|
|
\layout Section
|
|
|
|
Introduction
|
|
\layout Standard
|
|
|
|
Libical is an Open Source implementation of the iCalendar protocols and
|
|
protocol data units.
|
|
The iCalendar specification describes how calendar clients can communicate
|
|
with calendar servers for users can store their calendar data and arrange
|
|
meetings with other users.
|
|
|
|
\layout Standard
|
|
|
|
Libical implements the following specifications and protocols
|
|
\layout Standard
|
|
\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable
|
|
multicol5
|
|
5 2 0 0 -1 -1 -1 -1
|
|
1 1 0 0
|
|
1 1 0 0
|
|
1 1 0 0
|
|
1 1 0 0
|
|
1 1 0 0
|
|
8 1 0 "" ""
|
|
8 1 1 "" ""
|
|
0 8 1 0 0 0 0 "" ""
|
|
0 8 1 0 0 0 0 "" ""
|
|
0 8 1 0 0 0 0 "" ""
|
|
0 8 1 0 0 0 0 "" ""
|
|
0 8 1 0 0 0 0 "" ""
|
|
0 8 1 0 0 0 0 "" ""
|
|
0 8 1 0 0 0 0 "" ""
|
|
0 8 1 0 0 0 0 "" ""
|
|
0 8 1 0 0 0 0 "" ""
|
|
0 8 1 0 0 0 0 "" ""
|
|
|
|
iCal Core
|
|
\newline
|
|
2445
|
|
\newline
|
|
iTIP
|
|
\newline
|
|
2446
|
|
\newline
|
|
iMIP
|
|
\newline
|
|
2447
|
|
\newline
|
|
iRIP
|
|
\newline
|
|
draft
|
|
\newline
|
|
CAP
|
|
\newline
|
|
draft
|
|
\layout Standard
|
|
|
|
(The current version, 0.14, does not implement iRip or CAP.
|
|
)
|
|
\layout Standard
|
|
|
|
This documentation assumes that you are familiar with the iCalendar standards
|
|
RFC2445 and RFC2446.
|
|
\layout Subsection
|
|
|
|
The libical project
|
|
\layout Standard
|
|
|
|
This code is under active development.
|
|
If you would like to contribute to the project, you can contact me, Eric
|
|
Busboom, at eric@softwarestudio.org.
|
|
The project has a webpage at
|
|
\layout Quote
|
|
|
|
http://softwarestudio.org/libical/index.html
|
|
\layout Standard
|
|
|
|
and a mailing list that you can join by sending the following mail:
|
|
\layout Code
|
|
|
|
To: minimalist@softwarestudio.org
|
|
\layout Code
|
|
|
|
Subject: subscribe libical
|
|
\layout Subsection
|
|
|
|
License
|
|
\layout Standard
|
|
|
|
The code and datafiles in this distribution are licensed under the Mozilla
|
|
Public License.
|
|
See http://www.mozilla.org/NPL/MPL-1.0.html for a copy of the license.
|
|
Alternately, you may use libical under the terms of the GNU Library General
|
|
Public License.
|
|
See http://www.fsf.org/copyleft/lesser.html for a copy of the LGPL.
|
|
\layout Standard
|
|
|
|
This dual license ensures that the library can be incorporated into both
|
|
proprietary code and GPL'd programs, and will benefit from improvements
|
|
made by programmers in both realms.
|
|
I will only accept changes into my version of the library if they are similarly
|
|
dual-licensed.
|
|
\layout Subsection
|
|
|
|
Purpose & Goals
|
|
\layout Subsection
|
|
|
|
Document version
|
|
\layout Standard
|
|
|
|
$Id: UsingLibical.lyx,v 1.1 2000/02/17 18:02:36 alves Exp $
|
|
\layout Section
|
|
|
|
Building the Library
|
|
\layout Section
|
|
|
|
Structure
|
|
\layout Standard
|
|
|
|
The iCal calendar model is based on four types of objects: components, propertie
|
|
s, values and parameters.
|
|
|
|
\layout Standard
|
|
|
|
Properties are the fundamental unit of information in iCal, and they work
|
|
a bit like a hash entry, with a constant key and a variable value.
|
|
Properties may also have modifiers, called parameters.
|
|
In the iCal content line
|
|
\layout Code
|
|
|
|
ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com
|
|
\layout Standard
|
|
|
|
The property name is
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
ORGANIZER,
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
the value of the property is
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
mrbig@host.com
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
and the
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
ROLE
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
parameter specifies that Mr Big is the chair of the meetings associated
|
|
with this property.
|
|
|
|
\layout Standard
|
|
|
|
Components are groups of properties that represent the core objects of a
|
|
calendar system, such as events or timezones.
|
|
|
|
\layout Standard
|
|
|
|
The central goal of libical is to parse iTIP data into an internal representatio
|
|
n of Components, Properties, Parameters an Values, and to allow the user
|
|
to manipulate the data in various ways
|
|
\layout Subsection
|
|
|
|
Components
|
|
\layout Subsection
|
|
|
|
Properties
|
|
\layout Subsection
|
|
|
|
Values
|
|
\layout Subsection
|
|
|
|
Parameters
|
|
\layout Subsection
|
|
|
|
Enumerations
|
|
\layout Subsection
|
|
|
|
Types
|
|
\layout Subsection
|
|
|
|
The Parser
|
|
\layout Subsection
|
|
|
|
Restrictions
|
|
\layout Subsection
|
|
|
|
Memory Management
|
|
\layout Section
|
|
|
|
Differences From RFCs
|
|
\layout Standard
|
|
|
|
Libical has been designed to follow the standards as closely as possible,
|
|
so that the key objects in the standards are also keey objects in the library.
|
|
However, there are a few areas where the specifications are (arguably)
|
|
irregular, and following them exactly would result in an unfriendly interface.
|
|
These deviations make libical easier to use by maintaining a self-similar
|
|
interface.
|
|
|
|
\layout Subsection
|
|
|
|
Pseudo Components
|
|
\layout Standard
|
|
|
|
Libical defines components for groups of properties that look and act like
|
|
components, but are not defined as components in the specification.
|
|
XDAYLIGHT and XSTANDARD are notable examples.
|
|
These pseudo components group properties within the VTIMEZONE components.
|
|
XDAYLIGHT starts with
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
BEGIN:DAYLIGHT
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
and ends with
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
END:DAYLIGHT, just like other components, but is not defined as a component
|
|
in RFC2445.
|
|
( See RFC2445, page 61 ) In Libical, it is a component.
|
|
|
|
\layout Standard
|
|
|
|
There are also pseudo components that are conceptually derived classess
|
|
of VALARM.
|
|
RFC2446 defines what properties may be included in each component, and
|
|
for VALARM, the set of properties it may have depends on the value of the
|
|
ACTION property.
|
|
|
|
\layout Standard
|
|
|
|
For instance, if a VALARM component has an ACTION property with the value
|
|
of
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
AUDIO,
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
the component must also have an
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
ATTACH
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
property.
|
|
However, if the ACTION value is
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
DISPLAY,
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
the component must have a DESCRIPTION property.
|
|
|
|
\layout Standard
|
|
|
|
To handle these various, complex restrictions, libical has pseudo components
|
|
for each type of alarm: XAUDIOALARM, XDISPLAYALARM, XEMAILALARM and XPROCEDUREA
|
|
LARM.
|
|
|
|
\layout Subsection
|
|
|
|
Combined Values
|
|
\layout Standard
|
|
|
|
Many values can take more than one type.
|
|
TRIGGER, for instance, can have a value type of with DURATION or of DATE-TIME.
|
|
These multiple types make it difficult to create routines to return the
|
|
value associated with a property.
|
|
|
|
\layout Standard
|
|
|
|
It is natural to have interfaces that would return the value of a property,
|
|
but it is cumbersone for a single routine to return multiple types.
|
|
So, in libical, properties that can have multiple types are given a single
|
|
type that is the union of their RFC2445 types.
|
|
For instance, in libical, the value of the TRIGGER property resolves to
|
|
|
|
\noun on
|
|
struct icaltriggertype
|
|
\noun default
|
|
.
|
|
This type is a union of a DURATION and a DATE-TIME.
|
|
|
|
\layout Subsection
|
|
|
|
Multi-Valued Properties
|
|
\layout Standard
|
|
|
|
Some properties, such as CATEGORIES have only one value type, but each CATEGORIE
|
|
S property can have multiple value instances.
|
|
This also results in a cumbersome interface -- CATEGORIES accessors would
|
|
have to return a list while all other accessors returned a single value.
|
|
In libical, all properties have a single value, and multi-valued properties
|
|
are broken down into multiple single valued properties during parsing.
|
|
That is, an input line like,
|
|
\layout Code
|
|
|
|
CATEGORIES: work, home
|
|
\layout Standard
|
|
|
|
becomes in libical's internal representation
|
|
\layout Code
|
|
|
|
CATEGORIES: work
|
|
\layout Code
|
|
|
|
CATEGORIES: home
|
|
\layout Standard
|
|
|
|
Oddly, RFC2445 allows some multi-valued properties ( like FREEBUSY ) to
|
|
exist as both a multi-values property and as multiple single value properties,
|
|
while others ( like CATEGORIES ) can only exist as single multi-valued
|
|
properties.
|
|
This makes the internal representation for CATEGORIES illegal.
|
|
However when you convert a component to a string, the library will collect
|
|
all of the CATEGORIES properties into one.
|
|
|
|
\layout Section
|
|
|
|
Implementation Limitations
|
|
\layout Section
|
|
|
|
Using libical
|
|
\layout Subsection
|
|
|
|
Creating Components
|
|
\layout Standard
|
|
|
|
There are three ways to create components in Libical: creating individual
|
|
objects and assembling them, building entire objects in massive vaargs
|
|
calls, and parsing a text file containing iCalendar data.
|
|
|
|
\layout Subsubsection
|
|
|
|
Constructor Interfaces
|
|
\layout Standard
|
|
|
|
Using constructor interfaces, you create each of the objects seperately
|
|
and them assemble them in to components:
|
|
\layout Code
|
|
|
|
event = icalcomponent_new(ICAL_VEVENT_COMPONENT);
|
|
\layout Code
|
|
|
|
icalcomponent_add_property(event, icalproperty_new_dtstamp(atime) );
|
|
\layout Code
|
|
|
|
icalcomponent_add_property(event,icalproperty_new_uid(strdup("guid-1.host1.com"))
|
|
);
|
|
\layout Code
|
|
|
|
property=icalproperty_new_organizer(strdup("mrbig@host.com"));
|
|
\layout Code
|
|
|
|
icalproperty_add_parameter(property,icalparameter_new_role(ICAL_ROLE_CHAIR)
|
|
);
|
|
\layout Code
|
|
|
|
icalcomponent_add_property(event,property);
|
|
\layout Subsubsection
|
|
|
|
vaargs Constructors
|
|
\layout Subsubsection
|
|
|
|
Parsing Text Files
|
|
\layout Subsection
|
|
|
|
Accessing Components
|
|
\layout Subsubsection
|
|
|
|
Finding Components
|
|
\layout Subsubsection
|
|
|
|
Removing Components
|
|
\layout Standard
|
|
|
|
Removing an element from a list while iterating through the list can cause
|
|
problems, since you will probably be removing the element that the internal
|
|
iterator points to.
|
|
This will result in the iteration loop terminating immediately after removing
|
|
the element.
|
|
To avoid the problem, you will need to step the iterator ahead of the element
|
|
you are going to remove, like this:
|
|
\layout Code
|
|
|
|
for(c = icalcomponent_get_first_component(parent_comp,ICAL_ANY_COMPONENT);
|
|
|
|
\layout Code
|
|
|
|
|
|
\protected_separator
|
|
|
|
\protected_separator
|
|
|
|
\protected_separator
|
|
|
|
\protected_separator
|
|
c != 0;
|
|
\layout Code
|
|
|
|
|
|
\protected_separator
|
|
|
|
\protected_separator
|
|
|
|
\protected_separator
|
|
|
|
\protected_separator
|
|
c = next
|
|
\layout Code
|
|
|
|
{
|
|
\layout Code
|
|
|
|
|
|
\protected_separator
|
|
|
|
\protected_separator
|
|
next = icalcomponent_get_next_component(parent_comp,ICAL_ANY_COMPONENT);
|
|
\layout Code
|
|
|
|
|
|
\protected_separator
|
|
|
|
\protected_separator
|
|
icalcomponent_remove_component(parent_comp,c);
|
|
\layout Code
|
|
|
|
}
|
|
\layout Subsubsection
|
|
|
|
Finding Properties
|
|
\layout Subsubsection
|
|
|
|
Removing Properties
|
|
\layout Subsubsection
|
|
|
|
Getting Values
|
|
\layout Subsubsection
|
|
|
|
Setting Values
|
|
\layout Subsubsection
|
|
|
|
Getting Parameters
|
|
\layout Subsubsection
|
|
|
|
Setting Parameters
|
|
\layout Subsubsection
|
|
|
|
Removing Parameters
|
|
\layout Subsubsection
|
|
|
|
Checking Component Validity
|
|
\layout Subsection
|
|
|
|
Storing Objects
|
|
\layout Standard
|
|
|
|
The libical distribution inclues a seperate library, libicalss, that allows
|
|
you to store iCal component data to disk in a variety of ways.
|
|
This library is documented seperately.
|
|
|
|
\layout Subsection
|
|
|
|
Memory Management
|
|
\layout Standard
|
|
|
|
Libical relies heavily on dynamic allocation for both the core objects and
|
|
for the strings used to hold values.
|
|
Some of this memory the library caller owns and must free, and some of
|
|
the memory is managed by the library.
|
|
Here is a summary of the memory rules.
|
|
|
|
\layout Description
|
|
|
|
1) If the function name has "new" in it, the caller gets control of the
|
|
memory.
|
|
( such as icalcomponent_new(), or icalproperty_new_clone() )
|
|
\layout Description
|
|
|
|
2) If you got the memory from a routine with new in it, you must call the
|
|
corresponding *_free routine to free the memory.
|
|
( Use icalcomponent_free() to free objects created with icalcomponent_new())
|
|
|
|
\layout Description
|
|
|
|
3) If the function name has "add" in it, the caller is transfering control
|
|
of the memory to the routine.
|
|
( icalproperty_add_parameter() )
|
|
\layout Description
|
|
|
|
4) If the function name has "remove" in it, the caller passes in a pointer
|
|
to an object and after the call returns, the caller owns the object.
|
|
So, before you call icalcomponent_remove_property(comp,foo), you do not
|
|
own "foo" and after the call returns, you do.
|
|
|
|
\layout Description
|
|
|
|
5) If the routine returns a string, libical owns the memory and will put
|
|
it on a ring buffer to reclaim later.
|
|
You'd better strdup() it if you want to keep it, and you don't have to
|
|
delete it.
|
|
|
|
\layout Subsection
|
|
|
|
Error Handling
|
|
\layout Standard
|
|
|
|
icalerror_errno.
|
|
Return values.
|
|
#defines.
|
|
icalerror_stop_here
|
|
\layout Subsubsection
|
|
|
|
Return values
|
|
\layout Subsubsection
|
|
|
|
icalerrno
|
|
\layout Subsubsection
|
|
|
|
Component errors
|
|
\layout Subsection
|
|
|
|
Naming Standard
|
|
\layout Standard
|
|
|
|
Structures that you access with the
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
struct
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
keyword, such as
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
struct icaltimetype
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
are things that you are allowed to see inside and poke at.
|
|
|
|
\layout Standard
|
|
|
|
Structures that you access though a typedef, such as
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
icalcomponent
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
are things where all of the data is hidden.
|
|
|
|
\layout Standard
|
|
|
|
Component names that start with
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
V
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
are part of RFC 2445 or another iCal standard.
|
|
Component names that start with
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
X
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
are also part of the spec, but they are not actually components in the
|
|
spec.
|
|
However, they look and act like components, so they are components in libical.
|
|
Names that start with
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
XLIC
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
or
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
X-LIC
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
are not part of any iCal spec.
|
|
They are used internally by libical.
|
|
|
|
\layout Standard
|
|
|
|
Enums that identify a component, property, value or parameter end with
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
_COMPONENT,
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
_PROPERTY,
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
_VALUE,
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
or
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
_PAAMETER
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
s
|
|
\layout Standard
|
|
|
|
Enums that identify a parameter value have the name of the parameter as
|
|
the second word.
|
|
For instance: ICAL_ROLE_REQPARTICIPANT or ICAL_PARTSTAT_ACCEPTED.
|
|
\layout Standard
|
|
|
|
The enums for the parts of a recurarance rule and request statuses are irregular.
|
|
|
|
\layout Section
|
|
|
|
Useful Recipies
|
|
\layout Standard
|
|
|
|
Iteration
|
|
\layout Standard
|
|
|
|
Copying components.
|
|
Remember that you must clone or remove an object before putting in on anothr
|
|
list.
|
|
|
|
\layout Standard
|
|
|
|
Finding compliance errors
|
|
\layout Section
|
|
|
|
Performance
|
|
\layout Standard
|
|
|
|
Checking restrictions is computationally expensive
|
|
\layout Section
|
|
|
|
Hacks and Bugs
|
|
\the_end
|