Fix fucking CVS conflicts because fucking CVS is a fucking big doofus - Federico

svn path=/trunk/; revision=6920

1 files changed, 320 insertions, 26 deletions

diff --git a/libical/doc/UsingLibical.lyx b/libical/doc/UsingLibical.lyx
index 868eac93b7..776f0d3835 100644
--- a/libical/doc/UsingLibical.lyx
+++ b/libical/doc/UsingLibical.lyx
@@ -30,7 +30,7 @@ Using Libical
 Eric Busboom (eric@softwarestudio.org)
 \layout Date
 
-May 2000
+November 2000
 \layout Standard
 
 
@@ -134,7 +134,15 @@ Building the Library
 
 Libical uses autoconf to generate makefiles, although it uses none of the
  autoconf flags to influence the compilation.
- It should built with no adjustments on Linux, FreeBSD and Solaris.
+ It should built with no adjustments on Linux, FreeBSD and Solaris under
+ gcc.
+ Some version have been successfully been build on MacOS, Solaris and UnixWare
+ without gcc, but you may run into problems with a particular later version.
+ 
+\layout Standard
+
+For a more complete guide to building the library, see the README file in
+ the distribution.
  
 \layout Section
 
@@ -272,7 +280,7 @@ Enumerations
 Types
 \layout Subsubsection
 
-The Parser
+The parser
 \layout Subsubsection
 
 Restrictions
@@ -487,13 +495,13 @@ prop = icalproperty_new_dtstamp(atime) ;
 icalcomponent_add_property(event, prop);
 \layout Code
 
-prop = icalproperty_new_uid(strdup("guid-1.host1.com")) );
+prop = icalproperty_new_uid("guid-1.host1.com") );
 \layout Code
 
 icalcomponent_add_property(event,prop);
 \layout Code
 
-prop=icalproperty_new_organizer(strdup("mrbig@host.com")); 
+prop=icalproperty_new_organizer("mrbig@host.com"); 
 \layout Code
 
 param = icalparameter_new_role(ICAL_ROLE_CHAIR) 
@@ -519,9 +527,6 @@ new
  in the name.
  Also note that, other than the object reference, most structure data is
  passed in to libical routines by value.
- Strings, of course, are passed in by reference, but libical will take ownership
- of the memory, so you had beter strdup() the data unless you want a core
- dump when the memory is freed for the second time.
  Libical has some complex but very regular memory handling rules.
  These are detailed in section 
 \begin_inset LatexCommand \ref{sec:memory}
@@ -559,13 +564,13 @@ There is another way to create complex components, which is arguable more
             ICAL_VCALENDAR_COMPONENT,
 \layout Verbatim
 
-            icalproperty_new_version(strdup("2.0")),
+            icalproperty_new_version("2.0"),
 \layout Verbatim
 
