From 4873d50a914ad0c3041010195808f3e596e8ba0f Mon Sep 17 00:00:00 2001 From: nobody Date: Sat, 17 Jun 2000 21:00:40 +0000 Subject: This commit was manufactured by cvs2svn to create tag 'gnome-debug-0-1-3'. svn path=/tags/gnome-debug-0-1-3/; revision=3621 --- libical/doc/UsingLibical.sgml | 318 ------------------------------------------ 1 file changed, 318 deletions(-) delete mode 100644 libical/doc/UsingLibical.sgml (limited to 'libical/doc/UsingLibical.sgml') diff --git a/libical/doc/UsingLibical.sgml b/libical/doc/UsingLibical.sgml deleted file mode 100644 index d967bd860c..0000000000 --- a/libical/doc/UsingLibical.sgml +++ /dev/null @@ -1,318 +0,0 @@ - - - -
- -Using Libical - - -Eric Busboom (eric@softwarestudio.org) - - -January 2000 - - -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 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 ------------- - -

-$Id: UsingLibical.lyx,v 1.3 2000/01/06 06:20:06 eric Exp eric $ -

- -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. -

- -Purpose & Goals - -Building the Library - -Structure -

-The iCal calendar model is based on four types of objects: components, - properties, values and parameters. -

-

-Components are the fundamental grouping of calendar information -

-

-Properties are the fundamental unit of information. Each property is composed - of a type, a value and collection of parameters. -

- -Components -

-Components are named clusters of properties -

- -Properties - -Values - -Parameters - -Storage - -Cluster - -Store - -Calendar - -Other bits -

-Restrictions -

-

-Types -

- -Differences From RFCs -

-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. -

- -Pseudo Components -

-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. - -

-

-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. -

-

-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. - -

- -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. 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 -

-

-struct icaltriggertype -

-

-This type is a union of a DURATION and a DATE-TIME. -

- -Multi-Valued Properties -

-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, -

-

- -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. -

- -Implementation Limitations - -Using libical - -Creating Components - -Constructor interfaces - -vaargs Constructors - -Parsing Text Files - -Accessing Components - -Finding Components - -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); -} - -

-Finding Properties - -Removing Properties - -Getting Values - -Setting Values - -Getting Parameters - -Setting Parameters - -Removing Parameters - -Storing Objects -

-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. - ) -

- -Memory Management -

-Here are the memory rules for the C 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. - -

-Error Handling - -Return values - -icalerrno - -Component errors - -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. -

- -Hacks and Bugs - - -
-- cgit v1.2.3