summaryrefslogtreecommitdiffstats
path: root/libkcal/libical/doc/UsingLibical.txt
diff options
context:
space:
mode:
Diffstat (limited to 'libkcal/libical/doc/UsingLibical.txt')
-rw-r--r--libkcal/libical/doc/UsingLibical.txt1384
1 files changed, 1384 insertions, 0 deletions
diff --git a/libkcal/libical/doc/UsingLibical.txt b/libkcal/libical/doc/UsingLibical.txt
new file mode 100644
index 000000000..6b203d43d
--- /dev/null
+++ b/libkcal/libical/doc/UsingLibical.txt
@@ -0,0 +1,1384 @@
+
+
+Using Libical
+
+Eric Busboom (eric@softwarestudio.org)
+
+January 2001
+
+
+
+1 Introduction
+
+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 so users can
+store their calendar data and arrange meetings with other users.
+
+Libical implements RFC2445, RFC2446 and some of RFC2447 and the CAP
+draft.
+
+This documentation assumes that you are familiar with the iCalendar
+standards RFC2445 and RFC2446. these specifications are online on
+the CALSCH webpage at:
+
+http://www.imc.org/ietf-calendar/
+
+1.1 The libical project
+
+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
+
+http://softwarestudio.org/libical/index.html
+
+and a mailing list that you can join by sending the following mail:
+
+To: minimalist@softwarestudio.org
+
+Subject: subscribe libical
+
+1.2 License
+
+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.
+
+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.
+
+1.3 Example Code
+
+A lot of the documentation for this library is in the form of example
+code. These examples are in the "examples" directory of the distribution.
+Also look in "src/test" for additional annotated examples.
+
+2 Building the Library
+
+Libical uses autoconf to generate makefiles. It should built with no
+adjustments on Linux, FreeBSD and Solaris under gcc. Some version
+have been successfully been build on MacOS, Solaris, UnixWare, And
+Tru64 UNIX without gcc, but you may run into problems with a particular
+later version.
+
+For a more complete guide to building the library, see the README file
+in the distribution.
+
+3 Structure
+
+The iCal calendar model is based on four types of objects: components,
+properties, values and parameters.
+
+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
+
+ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com
+
+The property name is "ORGANIZER," the value of the property is "mrbig@host.com"
+and the "ROLE" parameter specifies that Mr Big is the chair of the
+meetings associated with this property.
+
+Components are groups of properties that represent the core objects
+of a calendar system, such as events or timezones. Components are
+delimited by "BEGIN" and "END" tags.
+
+When a component is sent across a network, if it is un-encrypted, it
+will look something like:
+
+BEGIN:VCALENDAR
+
+METHOD:REQUEST
+
+PRODID: -//hacksw/handcal//NONSGML v1.0//EN
+
+BEGIN:VEVENT
+
+DTSTAMP:19980309T231000Z
+
+UID:guid-1.host1.com
+
+ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com
+
+ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP:
+
+ MAILTO:employee-A@host.com
+
+DESCRIPTION:Project XYZ Review Meeting
+
+CATEGORIES:MEETING
+
+CLASS:PUBLIC
+
+CREATED:19980309T130000Z
+
+SUMMARY:XYZ Project Review
+
+DTSTART;TZID=US-Eastern:19980312T083000
+
+DTEND;TZID=US-Eastern:19980312T093000
+
+LOCATION:1CP Conference Room 4350
+
+END:VEVENT
+
+END:VCALENDAR
+
+Note that components can be nested; this example has both a VCALENDAR
+and a VEVENT component, one nested inside the other.
+
+3.1 Core iCal classes
+
+Libical is an object-based, data-oriented library. Nearly all of the
+routines in the library are associated with an opaque data types and
+perform some operation on that data type. Although the library does
+not actually have classes, we will use those terms since the behavior
+of these associations of data and routines is very similar to a class.
+
+3.1.1 Properties
+
+Properties are represented with the icalproperty class and its many
+"derived" classes with on "derived" class per property type in RFC2445.
+Again, there is no actual inheritance relations, but there are clusters
+of routines that make this term useful. A property is a container
+for a single value and a set of parameters.
+
+3.1.2 Components
+
+In libical, components are represented with the icalcomponent class.
+Icalcomponent is a container for a set of other components and properties.
+
+3.1.3 Values
+
+Values are represented in a similar way to properties; a base class
+and many "derived " classes. A value is essentially a abstract handle
+on a single fundamental type, a structure or a union.
+
+3.1.4 Parameters
+
+Parameters are represetned in a similar way to properties, except that
+they contain only one value
+
+3.2 Other elements of libical
+
+In addition to the core iCal classes, libical has many other types,
+structures, classes that aid in creating and using iCal components.
+
+3.2.1 Enumerations and types
+
+Libical is strongly typed, soo every component, property, parameter,
+and value type has an enumeration, and some have an associated structure
+or union.
+
+3.2.2 The parser
+
+The libical parser offers a variety of ways to convert RFC2445 text
+into a libical iinsteral component structure. the parser can parse
+blocks of text as a string, or it can parse lin-by-line.
+
+3.2.3 Error objects
+
+Libical has a substantial error reporting system for both programming
+errors and component usage errors.
+
+3.2.4 Memory Management
+
+Since many of libicals interfaces return strings, the library has its
+own memory management system to elimiate the need to free every string
+returned from the libraru.
+
+3.2.5 Storage classes
+
+The library also offers several classes to store components to flies,
+memory or databases.
+
+4 Differences From RFCs
+
+Libical has been designed to follow the standards as closely as possible,
+so that the key objects in the standards are also key 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.
+
+4.1 Pseudo Components
+
+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:DAYLIGHT" and ends with "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 "V," while pseudo
+components start with"X."
+
+There are also pseudo components that are conceptually derived classes
+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.
+
+For instance, if a VALARM component has an ACTION property with the
+value of "AUDIO," the component must also have an "ATTACH" property.
+However, if the ACTION value is "DISPLAY," the component must have
+a DESCRIPTION property.
+
+To handle these various, complex restrictions, libical has pseudo components
+for each type of alarm: XAUDIOALARM, XDISPLAYALARM, XEMAILALARM and
+XPROCEDUREALARM.
+
+4.2 Combined Values
+
+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.
+
+It is natural to have interfaces that would return the value of a property,
+but it is cumbersome 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 struct icaltriggertype.
+This type is a union of a DURATION and a DATE-TIME.
+
+4.3 Multi-Valued Properties
+
+Some properties, such as CATEGORIES have only one value type, but each
+CATEGORIES 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,
+
+CATEGORIES: work, home
+
+becomes in libical's internal representation
+
+CATEGORIES: work
+
+CATEGORIES: home
+
+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.
+
+5 Using libical
+
+5.1 Creating Components
+
+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.
+
+5.1.1 Constructor Interfaces
+
+Using constructor interfaces, you create each of the objects separately
+and then assemble them in to components:
+
+icalcomponent *event;
+
+icalproperty *prop;
+
+icalparameter *param;
+
+struct icaltimetype atime;
+
+event = icalcomponent_new(ICAL_VEVENT_COMPONENT);
+
+prop = icalproperty_new_dtstamp(atime) ;
+
+icalcomponent_add_property(event, prop);
+
+prop = icalproperty_new_uid(''guid-1.host1.com'') );
+
+icalcomponent_add_property(event,prop);
+
+prop=icalproperty_new_organizer(''mrbig@host.com'');
+
+param = icalparameter_new_role(ICAL_ROLE_CHAIR)
+
+icalproperty_add_parameter(prop, param);
+
+icalcomponent_add_property(event,prop);
+
+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 "new" 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 [sec:memory].
+
+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.
+
+5.1.2 vaargs Constructors
+
+There is another way to create complex components, which is arguably
+more elegant, if you are not horrified by varargs. The varargs constructor
+interface allows you to create intricate components in a single block
+of code. Here is the previous examples in the vaargs style.
+
+ calendar =
+
+ icalcomponent_vanew(
+
+ ICAL_VCALENDAR_COMPONENT,
+
+ icalproperty_new_version(''2.0''),
+
+ icalproperty_new_prodid(
+
+ ''-//RDU Software//NONSGML HandCal//EN''),
+
+ icalcomponent_vanew(
+
+ ICAL_VEVENT_COMPONENT,
+
+ icalproperty_new_dtstamp(atime),
+
+ icalproperty_new_uid(''guid-1.host1.com''),
+
+ icalproperty_vanew_organizer(
+
+ ''mrbig@host.com''),
+
+ icalparameter_new_role(ICAL_ROLE_CHAIR),
+
+ 0
+
+ ),
+
+ icalproperty_vanew_attendee(
+
+ ''employee-A@host.com'',
+
+ icalparameter_new_role(
+
+ ICAL_ROLE_REQPARTICIPANT),
+
+ icalparameter_new_rsvp(1),
+
+ icalparameter_new_cutype(ICAL_CUTYPE_GROUP),
+
+ 0
+
+ ),
+
+ icalproperty_new_location(
+
+ "1CP Conference Room 4350"),
+
+ 0
+
+ ),
+
+ 0
+
+ );
+
+This form is similar to the constructor form , except that the constructors
+have "vanew" instead of "new" in the name. The arguments are similar
+too, except that the component constructor can have a list of properties,
+and the property constructor can have a list of parameters. Be sure
+to terminate every list with a '0', or your code will crash, if you
+are lucky.
+
+5.1.3 Parsing Text Files
+
+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
+
+icalcomponent* icalparser_parse_string(char* str);
+
+If the string contains only one component, the parser will return the
+component in libical form. If the string contains multiple components,
+the multiple components will be returned as the children of an ICAL_XROOT_COMPONENT
+component.
+
+Parsing a whole string may seem wasteful if you want to pull a large
+component off of the network or from a file; you may prefer to parse
+the component line by line. This is possible too by using:
+
+icalparser* icalparser_new();
+
+void icalparser_free(icalparser* parser);
+
+icalparser_get_line(parser,read_stream);
+
+icalparser_add_line(parser,line);
+
+icalparser_set_gen_data(parser,stream)
+
+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. These routines work by specifing an adaptor routine
+to get string data from a source. For an example:
+
+char* read_stream(char *s, size_t size, void *d)
+
+{
+
+ char *c = fgets(s,size, (FILE*)d);
+
+ return c;
+
+}
+
+main() {
+
+ char* line;
+
+ icalcomponent *c;
+
+ icalparser *parser = icalparser_new();
+
+ FILE* stream = fopen(argv[1],"r");
+
+ icalparser_set_gen_data(parser,stream);
+
+ do{
+
+ line = icalparser_get_line(parser,read_stream);
+
+ c = icalparser_add_line(parser,line);
+
+ if (c != 0){
+
+ printf("%s",icalcomponent_as_ical_string(c));
+
+ icalparser_claim(parser);
+
+ printf("\n---------------\n");
+
+ icalcomponent_free(c);
+
+ }
+
+ } while ( line != 0);
+
+}
+
+The parser object parameterizes the routine used to get input lines
+with icalparser_set_gen_data() and 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().
+By using a different routine for read_stream or passing in different
+data with icalparser_set_gen_data, you can connect to any data source.
+
+Using the same mechanism, other implementations could read from memory
+buffers, sockets or other interfaces.
+
+Since the example code is a very common way to use the parser, there
+is a convenience routine;
+
+icalcomponent* icalparser_parse(icalparser *parser,
+
+ char* (*line_gen_func)(char *s, size_t size, void*
+d))
+
+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
+components 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.
+
+5.2 Accessing Components
+
+Given a reference to a component, you probably will want to access
+the properties, parameters and values inside. Libical interfaces let
+you find sub-component, add and remove sub-components, and do the
+same three operations on properties.
+
+5.2.1 Finding Components
+
+To find a sub-component of a component, use:
+
+icalcomponent* icalcomponent_get_first_component(
+
+ icalcomponent* component,
+
+ icalcomponent_kind kind);
+
+This routine will return a reference to the first component of the
+type 'kind.' The key kind values, listed in icalenums.h are:
+
+ICAL_ANY_COMPONENT
+
+ICAL_VEVENT_COMPONENT
+
+ICAL_VTODO_COMPONENT
+
+ICAL_VJOURNAL_COMPONENT
+
+ICAL_VCALENDAR_COMPONENT
+
+ICAL_VFREEBUSY_COMPONENT
+
+ICAL_VALARM_COMPONENT
+
+These are only the most common components; there are many more listed
+in icalenums.h.
+
+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.
+
+5.2.2 Iterating Through Components
+
+Iteration requires a second routine to get the next subcomponent after
+the first:
+
+icalcomponent* icalcomponent_get_next_component(
+
+ icalcomponent* component,
+
+ icalcomponent_kind kind);
+
+With the 'first' and 'next' routines, you can create a for loop to
+iterate through all of a components subcomponents
+
+ for(c = icalcomponent_get_first_component(comp,ICAL_ANY_COMPONENT);
+
+ c != 0;
+
+ c = icalcomponent_get_next_component(comp,ICAL_ANY_COMPONENT))
+
+{
+
+ do_something(c);
+
+}
+
+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.
+
+5.2.3 Using Component Iterators
+
+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()
+when an iteration is in progress, the pointer will be reset to the
+beginning.
+
+To solve this problem, there are also external iterators for components.
+The routines associated with these external iterators are:
+
+icalcompiter icalcomponent_begin_component(icalcomponent* component,
+icalcomponent_kind kind);
+
+icalcompiter icalcomponent_end_component(icalcomponent* component,
+icalcomponent_kind kind);
+
+icalcomponent* icalcompiter_next(icalcompiter* i);
+
+icalcomponent* icalcompiter_prior(icalcompiter* i);
+
+icalcomponent* icalcompiter_deref(icalcompiter* i);
+
+The _begin_() and _end_() routines return a new iterator that points
+to the beginning and ending of the list of subcomponent for the given
+component, and the kind argument works like the kind argument for
+internal iterators.
+
+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.
+
+Here is an example of a loop using these routines:
+
+for(
+
+ i = icalcomponent_begin_component(impl->cluster,ICAL_ANY_COMPONENT);
+
+ icalcompiter_deref(&i)!= 0;
+
+ icalcompiter_next(&i)
+
+) {
+
+ icalcomponent *this = icalcompiter_deref(&i);
+
+}
+
+5.2.4 Removing Components
+
+Removing an element from a list while iterating through the list with
+the internal iterators 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:
+
+for(c = icalcomponent_get_first_component(parent_comp,ICAL_ANY_COMPONENT);
+
+ c != 0;
+
+ c = next
+
+{
+
+ next = icalcomponent_get_next_component(parent_comp,ICAL_ANY_COMPONENT);
+
+ icalcomponent_remove_component(parent_comp,c);
+
+}
+
+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:
+
+icalcomponent_get_first_component(parent_comp,ICAL_VEVENT_COMPONENT);
+
+while((c=icalcomponent_get_current_component(c)) != 0 ){
+
+ if(icalcomponent_isa(c) == ICAL_VEVENT_COMPONENT){
+
+ icalcomponent_remove_component(parent_comp,inner);
+
+ } else {
+
+ icalcomponent_get_next_component(parent_comp,ICAL_VEVENT_COMPONENT);
+
+ }
+
+}
+
+5.2.5 Working with properties and parameters
+
+Finding, iterating and removing properties works the same as it does
+for components, using the property-specific or parameter-specific
+interfaces:
+
+icalproperty* icalcomponent_get_first_property(
+
+ icalcomponent* component,
+
+ icalproperty_kind kind);
+
+icalproperty* icalcomponent_get_next_property(
+
+ icalcomponent* component,
+
+ icalproperty_kind kind);
+
+void icalcomponent_add_property(
+
+ icalcomponent* component,
+
+ icalproperty* property);
+
+void icalcomponent_remove_property(
+
+ icalcomponent* component,
+
+ icalproperty* property);
+
+For parameters:
+
+icalparameter* icalproperty_get_first_parameter(
+
+ icalproperty* prop,
+
+ icalparameter_kind kind);
+
+icalparameter* icalproperty_get_next_parameter(
+
+ icalproperty* prop,
+
+ icalparameter_kind kind);
+
+void icalproperty_add_parameter(
+
+ icalproperty* prop,
+
+ icalparameter* parameter);
+
+void icalproperty_remove_parameter(
+
+ icalproperty* prop,
+
+ icalparameter_kind kind);
+
+Note that since there should be only one parameter of each type in
+a property, you will rarely need to use icalparameter_get_nect_paameter.
+
+5.2.6 Working with values
+
+Values are typically part of a property, although they can exist on
+their own. You can manipulate them either as part of the property
+or independently.
+
+The most common way to work with values to is to manipulate 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.
+
+For each property, there are a _get_ and a _set_ routine that access
+the internal value. For instanace, for the UID property, the routines
+are:
+
+void icalproperty_set_uid(icalproperty* prop, const char* v)
+
+const char* icalproperty_get_uid(icalproperty* prop)
+
+For multi-valued properties, like ATTACH, the value type is usually
+a struct or union that holds both possible types.
+
+If you want to work with the underlying value object, you can get and
+set it with:
+
+icalvalue* icalproperty_get_value (icalproperty* prop)
+
+void icalproperty_set_value(icalproperty* prop, icalvalue* value);
+
+Icalproperty_get_value() will return a reference that you can manipulate
+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 manipulate it with:
+
+struct icaltimetype icalvalue_get_datetime(icalvalue* value);
+
+void icalvalue_set_datetime(icalvalue* value, struct icaltimetype v);
+
+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:
+
+void icalproperty_set_x(icalproperty* prop, char* v);
+
+char* icalproperty_get_x(icalproperty* prop);
+
+All X properties have the type of ICAL_X_PROPERTY, so you will need
+these routines to get and set the name of the property:
+
+char* icalproperty_get_x_name(icalproperty* prop)
+
+void icalproperty_set_x_name(icalproperty* prop, char* name);
+
+5.2.7 Checking Component Validity
+
+RFC 2446 defines rules for what properties must exist in a component
+to be used for transferring scheduling data. Most of these rules relate
+to the existence of properties relative to the METHOD property, which
+declares what operation a remote receiver 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 receiver to join in
+a meeting. In this case, RFC2446 says that the component must specify
+a start time (DTSTART) and list the receiver as an attendee (ATTENDEE).
+
+Libical can check these restrictions with the routine:
+
+int icalrestriction_check(icalcomponent* comp);
+
+This routine returns 0 if the component does not pass RFC2446 restrictions,
+or if the component is malformed. The component you pass in must be
+a VCALENDAR, with one or more children, like the examples in RFC2446.
+
+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.
+
+5.2.8 Converting Components to Text
+
+To create an RFC2445 compliant text representation of an object, use
+one of the *_as_ical_string() routines:
+
+char* icalcomponent_as_ical_string (icalcomponent* component)
+
+char* icalproperty_as_ical_string (icalproperty* property)
+
+char* icalparameter_as_ical_string (icalparameter* parameter)
+
+char* icalvalue_as_ical_string (icalvalue* value)
+
+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.
+
+Icalproperty_as_ical_string() will terminate each line with the RFC2445
+specified line terminator "\\n" However, if you compile with the symbol
+ICAL_UNIX_NEWLINE undefined, ( it is defined by default) it will terminate
+lines with "\\n\\r"
+
+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.
+
+5.3 Time
+
+5.3.1 Time structure
+
+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 struct tm, but that
+structure does not differentiate between dates and times, and between
+local time and UTC. The libical structure is:
+
+struct icaltimetype {
+
+ int year;
+
+ int month;
+
+ int day;
+
+ int hour;
+
+ int minute;
+
+ int second;
+
+ int is_utc; /* 1-> time is in UTC timezone */
+
+ int is_date; /* 1 -> interpret this as date. */ };
+
+The year, month, day, hour, minute and second fields hold the broken-out
+time values. The is_utc field distinguishes between times in UTC and
+a local time zone. The is_date field indicates if the time should
+be interpreted only as a date. If it is a date, the hour, minute and
+second fields are assumed to be zero, regardless of their actual vaules.
+
+5.3.2 Creating time structures
+
+There are several ways to create a new icaltimetype structure:
+
+struct icaltimetype icaltime_from_string(const char* str);
+
+struct icaltimetype icaltime_from_timet(time_t v, int is_date);
+
+struct icaltimetype icaltime_from_int(int v, int is_date, int is_utc);
+
+Icaltime_from_string takes any RFC2445 compliant time string:
+
+struct icaltimetype tt = icaltime_from_string("19970101T103000");
+
+Icaltime_from_timet takes a timet value, representing seconds past
+the POSIX epoch, and a flag to indicate if the time is a date. Dates
+have an identical structure to a time, but the time portion ( hours,
+minuts and seconds ) is always 00:00:00. Dates act differently in
+sorting an comparision, and they have a different string representation
+in RFC2445.
+
+The icaltime_from_int is like icaltime_from_timet, but with an arbitrary
+epoch. This routine was a mistake and is deprecated.
+
+5.3.3 Time manipulating routines
+
+The null time value is used to indicate that the data in the structure
+is not a valid time.
+
+struct icaltimetype icaltime_null_time(void);
+
+int icaltime_is_null_time(struct icaltimetype t);
+
+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.
+
+struct icaltimetype icaltime_normalize(struct icaltimetype t);
+
+Normalizing allows you to do arithmetic operations on time values.
+
+struct icaltimetype tt = icaltime_from_string("19970101T103000");
+
+tt.days +=3
+
+tt.second += 70;
+
+tt = icaltime_normalize(tt);
+
+There are several routines to get the day of the week or month, etc,
+from a time structure.
+
+short icaltime_day_of_year(struct icaltimetype t);
+
+struct icaltimetype icaltime_from_day_of_year(short doy, short year);
+
+short icaltime_day_of_week(struct icaltimetype t);
+
+short icaltime_start_doy_of_week(struct icaltimetype t);
+
+short icaltime_week_number(short day_of_month, short month, short year);
+
+struct icaltimetype icaltime_from_week_number(short week_number, short
+year);
+
+short icaltime_days_in_month(short month,short year);
+
+Two routines convert time structures to and from the number of seconds
+since the POSIX epoch. The is_date field indicates whether or not
+the hour, minute and second fields should be used in the conversion.
+
+struct icaltimetype icaltime_from_timet(time_t v, int is_date);
+
+time_t icaltime_as_timet(struct icaltimetype);
+
+The compare routine works exactly like strcmp, but on time structures.
+
+int icaltime_compare(struct icaltimetype a,struct icaltimetype b);
+
+The following routines convert between UTC and a named timezone. The
+tzid field must be a timezone name from the Olsen database, such as
+"America/Los_Angeles."
+
+The utc_offset routine returns the offset of the named time zone from
+UTC, in seconds.
+
+The tt parameter in the following 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.
+
+int icaltime_utc_offset(struct icaltimetype tt, char* tzid);
+
+int icaltime_local_utc_offset();
+
+struct icaltimetype icaltime_as_utc(struct icaltimetype tt,char* tzid);
+
+struct icaltimetype icaltime_as_zone(struct icaltimetype tt,char* tzid);
+
+struct icaltimetype icaltime_as_local(struct icaltimetype tt);
+
+5.4 Storing Objects
+
+The libical distribution includes a separate library, libicalss, that
+allows you to store iCal component data to disk in a variety of ways.
+This library also includes code to implement the CSTP protocol of
+CAP and has some routines for deciphering incomming messages.
+
+The file storage routines are organized in an inheritance heirarchy
+that is rooted in icalset, with the derived class icalfileset and
+icaldirset. Icalfileset stores components to a file, while icaldirset
+stores components to multiple files, one per month based on DTSTAMP.
+Other storages classess, for storage to a heap or a mysql database
+are planned for the future.
+
+All of the icalset derived classes have the same interface:
+
+icaldirset* icaldirset_new(const char* path);
+
+void icaldirset_free(icaldirset* store);
+
+const char* icaldirset_path(icaldirset* store);
+
+void icaldirset_mark(icaldirset* store);
+
+icalerrorenum icaldirset_commit(icaldirset* store);
+
+icalerrorenum icaldirset_add_component(icaldirset* store, icalcomponent*
+comp);
+
+icalerrorenum icaldirset_remove_component(icaldirset* store, icalcomponent*
+comp);
+
+int icaldirset_count_components(icaldirset* store, icalcomponent_kind
+kind);
+
+icalerrorenum icaldirset_select(icaldirset* store, icalcomponent* gauge);
+
+void icaldirset_clear(icaldirset* store);
+
+icalcomponent* icaldirset_fetch(icaldirset* store, const char* uid);
+
+int icaldirset_has_uid(icaldirset* store, const char* uid);
+
+icalcomponent* icaldirset_fetch_match(icaldirset* set, icalcomponent
+*c);
+
+icalerrorenum icaldirset_modify(icaldirset* store, icalcomponent *oldc,
+icalcomponent *newc);
+
+icalcomponent* icaldirset_get_current_component(icaldirset* store);
+
+icalcomponent* icaldirset_get_first_component(icaldirset* store);
+
+icalcomponent* icaldirset_get_next_component(icaldirset* store);
+
+5.4.1 Creating a new set
+
+You can create a new set from either the base class or the direved
+class. From the base class use one of:
+
+icalset* icalset_new_file(const char* path);
+
+icalset* icalset_new_dir(const char* path);
+
+icalset* icalset_new_heap(void);
+
+icalset* icalset_new_mysql(const char* path);
+
+You can also create a new set based on the derived class, For instance,
+with icalfileset:
+
+icalfileset* icalfileset_new(const char* path);
+
+icalfileset* icalfileset_new_open(const char* path, int flags, mode_t
+mode);
+
+Icaset_new_file is identical to icalfileset_new. BOth routines will
+open an existing file for readinga and writing, or create a new file
+if it does not exist. Icalfilset_new_open takes the same arguments
+as the open() system routine and behaves in the same way.
+
+The icalset and icalfilset objects are somewhat interchangable -- you
+can use an icalfileset* as an argument to any of the icalset routines.
+
+The following examples will all use icalfileset routines; using the
+other icalset derived classess will be similar.
+
+5.4.2 Adding, Finding and Removing Components
+
+To add components to a set, use:
+
+icalerrorenum icalfileset_add_component(icalfileset* cluster, icalcomponent*
+child);
+
+The fileset keeps an inmemory copy of the components, and this set
+must be written back to the file ocassionally. There are two routines
+to manage this:
+
+void icalfileset_mark(icalfileset* cluster);
+
+icalerrorenum icalfileset_commit(icalfileset* cluster);
+
+Icalfileset_mark indicates that the in-memory components have changed.
+Calling the _add_component routine will call _mark automatically,
+but you may need to call it yourself if you have made a change to
+an existing component. The _commit routine writes the data base to
+disk, but only if it is marked. The _commit routine is called automatically
+when the icalfileset is freed.
+
+To iterate through the components in a set, use:
+
+icalcomponent* icalfileset_get_first_component(icalfileset* cluster);
+
+icalcomponent* icalfileset_get_next_component(icalfileset* cluster);
+
+icalcomponent* icalfileset_get_current_component (icalfileset* cluster);
+
+These routines work like the corresponding routines from icalcomponent,
+except that their output is filtered through a gauge. A gauge is a
+test for the properties within a components; only components that
+pass the test are returned. A gauge can be constructed from a MINSQL
+string with:
+
+icalgauge* icalgauge_new_from_sql(char* sql);
+
+Then, you can add the gauge to the set with :
+
+icalerrorenum icalfileset_select(icalfileset* store, icalgauge* gauge);
+
+Here is an example that puts all of these routines together:
+
+void test_fileset()
+
+{
+
+ icalfileset *fs;
+
+ icalcomponent *c;
+
+ int i;
+
+ char *path = "test_fileset.ics";
+
+ icalgauge *g = icalgauge_new_from_sql(
+
+ "SELECT * FROM VEVENT WHERE DTSTART > '20000103T120000Z' AND
+DTSTART <= '20000106T120000Z'");
+
+
+
+ fs = icalfileset_new(path);
+
+
+
+ for (i = 0; i!= 10; i++){
+
+ c = make_component(i); /* Make a new component where DTSTART
+has month of i */
+
+ icalfileset_add_component(fs,c);
+
+ }
+
+ icalfileset_commit(fs); /* Write to disk */
+
+ icalfileset_select(fs,g); /* Set the gauge to filter components
+*/
+
+
+
+ for (c = icalfileset_get_first_component(fs);
+
+ c != 0;
+
+ c = icalfileset_get_next_component(fs)){
+
+ struct icaltimetype t = icalcomponent_get_dtstart(c);
+
+
+
+ printf("%s\n",icaltime_as_ctime(t));
+
+ }
+
+ icalfileset_free(fs);
+
+}
+
+5.4.3 Other routines
+
+There are several other routines in the icalset interface, but they
+not fully implemented yet.
+
+5.5 <sec:memory>Memory Management
+
+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.
+
+1) If the function name has "new" in it, the caller gets control
+ of the memory. ( such as icalcomponent_new(), or icalproperty_new_clone()
+ )
+
+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())
+
+3) If the function name has "add" in it, the caller is transferring
+ control of the memory to the routine. ( icalproperty_add_parameter() )
+
+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.
+
+5) If the routine returns a string, libical owns the memory and will
+ put it on a ring buffer to reclaim later. For example, icalcomponent_as_ical_string().
+ You'd better strdup() it if you want to keep it, and you don't have
+ to delete it.
+
+5.6 Error Handling
+
+Libical has several error handling mechanisms for the various types
+of programming, semantic and syntactic errors you may encounter.
+
+5.6.1 Return values
+
+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.
+
+5.6.2 icalerrno
+
+Most routines will set the global error value icalerrno on errors.
+This variable is an enumeration; permissible values can be found in
+libical/icalerror.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. The enumerations are:
+
+* ICAL_BADARG_ERROR -- One of the argument to a routine was bad. Typically
+ for a null pointer.
+
+* ICAL_NEWFAILED_ERROR -- A new() or malloc() failed
+
+* ICAL_MALFORMEDDATA_ERROR -- An input string was not in the correct
+ format
+
+* ICAL_PARSE_ERROR -- The parser failed to parse an incomming component
+
+* ICAL_INTERNAL_ERROR -- Largely equivalent to an assert
+
+* ICAL_FILE_ERROR -- A file operation failed. Check errno for more
+ detail.
+
+* ICAL_ALLOCATION_ERROR -- ?
+
+* ICAL_USAGE_ERROR -- ?
+
+* ICAL_NO_ERROR -- No error
+
+* ICAL_MULTIPLEINCLUSION_ERROR -- ?
+
+* ICAL_TIMEDOUT_ERROR -- For CSTP and acquiring locks
+
+* ICAL_UNKNOWN_ERROR -- ?
+
+5.6.3 X-LIC-ERROR and X-LIC-INVALID-COMPONENT
+
+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 requirements
+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:
+
+X-LIC-ERROR;X-LIC-ERRORTYPE=INVALID_ITIP :Failed iTIP restrictions
+for property DTSTART.
+
+Expected 1 instances of the property and got 0
+
+This error resulted from a call to icalrestriction_check(), which discovered
+that the component does not have a DTSTART property, as required by
+RFC2445.
+
+There are a few routines to manipulate error properties:
+
+[ The following data is supposed to be in a table. It looks OK in LyX,
+but does not format propertly in output. ]
+
++-------------------------------------+---------------------------------------------------------+
+| Routine | Purpose |
++-------------------------------------+---------------------------------------------------------+
+| void icalrestriction_check() | Check a component against RFC2446 and insert |
++-------------------------------------+---------------------------------------------------------+
+| | error properties to indicate non compliance |
++-------------------------------------+---------------------------------------------------------+
+| int icalcomponent_count_errors() | Return the number of error properties |
++-------------------------------------+---------------------------------------------------------+
+| | in a component |
++-------------------------------------+---------------------------------------------------------+
+| void icalcomponent_strip_errors() | Remove all error properties in as |
++-------------------------------------+---------------------------------------------------------+
+| | component |
++-------------------------------------+---------------------------------------------------------+
+| void icalcomponent_convert_errors() | Convert some error properties into |
++-------------------------------------+---------------------------------------------------------+
+| | REQUESTS-STATUS proprties to indicate the inability to |
++-------------------------------------+---------------------------------------------------------+
+| | process the component as an iTIP request. |
++-------------------------------------+---------------------------------------------------------+
+
+
+The types of errors are listed in icalerror.h. They are:
+
+ICAL_XLICERRORTYPE_COMPONENTPARSEERROR
+
+ICAL_XLICERRORTYPE_PARAMETERVALUEPARSEERROR
+
+ICAL_XLICERRORTYPE_PARAMETERNAMEPARSEERROR
+
+ICAL_XLICERRORTYPE_PROPERTYPARSEERROR
+
+ICAL_XLICERRORTYPE_VALUEPARSEERROR
+
+ICAL_XLICERRORTYPE_UNKVCALPROP
+
+ICAL_XLICERRORTYPE_INVALIDITIP
+
+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.
+
+Icalcomponent_convert_errors() converts some of the error properties
+in a 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.
+
+5.6.4 ICAL_ERRORS_ARE_FATAL and icalerror_errors_are_fatal
+
+If the global variable icalerror_errors_are_fatal is set to 1, then
+any error condition will cause the program to abort. The abort occurs
+in icalerror_set_errno(), and is done with an assert(0) if NDEBUG
+is undefined, and with icalerror_crash_here if NDEBUG is defined.
+The default value of icalerror_errors_are_fatal is 1 when ICAL_ERRORS_ARE_FATAL
+is defined, and 0 otherwise. Since ICAL_ERRORS_ARE_FATAL is defined
+by default, icalerror_errors_are_fatal is also defined by default.
+
+5.7 Naming Standard
+
+Structures that you access with the "struct" keyword, such as "struct
+icaltimetype" are things that you are allowed to see inside and poke
+at.
+
+Structures that you access though a typedef, such as "icalcomponent"
+are things where all of the data is hidden.
+
+Component names that start with "V" are part of RFC 2445 or another
+iCal standard. Component names that start with "X" 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 "XLIC" or "X-LIC" are not part of any iCal spec.
+They are used internally by libical.
+
+Enums that identify a component, property, value or parameter end with
+"_COMPONENT," "_PROPERTY," "_VALUE," or "_PARAMETER"s
+
+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.
+
+The enums for the parts of a recurarance rule and request statuses
+are irregular.
+
+6 Hacks and Bugs
+
+There are a lot of hacks in the library -- bits of code that I am not
+proud of and should probably be changed. These are marked with the
+comment string "HACK."
+
+7 Library Reference
+
+7.1 Manipulating struct icaltimetype
+
+7.1.1 Struct icaltimetype
+
+struct icaltimetype
+
+{
+
+ int year;
+
+ int month;
+
+ int day;
+
+ int hour;
+
+ int minute;
+
+ int second;
+
+ int is_utc;
+
+ int is_date;
+
+ const char* zone;
+
+};