-            icalproperty_new_prodid(strdup(
+            icalproperty_new_prodid(
 \layout Verbatim
 
-                 "-//RDU Software//NONSGML HandCal//EN")),
+                 "-//RDU Software//NONSGML HandCal//EN"),
 \layout Verbatim
 
             icalcomponent_vanew(
@@ -577,13 +582,13 @@ There is another way to create complex components, which is arguable more
                 icalproperty_new_dtstamp(atime),
 \layout Verbatim
 
-                icalproperty_new_uid(strdup("guid-1.host1.com")),
+                icalproperty_new_uid("guid-1.host1.com"),
 \layout Verbatim
 
                 icalproperty_vanew_organizer(
 \layout Verbatim
 
-                    strdup("mrbig@host.com"),
+                    "mrbig@host.com"),
 \layout Verbatim
 
                     icalparameter_new_role(ICAL_ROLE_CHAIR),
@@ -598,7 +603,7 @@ There is another way to create complex components, which is arguable more
                 icalproperty_vanew_attendee(
 \layout Verbatim
 
-                    strdup("employee-A@host.com"),
+                    "employee-A@host.com",
 \layout Verbatim
 
                     icalparameter_new_role(
@@ -619,10 +624,10 @@ There is another way to create complex components, which is arguable more
                     ),
 \layout Verbatim
 
-                icalproperty_new_location(strdup(
+                icalproperty_new_location(
 \layout Verbatim
 
-                   "1CP Conference Room 4350")),
+                   "1CP Conference Room 4350"),
 \layout Verbatim
 
                 0
@@ -895,7 +900,7 @@ With the 'first' and 'next' routines, you can create a for loop to iterate
          c != 0; 
 \layout Verbatim
 
-         c = icalcomponent_get_next_component(comp,ICAL_ANY_COMPONENT))
+ c = icalcomponent_get_next_component(comp,ICAL_ANY_COMPONENT))
 \layout Verbatim
 
 { 
@@ -912,6 +917,78 @@ This code bit wil iterate through all of the subcomponents in 'comp' but
  to another component type.
 \layout Subsubsection
 
+Using Component Iterators
+\layout Standard
+
+The iteration model in the previous section requires the component to keep
+ the state of the iteration.
+ So, you could not use this model to perform a sorting operations, since
+ you'd need two iterators and there is only space for one.
+ If you ever call icalcomponent_get_first_component() which an iteration
+ is in progress, the pointer will be reset to the beginning.
+ 
+\layout Standard
+
+To solve this problem, there are also external iterators for components.
+ The routines associated with these external iterators are: 
+\layout Verbatim
+
+icalcompiter icalcomponent_begin_component(icalcomponent* component, icalcompone
+nt_kind kind);
+\layout Verbatim
+
+icalcompiter icalcomponent_end_component(icalcomponent* component, icalcomponent
+_kind kind);
+\layout Verbatim
+
+icalcomponent* icalcompiter_next(icalcompiter* i); 
+\layout Verbatim
+
+icalcomponent* icalcompiter_prior(icalcompiter* i); 
+\layout Verbatim
+
+icalcomponent* icalcompiter_deref(icalcompiter* i);
+\layout Standard
+
+The _begin_() and _end_() routines return a new iterator that points to
+ the begining and ending of the list of subcomponent for the given component,
+ and the kind argument works like the kind argument for internal iterators.
+ 
+\layout Standard
+
+After creating an iterators, use _next_() and _prior_() to step forward
+ and backward through the list and get the component that the iterator points
+ to, and use _deref() to return the component that the iterator points to
+ without moving the iterator.
+ All routines will return 0 when they move to point off the end of the list.
+ 
+\layout Standard
+
+Here is an example of a loop using these routines: 
+\layout Verbatim
+
+for(
+\layout Verbatim
+
+   i = icalcomponent_begin_component(impl->cluster,ICAL_ANY_COMPONENT);
+ 
+\layout Verbatim
+
+   icalcompiter_deref(&i)!= 0; 
+\layout Verbatim
+
+   icalcompiter_next(&i)
+\layout Verbatim
+
+) { 
+\layout Verbatim
+
+      icalcomponent *this = icalcompiter_deref(&i);
+\layout Verbatim
+
+}
+\layout Subsubsection
+
 Removing Components 
 \layout Standard
 
@@ -1061,19 +1138,72 @@ void icalproperty_remove_parameter(
      icalparameter_kind kind);
 \layout Subsubsection
 
-Getting Values 
-\layout Subsubsection
+Working with values
+\layout Standard
 
-Setting Values 
-\layout Subsubsection
+Values are typically part of a property, although they can exist on their
+ own.
+ You can maniplulate them either as part of the property or independantly.
+\layout Standard
 
-Getting Parameters
-\layout Subsubsection
+The most common way to work with values to is to maniplate them from they
+ properties that contain them.
+ This involves fewer routine calls and intermediate variables than working
+ with them independently, and it is type-safe.
+ 
+\layout Standard
+
+For each property, there are a _get_ and a _set_ routine that access the
+ internal value.
+ For instnace, for the UID property, the routines are: 
+\layout Verbatim
+
+void icalproperty_set_uid(icalproperty* prop, const char* v)
+\layout Verbatim
+
+const char* icalproperty_get_uid(icalproperty* prop)
+\layout Standard
+
+For multivalued properties, like ATTACH, the value type is usually a struct
+ or union that holds both possible types.
+ 
+\layout Standard
 
-Setting Parameters 
+If you want to work with the underlying value object, you can get and set
+ it with:
+\layout Verbatim
+
+icalvalue* icalproperty_get_value (icalproperty* prop)
+\layout Verbatim
+
+void icalproperty_set_value(icalproperty* prop, icalvalue* value);
+\layout Standard
+
+Icalproperty_get_value() will return a reference that you can manipluate
+ with other icalvalue routines.
+ Most of the time, you will have to know what the type of the value is.
+ For instance, if you know that the value is a DATETIME type, you can manipluate
+ it with: 
+\layout Verbatim
+
+struct icaltimetype icalvalue_get_datetime(icalvalue* value); 
+\layout Verbatim
+
+void icalvalue_set_datetime(icalvalue* value, struct icaltimetype v);
+\layout Standard
+
+When working with an extension property or value (and X-PROPERTY or a property
+ that has the parameter VALUE=x-name ) the value type is always a string.
+ To get and set the value, use: 
+\layout Verbatim
+
+void icalproperty_set_x(icalproperty* prop, char* v); 
+\layout Verbatim
+
+char* icalproperty_get_x(icalproperty* prop);
 \layout Subsubsection
 
-Removing Parameters 
+Working with parameters
 \layout Subsubsection
 
 Checking Component Validity
@@ -1086,7 +1216,7 @@ RFC 2446 defines rules for what properties must exist in a component to
  use to process a component.
  For instance, if the METHOD is REQUEST and the component is a VEVENT, the
  sender is probably asking the reciever to join in a meeting.
- I this case, RFC2446 says that the component must specify a start time
+ In this case, RFC2446 says that the component must specify a start time
  (DTSTART) and list the reciever as an attendee (ATTENDEE).
  
 \layout Standard
@@ -1170,6 +1300,170 @@ Remember that the string returned by these routines is owned by the library,
  
 \layout Subsection
 
+Time
+\layout Subsubsection
+
+Time structure
+\layout Standard
+
+LIbical defines it's own time structure for storing all dates and times.
+ It would have been nice to re-use the C library's 
+\emph on 
+struct tm, 
+\emph default 
+but that structure does not differentiate between dates and times, and between
+ local time and UTC.
+ The libical structure is:
+\layout Verbatim
+
+struct icaltimetype { 
+\layout Verbatim
+
+  int year; 
+\layout Verbatim
+
+  int month; 
+\layout Verbatim
+
+  int day; 
+\layout Verbatim
+
+  int hour; 
+\layout Verbatim
+
+  int minute; 
+\layout Verbatim
+
+  int second;
+\layout Verbatim
+
+  int is_utc; /* 1-> time is in UTC timezone */
+\layout Verbatim
+
+  int is_date; /* 1 -> interpret this as date.
+ */ }; 
+\layout Standard
+
+The year, month, day, hour, minute and second fields how the broken-out
+ time values.
+ The is_utc field distinguishes between times UTC and a local time zone.
+ The is_date field indicates if the intra-day fields hold valid data.
+ 
+\layout Subsubsection
+
+Time manipulating routines
+\layout Standard
+
+The null time value is used to indicate that the data in the structure is
+ not a valid time.
+\layout Verbatim
+
+struct icaltimetype icaltime_null_time(void);
+\layout Verbatim
+
+int icaltime_is_null_time(struct icaltimetype t);
+\layout Standard
+
+It is sensible for the broken-out time fields to contain values that are
+ not permitted in an ISO compliant time string.
+ For instance, the seconds field can hold values greater than 59, and the
+ hours field can hold values larger than 24.
+ The excessive values will be rolled over into the next larger field when
+ the structure is normalized.
+ 
+\layout Verbatim
+
+struct icaltimetype icaltime_normalize(struct icaltimetype t);
+\layout Standard
+
+There are several routines to get the day of the week or month, etc, from
+ a time structure.
+\layout Verbatim
+
+short icaltime_day_of_year(struct icaltimetype t); 
+\layout Verbatim
+
+struct icaltimetype icaltime_from_day_of_year(short doy, short year);
+\layout Verbatim
+
+short icaltime_day_of_week(struct icaltimetype t); 
+\layout Verbatim
+
+short icaltime_start_doy_of_week(struct icaltimetype t);
+\layout Verbatim
+
+short icaltime_week_number(short day_of_month, short month, short year);
+\layout Verbatim
+
+struct icaltimetype icaltime_from_week_number(short week_number, short year);
+\layout Verbatim
+
+short icaltime_days_in_month(short month,short year);
+\layout Standard
+
+Two routines convert time structures to and from the number of seconds since
+ the POSIX epoch.
+ The is_date field indicates wether or not the hour, minute and second fields
+ should be used in the conversion, and is_utc indicates if the value should
+ be converted to a local time or a UTC time, using the operating system
+ suppled notion of the local timezone.
+ 
+\layout Verbatim
+
+struct icaltimetype icaltime_from_timet(time_t v, int is_date, int is_utc);
+ 
+\layout Verbatim
+
+time_t icaltime_as_timet(struct icaltimetype);
+\layout Standard
+
+The compare routine works exactly like strcmp, but on time structures.
+ 
+\layout Verbatim
+
+int icaltime_compare(struct icaltimetype a,struct icaltimetype b);
+\layout Standard
+
+The following routines convert between UTC and a named timezone.
+ The tzid field must be a timezone name from the Olsen database, such as
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+America/Los_Angeles.
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\layout Standard
+
+The utc_offset routine returns the offset of the named time zone from UTC,
+ in seconds.
+ 
+\layout Standard
+
+The tt parmeter in the fonllowing routines indicates the date on which the
+ conversion should be made.
+ The tt parameter is necessary because timezones have many different rules
+ for when daylight savings time is used, and these rules can change over
+ time.
+ So, for a single timezone one year may have daylight savings time on March
+ 15, but for other years March 15 may be standard time, and some years may
+ have standard time all year.
+ 
+\layout Verbatim
+
+int icaltime_utc_offset(struct icaltimetype tt, char* tzid)
+\layout Verbatim
+
+struct icaltimetype icaltime_as_utc(struct icaltimetype tt,char* tzid);
+\layout Verbatim
+
+struct icaltimetype icaltime_as_zone(struct icaltimetype tt,char* tzid);
+\layout Verbatim
+
+\layout Subsection
+
 Storing Objects
 \layout Standard