path: root/libical/doc/UsingLibical.sgml

<!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>
&dollar;Id: UsingLibical.lyx,v 1.3 2000/01/06 06:20:06 eric Exp eric &dollar;
 </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 &amp; 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)
&lcub; 
    next = icalcomponent_get_next_component(s);
    icalcomponent_remove_component(s,c); 
&rcub;
 </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 &quot;new&quot; 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 &quot;add&quot; in it, the caller is
 transfering control of the memory to the routine. ( icalproperty_add_parameter()
 )
  <tag>
4)</tag>If the function name has &quot;remove&quot; 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 &quot;foo&quot; 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>