aboutsummaryrefslogtreecommitdiffstats
path: root/libical/doc/UsingLibical.txt
diff options
context:
space:
mode:
authorEric Busboom <ericb@src.gnome.org>2000-05-15 12:36:44 +0800
committerEric Busboom <ericb@src.gnome.org>2000-05-15 12:36:44 +0800
commitf8ff932ae3149c285acea3977a50596749d38584 (patch)
tree35b1dae583e169dda8f2ee7a31cf08dfc9658417 /libical/doc/UsingLibical.txt
parent8c965a2961ea6ae188a351be2671cfe63ac0a9ed (diff)
downloadgsoc2013-evolution-f8ff932ae3149c285acea3977a50596749d38584.tar
gsoc2013-evolution-f8ff932ae3149c285acea3977a50596749d38584.tar.gz
gsoc2013-evolution-f8ff932ae3149c285acea3977a50596749d38584.tar.bz2
gsoc2013-evolution-f8ff932ae3149c285acea3977a50596749d38584.tar.lz
gsoc2013-evolution-f8ff932ae3149c285acea3977a50596749d38584.tar.xz
gsoc2013-evolution-f8ff932ae3149c285acea3977a50596749d38584.tar.zst
gsoc2013-evolution-f8ff932ae3149c285acea3977a50596749d38584.zip
removing all files
svn path=/trunk/; revision=3040
Diffstat (limited to 'libical/doc/UsingLibical.txt')
-rw-r--r--libical/doc/UsingLibical.txt302
1 files changed, 0 insertions, 302 deletions
diff --git a/libical/doc/UsingLibical.txt b/libical/doc/UsingLibical.txt
deleted file mode 100644
index f80ea31121..0000000000
--- a/libical/doc/UsingLibical.txt
+++ /dev/null
@@ -1,302 +0,0 @@
-
-
-Using Libical
-
-Eric Busboom (eric@softwarestudio.org)
-
-January 2000
-
-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 for users can
-store their calendar data and arrange meetings with other users.
-
-Libical implements the following specifications and protocols
-
-+----------+-------+
-|iCal Core | 2445 |
-+----------+-------+
-+----------+-------+
-| iTIP | 2446 |
-+----------+-------+
-+----------+-------+
-| iMIP | 2447 |
-+----------+-------+
-+----------+-------+
-| iRIP | draft |
-+----------+-------+
-+----------+-------+
-| CAP | draft |
-+----------+-------+
-
-
-(The current version, 0.14, does not implement iRip or CAP. )
-
-This documentation assumes that you are familiar with the iCalendar
-standards RFC2445 and RFC2446.
-
-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 Purpose & Goals
-
-1.4 Document version
-
-$Id$
-
-2 Building the Library
-
-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.
-
-The central goal of libical is to parse iTIP data into an internal
-representation of Components, Properties, Parameters an Values, and
-to allow the user to manipulate the data in various ways
-
-3.1 Components
-
-3.2 Properties
-
-3.3 Values
-
-3.4 Parameters
-
-3.5 Enumerations
-
-3.6 Types
-
-3.7 The Parser
-
-3.8 Restrictions
-
-3.9 Memory Management
-
-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 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.
-
-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. 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.
-
-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.
-
-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 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 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 Implementation Limitations
-
-6 Using libical
-
-6.1 Creating Components
-
-6.1.1 Constructor Interfaces
-
-6.1.2 vaargs Constructors
-
-6.1.3 Parsing Text Files
-
-6.2 Accessing Components
-
-6.2.1 Finding Components
-
-6.2.2 Removing Components
-
-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:
-
-for(c = icalcomponent_get_first_component(s);
-
- c != 0;
-
- c = next)
-
-{
-
- next = icalcomponent_get_next_component(s);
-
- icalcomponent_remove_component(s,c);
-
-}
-
-6.2.3 Finding Properties
-
-6.2.4 Removing Properties
-
-6.2.5 Getting Values
-
-6.2.6 Setting Values
-
-6.2.7 Getting Parameters
-
-6.2.8 Setting Parameters
-
-6.2.9 Removing Parameters
-
-6.2.10 Checking Component Validity
-
-6.3 Storing Objects
-
-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.
-
-6.4 Memory Management
-
-Here are the memory rules for the library:
-
-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 transfering
- 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. You'd better strdup it
- if you want to keep it, and you don't have to delete it.
-
-6.5 Error Handling
-
-6.5.1 Return values
-
-6.5.2 icalerrno
-
-6.5.3 Component errors
-
-6.6 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.
-
-7 Hacks and Bugs