From 73a6d43a66a828b09e2c1b5a483405e6e0b5fa6a Mon Sep 17 00:00:00 2001 From: JP Rosevear Date: Thu, 24 Aug 2000 20:12:06 +0000 Subject: Fix minor conflicts. svn path=/trunk/; revision=5017 --- libical/doc/UsingLibical.lyx | 1957 ++++++++++++++---------------------------- 1 file changed, 628 insertions(+), 1329 deletions(-) (limited to 'libical/doc/UsingLibical.lyx') diff --git a/libical/doc/UsingLibical.lyx b/libical/doc/UsingLibical.lyx index 1742e3af00..868eac93b7 100644 --- a/libical/doc/UsingLibical.lyx +++ b/libical/doc/UsingLibical.lyx @@ -1,6 +1,5 @@ -#This file was created by Sat Feb 19 10:33:21 2000 -#LyX 1.0 (C) 1995-1999 Matthias Ettrich and the LyX Team -\lyxformat 2.15 +#LyX 1.1 created this file. For more info see http://www.lyx.org/ +\lyxformat 2.16 \textclass linuxdoc \language default \inputencoding default @@ -31,7 +30,15 @@ Using Libical Eric Busboom (eric@softwarestudio.org) \layout Date -January 2000 +May 2000 +\layout Standard + + +\begin_inset LatexCommand \tableofcontents{} + +\end_inset + + \layout Section Introduction @@ -45,52 +52,9 @@ Libical is an Open Source implementation of the iCalendar protocols and \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. - ) +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 @@ -140,13 +104,29 @@ This dual license ensures that the library can be incorporated into both dual-licensed. \layout Subsection -Purpose & Goals -\layout Subsection +Example Code +\layout Standard -Document version -\layout Verbatim +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 -$Id: UsingLibical.lyx,v 1.5 2000/06/06 22:48:07 alves Exp $ + for more annotated examples. + \layout Section Building the Library @@ -214,65 +194,51 @@ 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 +When a component is sent across a network, if it is un-encrypted, it will look something like: -\layout Code +\layout Verbatim BEGIN:VEVENT -\layout Code +\layout Verbatim DTSTAMP:19980309T231000Z -\layout Code +\layout Verbatim UID:guid-1.host1.com -\layout Code +\layout Verbatim ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com -\layout Code +\layout Verbatim ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP: -\layout Code - +\layout Verbatim -\protected_separator - MAILTO:employee-A@host.com -\layout Code + MAILTO:employee-A@host.com +\layout Verbatim DESCRIPTION:Project XYZ Review Meeting -\layout Code +\layout Verbatim CATEGORIES:MEETING -\layout Code +\layout Verbatim CLASS:PUBLIC -\layout Code +\layout Verbatim CREATED:19980309T130000Z -\layout Code +\layout Verbatim SUMMARY:XYZ Project Review -\layout Code +\layout Verbatim DTSTART;TZID=US-Eastern:19980312T083000 -\layout Code +\layout Verbatim DTEND;TZID=US-Eastern:19980312T093000 -\layout Code +\layout Verbatim LOCATION:1CP Conference Room 4350 -\layout Code +\layout Verbatim END:VEVENT \layout Subsection @@ -556,7 +522,7 @@ new 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. + Libical has some complex but very regular memory handling rules. These are detailed in section \begin_inset LatexCommand \ref{sec:memory} @@ -578,1189 +544,366 @@ 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 + 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 Code +\layout Verbatim + calendar = +\layout Verbatim -\protected_separator + icalcomponent_vanew( +\layout Verbatim -\protected_separator + ICAL_VCALENDAR_COMPONENT, +\layout Verbatim -\protected_separator - calendar = -\layout Code + icalproperty_new_version(strdup("2.0")), +\layout Verbatim + icalproperty_new_prodid(strdup( +\layout Verbatim -\protected_separator + "-//RDU Software//NONSGML HandCal//EN")), +\layout Verbatim -\protected_separator + icalcomponent_vanew( +\layout Verbatim -\protected_separator + ICAL_VEVENT_COMPONENT, +\layout Verbatim -\protected_separator + icalproperty_new_dtstamp(atime), +\layout Verbatim -\protected_separator + icalproperty_new_uid(strdup("guid-1.host1.com")), +\layout Verbatim -\protected_separator + icalproperty_vanew_organizer( +\layout Verbatim -\protected_separator + strdup("mrbig@host.com"), +\layout Verbatim -\protected_separator -icalcomponent_vanew( -\layout Code + icalparameter_new_role(ICAL_ROLE_CHAIR), +\layout Verbatim + 0 +\layout Verbatim -\protected_separator + ), +\layout Verbatim -\protected_separator + icalproperty_vanew_attendee( +\layout Verbatim -\protected_separator + strdup("employee-A@host.com"), +\layout Verbatim -\protected_separator + icalparameter_new_role( +\layout Verbatim -\protected_separator + ICAL_ROLE_REQPARTICIPANT), +\layout Verbatim -\protected_separator + icalparameter_new_rsvp(1), +\layout Verbatim -\protected_separator + icalparameter_new_cutype(ICAL_CUTYPE_GROUP), +\layout Verbatim -\protected_separator + 0 +\layout Verbatim -\protected_separator + ), +\layout Verbatim -\protected_separator + icalproperty_new_location(strdup( +\layout Verbatim -\protected_separator - ICAL_VCALENDAR_COMPONENT, -\layout Code + "1CP Conference Room 4350")), +\layout Verbatim + 0 +\layout Verbatim -\protected_separator + ), +\layout Verbatim -\protected_separator + 0 +\layout Verbatim -\protected_separator + ); +\layout Standard -\protected_separator +This form is similar to the regular constructor, except that they have +\begin_inset Quotes eld +\end_inset -\protected_separator +vanew +\begin_inset Quotes erd +\end_inset -\protected_separator + instead of +\begin_inset Quotes eld +\end_inset -\protected_separator +new +\begin_inset Quotes erd +\end_inset -\protected_separator + 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 -\protected_separator +Parsing Text Files +\layout Standard -\protected_separator +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 -\protected_separator - icalproperty_new_version(strdup("2.0")), -\layout Code +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 -\protected_separator +icalparser* icalparser_new(); +\layout Verbatim -\protected_separator +void icalparser_free(icalparser* parser); +\layout Verbatim -\protected_separator +icalparser_get_line(parser,read_stream); +\layout Verbatim -\protected_separator +icalparser_add_line(parser,line); +\layout Verbatim -\protected_separator +icalparser_set_gen_data(parser,stream) +\layout Standard -\protected_separator +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 -\protected_separator +char* read_stream(char *s, size_t size, void *d) +\layout Verbatim -\protected_separator +{ +\layout Verbatim -\protected_separator + char *c = fgets(s,size, (FILE*)d); +\layout Verbatim -\protected_separator + return c; +\layout Verbatim -\protected_separator - icalproperty_new_prodid(strdup("-//RDU Software//NONSGML HandCal//EN")), -\layout Code +} +\layout Verbatim +main() { +\layout Verbatim -\protected_separator + char* line; +\layout Verbatim -\protected_separator + icalcomponent *c; +\layout Verbatim -\protected_separator + icalparser *parser = icalparser_new(); +\layout Verbatim -\protected_separator + FILE* stream = fopen(argv[1],"r"); +\layout Verbatim -\protected_separator + icalparser_set_gen_data(parser,stream); +\layout Verbatim -\protected_separator + do{ +\layout Verbatim -\protected_separator + line = icalparser_get_line(parser,read_stream); +\layout Verbatim -\protected_separator + c = icalparser_add_line(parser,line); +\layout Verbatim -\protected_separator + if (c != 0){ +\layout Verbatim -\protected_separator + printf("%s",icalcomponent_as_ical_string(c)); +\layout Verbatim -\protected_separator - icalcomponent_vanew( -\layout Code + icalparser_claim(parser); +\layout Verbatim + printf(" +\backslash +n--------------- +\backslash +n"); +\layout Verbatim -\protected_separator + icalcomponent_free(c); +\layout Verbatim -\protected_separator + } +\layout Verbatim -\protected_separator + } while ( line != 0); +\layout Verbatim -\protected_separator +} +\layout Standard -\protected_separator +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 -\protected_separator +Using the same mechanism, other implmentations could read from memory buffers, + sockets or other interfaces. + +\layout Standard -\protected_separator +Since the example code is a very common way to use the parser, there is + a convienience routine; +\layout Verbatim -\protected_separator +icalcomponent* icalparser_parse(icalparser *parser, +\layout Verbatim -\protected_separator + char* (*line_gen_func)(char *s, size_t sise, void* d)) +\layout Standard -\protected_separator +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 -\protected_separator +Accessing Components +\layout Standard -\protected_separator +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 -\protected_separator +Finding Components +\layout Standard -\protected_separator +To find a sub-component of a component, use: +\layout Verbatim -\protected_separator +icalcomponent* icalcomponent_get_first_component( +\layout Verbatim -\protected_separator -ICAL_VEVENT_COMPONENT, -\layout Code + icalcomponent* component, +\layout Verbatim + icalcomponent_kind kind); +\layout Standard -\protected_separator +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 -\protected_separator +ICAL_ANY_COMPONENT +\layout Verbatim -\protected_separator +ICAL_VEVENT_COMPONENT +\layout Verbatim -\protected_separator +ICAL_VTODO_COMPONENT +\layout Verbatim -\protected_separator +ICAL_VJOURNAL_COMPONENT +\layout Verbatim -\protected_separator +ICAL_VCALENDAR_COMPONENT +\layout Verbatim -\protected_separator +ICAL_VFREEBUSY_COMPONENT +\layout Verbatim -\protected_separator +ICAL_VALARM_COMPONENT +\layout Standard -\protected_separator +These are only the most common components; there are many more listed in + icalenums.h. +\layout Standard -\protected_separator +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 -\protected_separator +Interating Through Components +\layout Standard -\protected_separator +Iteration requires a second routine to get the next subcomponent after the + first: +\layout Verbatim -\protected_separator +icalcomponent* icalcomponent_get_next_component( +\layout Verbatim -\protected_separator + icalcomponent* component, +\layout Verbatim -\protected_separator + icalcomponent_kind kind); +\layout Standard -\protected_separator -icalproperty_new_dtstamp(atime), -\layout Code +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 -\protected_separator + c != 0; +\layout Verbatim -\protected_separator + c = icalcomponent_get_next_component(comp,ICAL_ANY_COMPONENT)) +\layout Verbatim -\protected_separator +{ +\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 -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, - + do_something(c); \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 @@ -1777,62 +920,63 @@ Libical component have internal iterators, so you can only have one iteration 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 + 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 Code - - -\protected_separator +\layout Verbatim -\protected_separator + c != 0; +\layout Verbatim -\protected_separator + c = next +\layout Verbatim -\protected_separator +{ +\layout Verbatim -\protected_separator + next = icalcomponent_get_next_component(parent_comp,ICAL_ANY_COMPONENT); +\layout Verbatim -\protected_separator + icalcomponent_remove_component(parent_comp,c); +\layout Verbatim -\protected_separator -c != 0; -\layout Code +} +\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 -\protected_separator - -\protected_separator - -\protected_separator - -\protected_separator -c = next -\layout Code +icalcomponent_get_first_component(parent_comp,ICAL_VEVENT_COMPONENT); +\layout Verbatim -{ -\protected_separator - -\protected_separator - -\layout Code +while((c=icalcomponent_get_current_component(c)) != 0 ){ +\layout Verbatim + if(icalcomponent_isa(c) == ICAL_VEVENT_COMPONENT){ +\layout Verbatim -\protected_separator -next = icalcomponent_get_next_component(parent_comp,ICAL_ANY_COMPONENT); -\layout Code + icalcomponent_remove_component(parent_comp,inner); +\layout Verbatim + } else { +\layout Verbatim -\protected_separator + icalcomponent_get_next_component(parent_comp,ICAL_VEVENT_COMPONENT); -\protected_separator - icalcomponent_remove_component(parent_comp,c); -\layout Code +\layout Verbatim + + } +\layout Verbatim } \layout Subsubsection @@ -1848,169 +992,73 @@ Finding, iterating and removing properties works the same as it does for icalproperty* icalcomponent_get_first_property( \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalcomponent* component, + icalcomponent* component, \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalproperty_kind kind); + icalproperty_kind kind); \layout Verbatim icalproperty* icalcomponent_get_next_property( \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalcomponent* component, + icalcomponent* component, \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalproperty_kind kind); + icalproperty_kind kind); \layout Verbatim void icalcomponent_add_property( \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalcomponent* component, + icalcomponent* component, \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalproperty* property); + icalproperty* property); \layout Verbatim void icalcomponent_remove_property( \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalcomponent* component, + icalcomponent* component, \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalproperty* property); + icalproperty* property); \layout Verbatim icalparameter* icalproperty_get_first_parameter( \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalproperty* prop, + icalproperty* prop, \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalparameter_kind kind); + icalparameter_kind kind); \layout Verbatim icalparameter* icalproperty_get_next_parameter( \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalproperty* prop, + icalproperty* prop, \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalparameter_kind kind); + icalparameter_kind kind); \layout Verbatim void icalproperty_add_parameter( \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalproperty* prop, + icalproperty* prop, \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalparameter* parameter); + icalparameter* parameter); \layout Verbatim void icalproperty_remove_parameter( \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalproperty* prop, + icalproperty* prop, \layout Verbatim - -\protected_separator - -\protected_separator - -\protected_separator -icalparameter_kind kind); + icalparameter_kind kind); \layout Subsubsection Getting Values @@ -2029,6 +1077,97 @@ Removing 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. + I 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 Storing Objects @@ -2037,7 +1176,8 @@ Storing Objects 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 @@ -2089,26 +1229,172 @@ Libical relies heavily on dynamic allocation for both the core objects and Error Handling \layout Standard -icalerror_errno. - Return values. - #defines. - icalerror_stop_here. - X-LIC-ERROR +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 Subsubsection +\layout Standard -Component errors +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 -icalerror_stop_here -\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 -X-LIC-ERROR +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 @@ -2249,8 +1535,21 @@ Finding compliance errors Performance \layout Standard -Checking restrictions is computationally expensive +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 -- cgit v1.2.3