Initial revision

svn path=/trunk/; revision=1823

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>
+&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>