1850 lines
42 KiB
Plaintext
1850 lines
42 KiB
Plaintext
#LyX 1.1 created this file. For more info see http://www.lyx.org/
|
|
\lyxformat 2.16
|
|
\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
|
|
|
|
November 2000
|
|
\layout Standard
|
|
|
|
|
|
\begin_inset LatexCommand \tableofcontents{}
|
|
|
|
\end_inset
|
|
|
|
|
|
\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 RFC2445 and RFC2446.
|
|
Eventually, it will also implement iRIP and 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
|
|
|
|
Example Code
|
|
\layout Standard
|
|
|
|
A lot of the documentation for this library is in the form of example code.
|
|
These examples are in the
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
examples
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
directory of the distribution.
|
|
Also look in
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
src/test
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
for more annotated examples.
|
|
|
|
\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 under
|
|
gcc.
|
|
Some version have been successfully been build on MacOS, Solaris and UnixWare
|
|
without gcc, but you may run into problems with a particular later version.
|
|
|
|
\layout Standard
|
|
|
|
For a more complete guide to building the library, see the README file in
|
|
the distribution.
|
|
|
|
\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
|
|
When a component is sent across a network, if it is un-encrypted, it will
|
|
look something like:
|
|
\layout Verbatim
|
|
|
|
BEGIN:VEVENT
|
|
\layout Verbatim
|
|
|
|
DTSTAMP:19980309T231000Z
|
|
\layout Verbatim
|
|
|
|
UID:guid-1.host1.com
|
|
\layout Verbatim
|
|
|
|
ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com
|
|
\layout Verbatim
|
|
|
|
ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP:
|
|
\layout Verbatim
|
|
|
|
MAILTO:employee-A@host.com
|
|
\layout Verbatim
|
|
|
|
DESCRIPTION:Project XYZ Review Meeting
|
|
\layout Verbatim
|
|
|
|
CATEGORIES:MEETING
|
|
\layout Verbatim
|
|
|
|
CLASS:PUBLIC
|
|
\layout Verbatim
|
|
|
|
CREATED:19980309T130000Z
|
|
\layout Verbatim
|
|
|
|
SUMMARY:XYZ Project Review
|
|
\layout Verbatim
|
|
|
|
DTSTART;TZID=US-Eastern:19980312T083000
|
|
\layout Verbatim
|
|
|
|
DTEND;TZID=US-Eastern:19980312T093000
|
|
\layout Verbatim
|
|
|
|
LOCATION:1CP Conference Room 4350
|
|
\layout Verbatim
|
|
|
|
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("guid-1.host1.com") );
|
|
\layout Code
|
|
|
|
icalcomponent_add_property(event,prop);
|
|
\layout Code
|
|
|
|
prop=icalproperty_new_organizer("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.
|
|
Libical has some complex but 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 varargs.
|
|
The varargs constructor interface all you to create intricate components
|
|
in a single block of text.
|
|
|
|
\layout Verbatim
|
|
|
|
calendar =
|
|
\layout Verbatim
|
|
|
|
icalcomponent_vanew(
|
|
\layout Verbatim
|
|
|
|
ICAL_VCALENDAR_COMPONENT,
|
|
\layout Verbatim
|
|
|
|
icalproperty_new_version("2.0"),
|
|
\layout Verbatim
|
|
|
|
icalproperty_new_prodid(
|
|
\layout Verbatim
|
|
|
|
"-//RDU Software//NONSGML HandCal//EN"),
|
|
\layout Verbatim
|
|
|
|
icalcomponent_vanew(
|
|
\layout Verbatim
|
|
|
|
ICAL_VEVENT_COMPONENT,
|
|
\layout Verbatim
|
|
|
|
icalproperty_new_dtstamp(atime),
|
|
\layout Verbatim
|
|
|
|
icalproperty_new_uid("guid-1.host1.com"),
|
|
\layout Verbatim
|
|
|
|
icalproperty_vanew_organizer(
|
|
\layout Verbatim
|
|
|
|
"mrbig@host.com"),
|
|
\layout Verbatim
|
|
|
|
icalparameter_new_role(ICAL_ROLE_CHAIR),
|
|
\layout Verbatim
|
|
|
|
0
|
|
\layout Verbatim
|
|
|
|
),
|
|
\layout Verbatim
|
|
|
|
icalproperty_vanew_attendee(
|
|
\layout Verbatim
|
|
|
|
"employee-A@host.com",
|
|
\layout Verbatim
|
|
|
|
icalparameter_new_role(
|
|
\layout Verbatim
|
|
|
|
ICAL_ROLE_REQPARTICIPANT),
|
|
\layout Verbatim
|
|
|
|
icalparameter_new_rsvp(1),
|
|
\layout Verbatim
|
|
|
|
icalparameter_new_cutype(ICAL_CUTYPE_GROUP),
|
|
\layout Verbatim
|
|
|
|
0
|
|
\layout Verbatim
|
|
|
|
),
|
|
\layout Verbatim
|
|
|
|
icalproperty_new_location(
|
|
\layout Verbatim
|
|
|
|
"1CP Conference Room 4350"),
|
|
\layout Verbatim
|
|
|
|
0
|
|
\layout Verbatim
|
|
|
|
),
|
|
\layout Verbatim
|
|
|
|
0
|
|
\layout Verbatim
|
|
|
|
);
|
|
\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 by using:
|
|
\layout Verbatim
|
|
|
|
icalparser* icalparser_new();
|
|
\layout Verbatim
|
|
|
|
void icalparser_free(icalparser* parser);
|
|
\layout Verbatim
|
|
|
|
icalparser_get_line(parser,read_stream);
|
|
\layout Verbatim
|
|
|
|
icalparser_add_line(parser,line);
|
|
\layout Verbatim
|
|
|
|
icalparser_set_gen_data(parser,stream)
|
|
\layout Standard
|
|
|
|
These routines will construct a parser object to which you can add lines
|
|
of input and retrieve any components that the parser creates from the input.
|
|
For an example:
|
|
\layout Verbatim
|
|
|
|
char* read_stream(char *s, size_t size, void *d)
|
|
\layout Verbatim
|
|
|
|
{
|
|
\layout Verbatim
|
|
|
|
char *c = fgets(s,size, (FILE*)d);
|
|
\layout Verbatim
|
|
|
|
return c;
|
|
\layout Verbatim
|
|
|
|
}
|
|
\layout Verbatim
|
|
|
|
main() {
|
|
\layout Verbatim
|
|
|
|
char* line;
|
|
\layout Verbatim
|
|
|
|
icalcomponent *c;
|
|
\layout Verbatim
|
|
|
|
icalparser *parser = icalparser_new();
|
|
\layout Verbatim
|
|
|
|
FILE* stream = fopen(argv[1],"r");
|
|
\layout Verbatim
|
|
|
|
icalparser_set_gen_data(parser,stream);
|
|
\layout Verbatim
|
|
|
|
do{
|
|
\layout Verbatim
|
|
|
|
line = icalparser_get_line(parser,read_stream);
|
|
\layout Verbatim
|
|
|
|
c = icalparser_add_line(parser,line);
|
|
\layout Verbatim
|
|
|
|
if (c != 0){
|
|
\layout Verbatim
|
|
|
|
printf("%s",icalcomponent_as_ical_string(c));
|
|
\layout Verbatim
|
|
|
|
icalparser_claim(parser);
|
|
\layout Verbatim
|
|
|
|
printf("
|
|
\backslash
|
|
n---------------
|
|
\backslash
|
|
n");
|
|
\layout Verbatim
|
|
|
|
icalcomponent_free(c);
|
|
\layout Verbatim
|
|
|
|
}
|
|
\layout Verbatim
|
|
|
|
} while ( line != 0);
|
|
\layout Verbatim
|
|
|
|
}
|
|
\layout Standard
|
|
|
|
The parser object parameterizes the routine used to get input lines with
|
|
icalparser_set_gen_data() and
|
|
\emph on
|
|
|
|
\emph default
|
|
icalparser_get_line().
|
|
In this example, the routine read_stream() will fetch the next line from
|
|
a stream, with the stream passed in as the void* parameter d.
|
|
The parser calls read_stream() from icalparser_get_line(), but it also
|
|
needs to know what stream to use.
|
|
This is set by the call to icalparser_set_gen_data().
|
|
|
|
\layout Standard
|
|
|
|
Using the same mechanism, other implmentations could read from memory buffers,
|
|
sockets or other interfaces.
|
|
|
|
\layout Standard
|
|
|
|
Since the example code is a very common way to use the parser, there is
|
|
a convienience routine;
|
|
\layout Verbatim
|
|
|
|
icalcomponent* icalparser_parse(icalparser *parser,
|
|
\layout Verbatim
|
|
|
|
char* (*line_gen_func)(char *s, size_t sise, void* d))
|
|
\layout Standard
|
|
|
|
To use this routine, you still must construct the parser object and pass
|
|
in a reference to a line reading routine.
|
|
If the parser can create a single component from the input, it will return
|
|
a pointer to the newly constructed component.
|
|
If the parser can construct multiple cmponents from the input, it will
|
|
return a reference to an XROOT component ( of type ICAL_XROOT_COMPONENT.)
|
|
This XROOT component will hold all of the components constructed from the
|
|
input as children.
|
|
See section 6.2.2 for how to iterate through the child components.
|
|
|
|
\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.
|
|
Libical interface let you find sub-component, add and remove sub-components,
|
|
and do the same three operations on properties.
|
|
|
|
\layout Subsubsection
|
|
|
|
Finding Components
|
|
\layout Standard
|
|
|
|
To find a sub-component of a component, use:
|
|
\layout Verbatim
|
|
|
|
icalcomponent* icalcomponent_get_first_component(
|
|
\layout Verbatim
|
|
|
|
icalcomponent* component,
|
|
\layout Verbatim
|
|
|
|
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 Verbatim
|
|
|
|
ICAL_ANY_COMPONENT
|
|
\layout Verbatim
|
|
|
|
ICAL_VEVENT_COMPONENT
|
|
\layout Verbatim
|
|
|
|
ICAL_VTODO_COMPONENT
|
|
\layout Verbatim
|
|
|
|
ICAL_VJOURNAL_COMPONENT
|
|
\layout Verbatim
|
|
|
|
ICAL_VCALENDAR_COMPONENT
|
|
\layout Verbatim
|
|
|
|
ICAL_VFREEBUSY_COMPONENT
|
|
\layout Verbatim
|
|
|
|
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(
|
|
\layout Verbatim
|
|
|
|
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 Verbatim
|
|
|
|
for(c = icalcomponent_get_first_component(comp,ICAL_ANY_COMPONENT);
|
|
\layout Verbatim
|
|
|
|
c != 0;
|
|
\layout Verbatim
|
|
|
|
c = icalcomponent_get_next_component(comp,ICAL_ANY_COMPONENT))
|
|
\layout Verbatim
|
|
|
|
{
|
|
\layout Verbatim
|
|
|
|
do_something(c);
|
|
\layout Verbatim
|
|
|
|
}
|
|
\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
|
|
|
|
Using Component Iterators
|
|
\layout Standard
|
|
|
|
The iteration model in the previous section requires the component to keep
|
|
the state of the iteration.
|
|
So, you could not use this model to perform a sorting operations, since
|
|
you'd need two iterators and there is only space for one.
|
|
If you ever call icalcomponent_get_first_component() which an iteration
|
|
is in progress, the pointer will be reset to the beginning.
|
|
|
|
\layout Standard
|
|
|
|
To solve this problem, there are also external iterators for components.
|
|
The routines associated with these external iterators are:
|
|
\layout Verbatim
|
|
|
|
icalcompiter icalcomponent_begin_component(icalcomponent* component, icalcompone
|
|
nt_kind kind);
|
|
\layout Verbatim
|
|
|
|
icalcompiter icalcomponent_end_component(icalcomponent* component, icalcomponent
|
|
_kind kind);
|
|
\layout Verbatim
|
|
|
|
icalcomponent* icalcompiter_next(icalcompiter* i);
|
|
\layout Verbatim
|
|
|
|
icalcomponent* icalcompiter_prior(icalcompiter* i);
|
|
\layout Verbatim
|
|
|
|
icalcomponent* icalcompiter_deref(icalcompiter* i);
|
|
\layout Standard
|
|
|
|
The _begin_() and _end_() routines return a new iterator that points to
|
|
the begining and ending of the list of subcomponent for the given component,
|
|
and the kind argument works like the kind argument for internal iterators.
|
|
|
|
\layout Standard
|
|
|
|
After creating an iterators, use _next_() and _prior_() to step forward
|
|
and backward through the list and get the component that the iterator points
|
|
to, and use _deref() to return the component that the iterator points to
|
|
without moving the iterator.
|
|
All routines will return 0 when they move to point off the end of the list.
|
|
|
|
\layout Standard
|
|
|
|
Here is an example of a loop using these routines:
|
|
\layout Verbatim
|
|
|
|
for(
|
|
\layout Verbatim
|
|
|
|
i = icalcomponent_begin_component(impl->cluster,ICAL_ANY_COMPONENT);
|
|
|
|
\layout Verbatim
|
|
|
|
icalcompiter_deref(&i)!= 0;
|
|
\layout Verbatim
|
|
|
|
icalcompiter_next(&i)
|
|
\layout Verbatim
|
|
|
|
) {
|
|
\layout Verbatim
|
|
|
|
icalcomponent *this = icalcompiter_deref(&i);
|
|
\layout Verbatim
|
|
|
|
}
|
|
\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.
|
|
The _remove() routine will keep the iterator valid by moving it to the
|
|
next component, but in a normal loop, this will result in two advances
|
|
per iteration, and you will remove only every other component.
|
|
To avoid the problem, you will need to step the iterator ahead of the
|
|
element you are going to remove, like this:
|
|
\layout Verbatim
|
|
|
|
for(c = icalcomponent_get_first_component(parent_comp,ICAL_ANY_COMPONENT);
|
|
|
|
\layout Verbatim
|
|
|
|
c != 0;
|
|
\layout Verbatim
|
|
|
|
c = next
|
|
\layout Verbatim
|
|
|
|
{
|
|
\layout Verbatim
|
|
|
|
next = icalcomponent_get_next_component(parent_comp,ICAL_ANY_COMPONENT);
|
|
\layout Verbatim
|
|
|
|
icalcomponent_remove_component(parent_comp,c);
|
|
\layout Verbatim
|
|
|
|
}
|
|
\layout Standard
|
|
|
|
Another way to remove components is to rely on the side effect of icalcomponent_
|
|
remove_component: if component iterator in the parent component is pointing
|
|
to the child that will be removed, it will move the iterator to the component
|
|
after the child.
|
|
The following code will exploit this behavior:
|
|
\layout Verbatim
|
|
|
|
icalcomponent_get_first_component(parent_comp,ICAL_VEVENT_COMPONENT);
|
|
\layout Verbatim
|
|
|
|
while((c=icalcomponent_get_current_component(c)) != 0 ){
|
|
\layout Verbatim
|
|
|
|
if(icalcomponent_isa(c) == ICAL_VEVENT_COMPONENT){
|
|
\layout Verbatim
|
|
|
|
icalcomponent_remove_component(parent_comp,inner);
|
|
\layout Verbatim
|
|
|
|
} else {
|
|
\layout Verbatim
|
|
|
|
icalcomponent_get_next_component(parent_comp,ICAL_VEVENT_COMPONENT);
|
|
|
|
\layout Verbatim
|
|
|
|
}
|
|
\layout Verbatim
|
|
|
|
}
|
|
\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
|
|
|
|
icalcomponent* component,
|
|
\layout Verbatim
|
|
|
|
icalproperty_kind kind);
|
|
\layout Verbatim
|
|
|
|
icalproperty* icalcomponent_get_next_property(
|
|
\layout Verbatim
|
|
|
|
icalcomponent* component,
|
|
\layout Verbatim
|
|
|
|
icalproperty_kind kind);
|
|
\layout Verbatim
|
|
|
|
void icalcomponent_add_property(
|
|
\layout Verbatim
|
|
|
|
icalcomponent* component,
|
|
\layout Verbatim
|
|
|
|
icalproperty* property);
|
|
\layout Verbatim
|
|
|
|
void icalcomponent_remove_property(
|
|
\layout Verbatim
|
|
|
|
icalcomponent* component,
|
|
\layout Verbatim
|
|
|
|
icalproperty* property);
|
|
\layout Verbatim
|
|
|
|
icalparameter* icalproperty_get_first_parameter(
|
|
\layout Verbatim
|
|
|
|
icalproperty* prop,
|
|
\layout Verbatim
|
|
|
|
icalparameter_kind kind);
|
|
\layout Verbatim
|
|
|
|
icalparameter* icalproperty_get_next_parameter(
|
|
\layout Verbatim
|
|
|
|
icalproperty* prop,
|
|
\layout Verbatim
|
|
|
|
icalparameter_kind kind);
|
|
\layout Verbatim
|
|
|
|
void icalproperty_add_parameter(
|
|
\layout Verbatim
|
|
|
|
icalproperty* prop,
|
|
\layout Verbatim
|
|
|
|
icalparameter* parameter);
|
|
\layout Verbatim
|
|
|
|
void icalproperty_remove_parameter(
|
|
\layout Verbatim
|
|
|
|
icalproperty* prop,
|
|
\layout Verbatim
|
|
|
|
icalparameter_kind kind);
|
|
\layout Subsubsection
|
|
|
|
Working with values
|
|
\layout Standard
|
|
|
|
Values are typically part of a property, although they can exist on their
|
|
own.
|
|
You can maniplulate them either as part of the property or independantly.
|
|
\layout Standard
|
|
|
|
The most common way to work with values to is to maniplate them from they
|
|
properties that contain them.
|
|
This involves fewer routine calls and intermediate variables than working
|
|
with them independently, and it is type-safe.
|
|
|
|
\layout Standard
|
|
|
|
For each property, there are a _get_ and a _set_ routine that access the
|
|
internal value.
|
|
For instnace, for the UID property, the routines are:
|
|
\layout Verbatim
|
|
|
|
void icalproperty_set_uid(icalproperty* prop, const char* v)
|
|
\layout Verbatim
|
|
|
|
const char* icalproperty_get_uid(icalproperty* prop)
|
|
\layout Standard
|
|
|
|
For multivalued properties, like ATTACH, the value type is usually a struct
|
|
or union that holds both possible types.
|
|
|
|
\layout Standard
|
|
|
|
If you want to work with the underlying value object, you can get and set
|
|
it with:
|
|
\layout Verbatim
|
|
|
|
icalvalue* icalproperty_get_value (icalproperty* prop)
|
|
\layout Verbatim
|
|
|
|
void icalproperty_set_value(icalproperty* prop, icalvalue* value);
|
|
\layout Standard
|
|
|
|
Icalproperty_get_value() will return a reference that you can manipluate
|
|
with other icalvalue routines.
|
|
Most of the time, you will have to know what the type of the value is.
|
|
For instance, if you know that the value is a DATETIME type, you can manipluate
|
|
it with:
|
|
\layout Verbatim
|
|
|
|
struct icaltimetype icalvalue_get_datetime(icalvalue* value);
|
|
\layout Verbatim
|
|
|
|
void icalvalue_set_datetime(icalvalue* value, struct icaltimetype v);
|
|
\layout Standard
|
|
|
|
When working with an extension property or value (and X-PROPERTY or a property
|
|
that has the parameter VALUE=x-name ) the value type is always a string.
|
|
To get and set the value, use:
|
|
\layout Verbatim
|
|
|
|
void icalproperty_set_x(icalproperty* prop, char* v);
|
|
\layout Verbatim
|
|
|
|
char* icalproperty_get_x(icalproperty* prop);
|
|
\layout Subsubsection
|
|
|
|
Working with parameters
|
|
\layout Subsubsection
|
|
|
|
Checking Component Validity
|
|
\layout Standard
|
|
|
|
RFC 2446 defines rules for what properties must exist in a component to
|
|
be used for transfering scheduling data.
|
|
Most of these rules relate to the existence of properties relative to the
|
|
METHOD property, which declares what operation a remote reciever should
|
|
use to process a component.
|
|
For instance, if the METHOD is REQUEST and the component is a VEVENT, the
|
|
sender is probably asking the reciever to join in a meeting.
|
|
In this case, RFC2446 says that the component must specify a start time
|
|
(DTSTART) and list the reciever as an attendee (ATTENDEE).
|
|
|
|
\layout Standard
|
|
|
|
Libical can check these restrictions with the routine:
|
|
\layout Verbatim
|
|
|
|
int icalrestriction_check(icalcomponent* comp);
|
|
\layout Standard
|
|
|
|
This routine returns 0 if the component does not pass RFC2446 restrictions,
|
|
or if the component is malformed.
|
|
The component you pass in
|
|
\emph on
|
|
must
|
|
\emph default
|
|
be a VCALENDAR, with one or more children, like the examples in RFC2446.
|
|
|
|
\layout Standard
|
|
|
|
When this routine runs, it will insert new properties into the component
|
|
to indicate any errors it finds.
|
|
See section 6.5.3, X-LIC-ERROR for more information about these error properties.
|
|
|
|
\layout Subsubsection
|
|
|
|
Converting Components to Text
|
|
\layout Standard
|
|
|
|
To create an RFC2445 compliant text representtion of an object, use one
|
|
of the *_as_ical_string() routines:
|
|
\layout Verbatim
|
|
|
|
char* icalcomponent_as_ical_string (icalcomponent* component)
|
|
\layout Verbatim
|
|
|
|
char* icalproperty_as_ical_string (icalproperty* property)
|
|
\layout Verbatim
|
|
|
|
char* icalparameter_as_ical_string (icalparameter* parameter)
|
|
\layout Verbatim
|
|
|
|
char* icalvalue_as_ical_string (icalvalue* value)
|
|
\layout Standard
|
|
|
|
In most cases, you will only use icalcomponent_as_ical_string (), since
|
|
it will cascade and convert all of the parameters, properties and values
|
|
that are attached to the root component.
|
|
\layout Standard
|
|
|
|
Icalproperty_as_ical_string() will terminate each line with the RFC2445
|
|
specified line terminator
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
|
|
\backslash
|
|
r
|
|
\backslash
|
|
n
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
However, if you compile with the symbol ICAL_UNIX_NEWLINE defined, it will
|
|
terminate lines with
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
|
|
\backslash
|
|
n
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
|
|
\layout Standard
|
|
|
|
Remember that the string returned by these routines is owned by the library,
|
|
and will eventually be re-written.
|
|
You should copy it if you want to preserve it.
|
|
|
|
\layout Subsection
|
|
|
|
Time
|
|
\layout Subsubsection
|
|
|
|
Time structure
|
|
\layout Standard
|
|
|
|
LIbical defines it's own time structure for storing all dates and times.
|
|
It would have been nice to re-use the C library's
|
|
\emph on
|
|
struct tm,
|
|
\emph default
|
|
but that structure does not differentiate between dates and times, and between
|
|
local time and UTC.
|
|
The libical structure is:
|
|
\layout Verbatim
|
|
|
|
struct icaltimetype {
|
|
\layout Verbatim
|
|
|
|
int year;
|
|
\layout Verbatim
|
|
|
|
int month;
|
|
\layout Verbatim
|
|
|
|
int day;
|
|
\layout Verbatim
|
|
|
|
int hour;
|
|
\layout Verbatim
|
|
|
|
int minute;
|
|
\layout Verbatim
|
|
|
|
int second;
|
|
\layout Verbatim
|
|
|
|
int is_utc; /* 1-> time is in UTC timezone */
|
|
\layout Verbatim
|
|
|
|
int is_date; /* 1 -> interpret this as date.
|
|
*/ };
|
|
\layout Standard
|
|
|
|
The year, month, day, hour, minute and second fields how the broken-out
|
|
time values.
|
|
The is_utc field distinguishes between times UTC and a local time zone.
|
|
The is_date field indicates if the intra-day fields hold valid data.
|
|
|
|
\layout Subsubsection
|
|
|
|
Time manipulating routines
|
|
\layout Standard
|
|
|
|
The null time value is used to indicate that the data in the structure is
|
|
not a valid time.
|
|
\layout Verbatim
|
|
|
|
struct icaltimetype icaltime_null_time(void);
|
|
\layout Verbatim
|
|
|
|
int icaltime_is_null_time(struct icaltimetype t);
|
|
\layout Standard
|
|
|
|
It is sensible for the broken-out time fields to contain values that are
|
|
not permitted in an ISO compliant time string.
|
|
For instance, the seconds field can hold values greater than 59, and the
|
|
hours field can hold values larger than 24.
|
|
The excessive values will be rolled over into the next larger field when
|
|
the structure is normalized.
|
|
|
|
\layout Verbatim
|
|
|
|
struct icaltimetype icaltime_normalize(struct icaltimetype t);
|
|
\layout Standard
|
|
|
|
There are several routines to get the day of the week or month, etc, from
|
|
a time structure.
|
|
\layout Verbatim
|
|
|
|
short icaltime_day_of_year(struct icaltimetype t);
|
|
\layout Verbatim
|
|
|
|
struct icaltimetype icaltime_from_day_of_year(short doy, short year);
|
|
\layout Verbatim
|
|
|
|
short icaltime_day_of_week(struct icaltimetype t);
|
|
\layout Verbatim
|
|
|
|
short icaltime_start_doy_of_week(struct icaltimetype t);
|
|
\layout Verbatim
|
|
|
|
short icaltime_week_number(short day_of_month, short month, short year);
|
|
\layout Verbatim
|
|
|
|
struct icaltimetype icaltime_from_week_number(short week_number, short year);
|
|
\layout Verbatim
|
|
|
|
short icaltime_days_in_month(short month,short year);
|
|
\layout Standard
|
|
|
|
Two routines convert time structures to and from the number of seconds since
|
|
the POSIX epoch.
|
|
The is_date field indicates wether or not the hour, minute and second fields
|
|
should be used in the conversion, and is_utc indicates if the value should
|
|
be converted to a local time or a UTC time, using the operating system
|
|
suppled notion of the local timezone.
|
|
|
|
\layout Verbatim
|
|
|
|
struct icaltimetype icaltime_from_timet(time_t v, int is_date, int is_utc);
|
|
|
|
\layout Verbatim
|
|
|
|
time_t icaltime_as_timet(struct icaltimetype);
|
|
\layout Standard
|
|
|
|
The compare routine works exactly like strcmp, but on time structures.
|
|
|
|
\layout Verbatim
|
|
|
|
int icaltime_compare(struct icaltimetype a,struct icaltimetype b);
|
|
\layout Standard
|
|
|
|
The following routines convert between UTC and a named timezone.
|
|
The tzid field must be a timezone name from the Olsen database, such as
|
|
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
America/Los_Angeles.
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
|
|
\layout Standard
|
|
|
|
The utc_offset routine returns the offset of the named time zone from UTC,
|
|
in seconds.
|
|
|
|
\layout Standard
|
|
|
|
The tt parmeter in the fonllowing routines indicates the date on which the
|
|
conversion should be made.
|
|
The tt parameter is necessary because timezones have many different rules
|
|
for when daylight savings time is used, and these rules can change over
|
|
time.
|
|
So, for a single timezone one year may have daylight savings time on March
|
|
15, but for other years March 15 may be standard time, and some years may
|
|
have standard time all year.
|
|
|
|
\layout Verbatim
|
|
|
|
int icaltime_utc_offset(struct icaltimetype tt, char* tzid)
|
|
\layout Verbatim
|
|
|
|
struct icaltimetype icaltime_as_utc(struct icaltimetype tt,char* tzid);
|
|
\layout Verbatim
|
|
|
|
struct icaltimetype icaltime_as_zone(struct icaltimetype tt,char* tzid);
|
|
\layout Verbatim
|
|
|
|
\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.
|
|
( & currently, not at all.
|
|
)
|
|
\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
|
|
|
|
Libical has several error handling mechanisms for the varioustypes of programmin
|
|
g, semantic and syntactic errors you may encounter.
|
|
\layout Subsubsection
|
|
|
|
Return values
|
|
\layout Standard
|
|
|
|
Many library routines signal errors through their return values.
|
|
All routines that return a pointer, such as icalcomponent_new(), will return
|
|
0 ( zero ) on a fatal error.
|
|
Some routines will return a value of enum icalerrorenum.
|
|
|
|
\layout Subsubsection
|
|
|
|
icalerrno
|
|
\layout Standard
|
|
|
|
Most routines will set the global error value icalerrno on errors.
|
|
This variable is an enumeration; permissable values can be found in libical/ica
|
|
lerror.h.
|
|
If the routine returns an enum icalerrorenum, then the return value will
|
|
be the same as icalerrno.
|
|
You can use icalerror_strerror() to get a string that describes the error
|
|
\layout Subsubsection
|
|
|
|
X-LIC-ERROR and X-LIC-INVALID-COMPONENT
|
|
\layout Standard
|
|
|
|
The library handles semantic and syntactic errors in components by inserting
|
|
errors properties into the components.
|
|
If the parser cannot parse incoming text ( a syntactic error ) or if the
|
|
icalrestriction_check() routine indicates that the component does not meet
|
|
the requirments of RFC2446 ( a semantic error) the library will insert
|
|
properties of the type X-LIC-ERROR to describe the error.
|
|
Here is an example of the error property:
|
|
\layout Verbatim
|
|
|
|
X-LIC-ERROR;X-LIC-ERRORTYPE=INVALID_ITIP :Failed iTIP restrictions for property
|
|
DTSTART.
|
|
Expected 1 instances of the property and got 0
|
|
\layout Standard
|
|
|
|
This error resulted from a call to icalrestriction_check(), which discovered
|
|
that the component does not have a DTSTART property, as required by RFC2445.
|
|
|
|
\layout Standard
|
|
|
|
There are a few routines to manipulate error properties:
|
|
\layout Standard
|
|
\LyXTable
|
|
multicol5
|
|
10 2 0 0 -1 -1 -1 -1
|
|
1 1 0 0
|
|
1 0 0 0
|
|
0 1 1 0
|
|
1 0 0 0
|
|
0 1 1 0
|
|
1 1 0 0
|
|
0 1 1 0
|
|
1 1 0 0
|
|
0 1 1 0
|
|
0 1 1 0
|
|
2 1 0 "" ""
|
|
2 1 1 "3in" ""
|
|
0 2 1 1 0 0 0 "" ""
|
|
0 8 1 0 0 0 0 "" ""
|
|
0 2 1 0 0 0 0 "" ""
|
|
0 2 1 0 1 0 1 "" ""
|
|
0 2 1 0 0 0 0 "" ""
|
|
0 2 1 0 0 0 1 "" ""
|
|
0 2 1 0 0 0 0 "" ""
|
|
0 2 1 0 1 0 0 "" ""
|
|
0 2 1 0 0 0 0 "" ""
|
|
0 2 1 0 0 0 0 "" ""
|
|
0 2 1 0 0 0 0 "" ""
|
|
0 2 1 0 1 0 0 "" ""
|
|
0 2 1 0 0 0 0 "" ""
|
|
0 2 1 0 0 0 0 "" ""
|
|
0 2 1 0 0 0 0 "" ""
|
|
0 2 1 1 1 0 1 "" ""
|
|
0 2 1 0 0 0 0 "" ""
|
|
0 2 1 1 1 0 1 "" ""
|
|
0 2 1 0 0 0 0 "" ""
|
|
0 2 1 1 0 0 1 "" ""
|
|
|
|
Routine
|
|
\newline
|
|
Purpose
|
|
\newline
|
|
void icalrestriction_check()
|
|
\newline
|
|
Check a component against RFC2446 and insert
|
|
\newline
|
|
|
|
\newline
|
|
error properties to indicate non compliance
|
|
\newline
|
|
int icalcomponent_count_errors()
|
|
\newline
|
|
Return the number of error properties
|
|
\newline
|
|
|
|
\newline
|
|
in a component
|
|
\newline
|
|
void icalcomponent_strip_errors()
|
|
\newline
|
|
Remove all error properties in as
|
|
\newline
|
|
|
|
\newline
|
|
component
|
|
\newline
|
|
void icalcomponent_convert_errors()
|
|
\newline
|
|
Convert some error properties into
|
|
\newline
|
|
|
|
\newline
|
|
REQUESTS-STATUS to indicate the inability to
|
|
\newline
|
|
|
|
\newline
|
|
process the component as an iTIP request.
|
|
|
|
\layout Standard
|
|
|
|
The types of errors are listed in icalerror.h.
|
|
They are:
|
|
\layout Verbatim
|
|
|
|
ICAL_XLICERRORTYPE_COMPONENTPARSEERROR
|
|
\layout Verbatim
|
|
|
|
ICAL_XLICERRORTYPE_PARAMETERVALUEPARSEERROR
|
|
\layout Verbatim
|
|
|
|
ICAL_XLICERRORTYPE_PARAMETERNAMEPARSEERROR
|
|
\layout Verbatim
|
|
|
|
ICAL_XLICERRORTYPE_PROPERTYPARSEERROR
|
|
\layout Verbatim
|
|
|
|
ICAL_XLICERRORTYPE_VALUEPARSEERROR
|
|
\layout Verbatim
|
|
|
|
ICAL_XLICERRORTYPE_UNKVCALPROP
|
|
\layout Verbatim
|
|
|
|
ICAL_XLICERRORTYPE_INVALIDITIP
|
|
\layout Standard
|
|
|
|
The libical parser will generate the error that end in PARSEERROR when it
|
|
encounters garbage in the input steam.
|
|
ICAL_XLICERRORTYPE_INVALIDITIP is inserted by icalrestriction_check(),
|
|
and ICAL_XLICERRORTYPE_UNKVCALPROP is generated by icalvcal_convert() when
|
|
it encounters a vCal property that it cannot convert or does not know about.
|
|
|
|
\layout Standard
|
|
|
|
Icalcomponent_convert_errors() converts some of the error properties ina
|
|
component into REQUEST-STATUS properties that indicate a failure.
|
|
As of libical version0.18, this routine only convert *PARSEERROR errors
|
|
and it always generates a 3.x ( failure ) code.
|
|
This makes it more of a good idea than a really useful bit of code.
|
|
|
|
\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
|
|
\layout Standard
|
|
|
|
There are a lot of hacks in the library -- bits of code that I am not proud
|
|
of and should propbably be changed.
|
|
These are marked with the comment string
|
|
\begin_inset Quotes eld
|
|
\end_inset
|
|
|
|
HACK.
|
|
\begin_inset Quotes erd
|
|
\end_inset
|
|
|
|
|
|
\the_end
|