diff options
Diffstat (limited to 'libical/doc/UsingLibical.lyx')
| -rw-r--r-- | libical/doc/UsingLibical.lyx | 1555 |
1 files changed, 0 insertions, 1555 deletions
diff --git a/libical/doc/UsingLibical.lyx b/libical/doc/UsingLibical.lyx deleted file mode 100644 index 868eac93b7..0000000000 --- a/libical/doc/UsingLibical.lyx +++ /dev/null @@ -1,1555 +0,0 @@ -#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 - -May 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. - -\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(strdup("guid-1.host1.com")) ); -\layout Code - -icalcomponent_add_property(event,prop); -\layout Code - -prop=icalproperty_new_organizer(strdup("mrbig@host.com")); -\layout Code - -param = icalparameter_new_role(ICAL_ROLE_CHAIR) -\layout Code - -icalproperty_add_parameter(prop, param); -\layout Code - -icalcomponent_add_property(event,prop); -\layout Standard - -While we are on this example, you should notice that libical uses a semi-object- -oriented style of interface. - Most things you work with are objects, that are instantiated with a constructor - that has -\begin_inset Quotes eld -\end_inset - -new -\begin_inset Quotes erd -\end_inset - - in the name. - Also note that, other than the object reference, most structure data is - passed in to libical routines by value. - Strings, of course, are passed in by reference, but libical will take ownership - of the memory, so you had beter strdup() the data unless you want a core - dump when the memory is freed for the second time. - Libical has some complex 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(strdup("2.0")), -\layout Verbatim - - icalproperty_new_prodid(strdup( -\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(strdup("guid-1.host1.com")), -\layout Verbatim - - icalproperty_vanew_organizer( -\layout Verbatim - - strdup("mrbig@host.com"), -\layout Verbatim - - icalparameter_new_role(ICAL_ROLE_CHAIR), -\layout Verbatim - - 0 -\layout Verbatim - - ), -\layout Verbatim - - icalproperty_vanew_attendee( -\layout Verbatim - - strdup("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(strdup( -\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 - -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 - -Getting Values -\layout Subsubsection - -Setting Values -\layout Subsubsection - -Getting Parameters -\layout Subsubsection - -Setting Parameters -\layout Subsubsection - -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 -\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 |