diff options
Diffstat (limited to 'libical/doc/UsingLibical.sgml')
| -rw-r--r-- | libical/doc/UsingLibical.sgml | 318 |
1 files changed, 318 insertions, 0 deletions
diff --git a/libical/doc/UsingLibical.sgml b/libical/doc/UsingLibical.sgml new file mode 100644 index 0000000000..d967bd860c --- /dev/null +++ b/libical/doc/UsingLibical.sgml @@ -0,0 +1,318 @@ +<!doctype linuxdoc system> + +<!-- LinuxDoc file was created by LyX 1.0 (C) 1995-1999 by <eric> Wed Jan 5 22:30:06 2000 + --> + <article> + <title> +Using Libical + </title> + <author> +Eric Busboom (eric@softwarestudio.org) + </author> + <date> +January 2000 + </date> + <sect> +Introduction + <p> +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. + </p> + <p> +Libical implements the following specifications and protocols + </p> + <p> +iCal Core +2445 +iTIP +2446 +iMIP +2447 +iRIP +draft +CAP +draft + </p> + <p> +(The current version, 0.14, does not implement iRip or CAP. ) + </p> + <p> +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 + </p> + <p> + <quote> +http://softwarestudio.org/libical/index.html + </quote> +</p> <p> +and a mailing list that you can join by sending the following mail: + </p> + <p> + <code> +------------ +To: minimalist@softwarestudio.org +Subject: subscribe libical +------------ + </code> +</p> <p> +$Id: UsingLibical.lyx,v 1.3 2000/01/06 06:20:06 eric Exp eric $ + </p> + <sect1> +License + <p> +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. + </p> + <p> +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. + </p> + <sect1> +Purpose & Goals + <sect> +Building the Library + <sect> +Structure + <p> +The iCal calendar model is based on four types of objects: components, + properties, values and parameters. + </p> + <p> +Components are the fundamental grouping of calendar information + </p> + <p> +Properties are the fundamental unit of information. Each property is composed + of a type, a value and collection of parameters. + </p> + <sect1> +Components + <p> +Components are named clusters of properties + </p> + <sect1> +Properties + <sect1> +Values + <sect1> +Parameters + <sect1> +Storage + <sect2> +Cluster + <sect2> +Store + <sect2> +Calendar + <sect1> +Other bits + <p> +Restrictions + </p> + <p> +Types + </p> + <sect> +Differences From RFCs + <p> +Although libical has been design to follow the standards as closely as + possible, there are a few areas where the specifications are irregular, and + following them exactly would result in an unfriendly interface. + </p> + <sect1> +Pseudo Components + <p> +Libical defines pseudo components for groups of properties that look and + act like components, but are not defined as components in the specification. + XDAYLIGHT and XSTANDARD are notable examples. These pseudo components group + properties within the VTIMEZONE components. XDAYLIGHT starts with "BEGIN: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, it is a component. + + </p> + <p> +There are also pseudo componentsthat 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. + </p> + <p> +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. + </p> + <p> +To handle these various, complex restrictions, libical has pseudo components + for each type of alarm: XAUDIOALARM, XDISPLAYALARM, XEMAILALARM and XPROCEDUREALARM. + + </p> + <sect1> +Combined Values + <p> +Many values can take more than one type. TRIGGER, for instance, can have + a value type of with DURATION or of DATE-TIME. 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. + In libical, the value of the TRIGGER property resolves to + </p> + <p> +struct icaltriggertype + </p> + <p> +This type is a union of a DURATION and a DATE-TIME. + </p> + <sect1> +Multi-Valued Properties + <p> +Some properties, such as CATEGORIES, have a single value type, but may + have multiple values in a single instance. This also results in a cumbersome + interface -- CATEGORIES accessors would have to return a list which 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. The is, + </p> + <p> + <code> +CATEGORIES: work, home + </code> +</p> <p> +becomes in libical's internal representation + </p> + <p> + <code> +CATEGORIES: work +CATEGORIES: home + </code> +</p> <p> +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. + </p> + <sect> +Implementation Limitations + <sect> +Using libical + <sect1> +Creating Components + <sect2> +Constructor interfaces + <sect2> +vaargs Constructors + <sect2> +Parsing Text Files + <sect1> +Accessing Components + <sect2> +Finding Components + <sect2> +Removing Components + <p> +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: + </p> + <p> + <code> +for(c = icalcomponent_get_first_component(s); + c != 0; + c = next) +{ + next = icalcomponent_get_next_component(s); + icalcomponent_remove_component(s,c); +} + </code> +</p> <sect2> +Finding Properties + <sect2> +Removing Properties + <sect2> +Getting Values + <sect2> +Setting Values + <sect2> +Getting Parameters + <sect2> +Setting Parameters + <sect2> +Removing Parameters + <sect1> +Storing Objects + <p> +When you store a component to the database with icalstore_add_component, + you give the library takes the memory, so the caller does not own the component + anymore. If you want to keep ownership, use clone to make a copy. ( See "Memory + Management" and "Naming Starndard for more about routines with "add" in the name. + ) + </p> + <sect1> +Memory Management + <p> +Here are the memory rules for the C library: + </p> + <p> + <descrip> + <tag> +1)</tag>If the function name has "new" in it, the caller gets + control of the memory. ( such as icalcomponent_new(), or icalproperty_new_clone() + ) + <tag> +2)</tag>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()) + <tag> +3)</tag>If the function name has "add" in it, the caller is + transfering control of the memory to the routine. ( icalproperty_add_parameter() + ) + <tag> +4)</tag>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. + <tag> +5)</tag>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. + </descrip> +</p> <sect1> +Error Handling + <sect2> +Return values + <sect2> +icalerrno + <sect2> +Component errors + <sect1> +Naming Standard + <p> +Structures that you access with the "struct" keyword, such as "struct icaltimetype" + are things that you are allowed to see inside and poke at. + </p> + <p> +Structures that you access though a typedef, such as "icalcomponent" are + things where all of the data is hidden. + </p> + <p> +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. + </p> + <sect> +Hacks and Bugs + + + </article> |