diff options
Diffstat (limited to 'libical/doc')
| -rw-r--r-- | libical/doc/UsingLibical.lyx | 886 | ||||
| -rw-r--r-- | libical/doc/UsingLibical.txt | 80 |
2 files changed, 599 insertions, 367 deletions
diff --git a/libical/doc/UsingLibical.lyx b/libical/doc/UsingLibical.lyx index aa299de3c8..cef199bea5 100644 --- a/libical/doc/UsingLibical.lyx +++ b/libical/doc/UsingLibical.lyx @@ -1,8 +1,8 @@ #LyX 1.1 created this file. For more info see http://www.lyx.org/ \lyxformat 2.16 -\textclass linuxdoc +\textclass article \language default -\inputencoding default +\inputencoding latin1 \fontscheme default \graphics default \paperfontsize default @@ -59,7 +59,7 @@ Libical implements RFC2445, RFC2446 and some of RFC2447 and the CAP draft. This documentation assumes that you are familiar with the iCalendar standards RFC2445 and RFC2446. these specifications are online on the CALSCH webpage at: -\layout Verbatim +\layout LyX-Code http://www.imc.org/ietf-calendar/ \layout Subsection @@ -71,16 +71,16 @@ 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 -\layout Verbatim +\layout LyX-Code http://softwarestudio.org/libical/index.html \layout Standard and a mailing list that you can join by sending the following mail: -\layout Verbatim +\layout LyX-Code To: minimalist@softwarestudio.org -\layout Verbatim +\layout LyX-Code Subject: subscribe libical \layout Subsection @@ -128,7 +128,7 @@ src/test \layout Section -Building the Library +Building nas Installing the Library \layout Standard Libical uses autoconf to generate makefiles. @@ -143,6 +143,53 @@ Libical uses autoconf to generate makefiles. For a more complete guide to building the library, see the README file in the distribution. +\layout Standard + + +\begin_inset Quotes eld +\end_inset + +make install +\begin_inset Quotes erd +\end_inset + + will install the libraries and header files for three modules: libical, + libicalss. + and libicalvcal. + If you build shared objects, then these files will be installed: +\layout Itemize + +ical.h +\layout Itemize + +libical.a +\layout Itemize + +libical.so +\layout Itemize + +icalss.h +\layout Itemize + +libicalss.a +\layout Itemize + +libicalss.so +\layout Itemize + +icalvcal.h +\layout Itemize + +libicalvcal.a +\layout Itemize + +libicalvcal.so +\layout Standard + +The header files ical.h and icalss.h are combined header files, generated + by concatenating together all of the header files in src/libical and src/libica +lss respectively. + \layout Section Structure @@ -157,7 +204,7 @@ 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 -\layout Verbatim +\layout LyX-Code ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com \layout Standard @@ -215,61 +262,61 @@ END \added_space_bottom 0.3cm When a component is sent across a network, if it is un-encrypted, it will look something like: -\layout Verbatim +\layout LyX-Code BEGIN:VCALENDAR -\layout Verbatim +\layout LyX-Code METHOD:REQUEST -\layout Verbatim +\layout LyX-Code PRODID: -//hacksw/handcal//NONSGML v1.0//EN -\layout Verbatim +\layout LyX-Code BEGIN:VEVENT -\layout Verbatim +\layout LyX-Code DTSTAMP:19980309T231000Z -\layout Verbatim +\layout LyX-Code UID:guid-1.host1.com -\layout Verbatim +\layout LyX-Code ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com -\layout Verbatim +\layout LyX-Code ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP: -\layout Verbatim +\layout LyX-Code MAILTO:employee-A@host.com -\layout Verbatim +\layout LyX-Code DESCRIPTION:Project XYZ Review Meeting -\layout Verbatim +\layout LyX-Code CATEGORIES:MEETING -\layout Verbatim +\layout LyX-Code CLASS:PUBLIC -\layout Verbatim +\layout LyX-Code CREATED:19980309T130000Z -\layout Verbatim +\layout LyX-Code SUMMARY:XYZ Project Review -\layout Verbatim +\layout LyX-Code DTSTART;TZID=US-Eastern:19980312T083000 -\layout Verbatim +\layout LyX-Code DTEND;TZID=US-Eastern:19980312T093000 -\layout Verbatim +\layout LyX-Code LOCATION:1CP Conference Room 4350 -\layout Verbatim +\layout LyX-Code END:VEVENT -\layout Verbatim +\layout LyX-Code END:VCALENDAR \layout Standard @@ -277,21 +324,49 @@ END:VCALENDAR Note that components can be nested; this example has both a VCALENDAR and a VEVENT component, one nested inside the other. +\layout Standard + +The main goal of Libical is to offer a structured, type-safe to create, + access and manipulate components and their properties, values and parameters. + \layout Subsection Core iCal classes \layout Standard Libical is an object-based, data-oriented library. + There are no real-objects, but the way the routines are named and organized + results in the same sort of encapsulations and abstraction that are major + features of Object-Orieted languages. Nearly all of the routines in the library are associated with an opaque data types and perform some operation on that data type. - Although the library does not actually have classes, we will use those - terms since the behavior of these associations of data and routines is - very similar to a class. + For instnace, a Property is declared as: +\layout LyX-Code + +icalproperty *prop; +\layout Standard + +Icalproperty is typedef'd to void, so the only way to manipulate it is through + the accessor routines, all of which have a form similar to: +\layout LyX-Code + +char* icalproperty_as_ical_string(icalproperty* prop); +\layout Standard + +That is, the name of the 'class' is the first word in the routine name, + and the first parameter is a pointer to the 'object.' +\layout Standard + +Although the library does not actually have classes, we will use those terms + since the behavior of these associations of data and routines is very similar + to a class. \layout Subsubsection Properties +\layout LyX-Code + +icalproperty *prop; \layout Standard Properties are represented with the icalproperty class and its many @@ -318,6 +393,9 @@ derived \layout Subsubsection Components +\layout LyX-Code + +icalcomponent *comp; \layout Standard In libical, components are represented with the icalcomponent class. @@ -325,6 +403,9 @@ In libical, components are represented with the icalcomponent class. \layout Subsubsection Values +\layout LyX-Code + +icalvalue *value; \layout Standard Values are represented in a similar way to properties; a base class and @@ -339,10 +420,15 @@ derived classes. A value is essentially a abstract handle on a single fundamental type, a structure or a union. + You probably will never use a value directly, since for most operations + you can get to its data through the property that holds it. \layout Subsubsection Parameters +\layout LyX-Code + +icalparameter *param; \layout Standard Parameters are represetned in a similar way to properties, except that they @@ -360,7 +446,7 @@ In addition to the core iCal classes, libical has many other types, structures, Enumerations and types \layout Standard -Libical is strongly typed, soo every component, property, parameter, and +Libical is strongly typed, so every component, property, parameter, and value type has an enumeration, and some have an associated structure or union. @@ -513,11 +599,7 @@ It is natural to have interfaces that would return the value of a property, 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 - -\noun on -struct icaltriggertype -\noun default -. + struct icaltriggertype. This type is a union of a DURATION and a DATE-TIME. \layout Subsection @@ -532,16 +614,16 @@ S property can have multiple value instances. 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, -\layout Verbatim +\layout LyX-Code CATEGORIES: work, home \layout Standard becomes in libical's internal representation -\layout Verbatim +\layout LyX-Code CATEGORIES: work -\layout Verbatim +\layout LyX-Code CATEGORIES: home \layout Standard @@ -562,10 +644,20 @@ Using libical Creating Components \layout Standard -There are three ways to create components in Libical: creating individual - objects and assembling them, building entire objects in massive vaargs - calls, and parsing a text file containing iCalendar data. - +There are three ways to create components in Libical: +\layout Itemize + +Create individual components, properties and parameters and assemble them + into structures +\layout Itemize + +Build complete components with nested vaargs calls +\layout Itemize + +Parse bits of text +\layout Itemize + +Parse entire files \layout Subsubsection Constructor Interfaces @@ -573,43 +665,51 @@ Constructor Interfaces Using constructor interfaces, you create each of the objects separately and then assemble them in to components: -\layout Verbatim +\layout LyX-Code icalcomponent *event; -\layout Verbatim +\layout LyX-Code icalproperty *prop; -\layout Verbatim +\layout LyX-Code icalparameter *param; -\layout Verbatim +\layout LyX-Code struct icaltimetype atime; -\layout Verbatim +\layout LyX-Code + +\layout LyX-Code event = icalcomponent_new(ICAL_VEVENT_COMPONENT); -\layout Verbatim +\layout LyX-Code -prop = icalproperty_new_dtstamp(atime) ; -\layout Verbatim +prop = icalproperty_new_dtstamp(atime); +\layout LyX-Code icalcomponent_add_property(event, prop); -\layout Verbatim +\layout LyX-Code + +\layout LyX-Code prop = icalproperty_new_uid(''guid-1.host1.com'') ); -\layout Verbatim +\layout LyX-Code icalcomponent_add_property(event,prop); -\layout Verbatim +\layout LyX-Code + +\layout LyX-Code prop=icalproperty_new_organizer(''mrbig@host.com''); -\layout Verbatim +\layout LyX-Code param = icalparameter_new_role(ICAL_ROLE_CHAIR) -\layout Verbatim +\layout LyX-Code icalproperty_add_parameter(prop, param); -\layout Verbatim +\layout LyX-Code + +\layout LyX-Code icalcomponent_add_property(event,prop); \layout Standard @@ -654,91 +754,91 @@ There is another way to create complex components, which is arguably more in a single block of code. Here is the previous examples in the vaargs style. -\layout Verbatim +\layout LyX-Code calendar = -\layout Verbatim +\layout LyX-Code icalcomponent_vanew( -\layout Verbatim +\layout LyX-Code ICAL_VCALENDAR_COMPONENT, -\layout Verbatim +\layout LyX-Code icalproperty_new_version(''2.0''), -\layout Verbatim +\layout LyX-Code icalproperty_new_prodid( -\layout Verbatim +\layout LyX-Code ''-//RDU Software//NONSGML HandCal//EN''), -\layout Verbatim +\layout LyX-Code icalcomponent_vanew( -\layout Verbatim +\layout LyX-Code ICAL_VEVENT_COMPONENT, -\layout Verbatim +\layout LyX-Code icalproperty_new_dtstamp(atime), -\layout Verbatim +\layout LyX-Code icalproperty_new_uid(''guid-1.host1.com''), -\layout Verbatim +\layout LyX-Code icalproperty_vanew_organizer( -\layout Verbatim +\layout LyX-Code ''mrbig@host.com''), -\layout Verbatim +\layout LyX-Code icalparameter_new_role(ICAL_ROLE_CHAIR), -\layout Verbatim +\layout LyX-Code 0 -\layout Verbatim +\layout LyX-Code ), -\layout Verbatim +\layout LyX-Code icalproperty_vanew_attendee( -\layout Verbatim +\layout LyX-Code ''employee-A@host.com'', -\layout Verbatim +\layout LyX-Code icalparameter_new_role( -\layout Verbatim +\layout LyX-Code ICAL_ROLE_REQPARTICIPANT), -\layout Verbatim +\layout LyX-Code icalparameter_new_rsvp(1), -\layout Verbatim +\layout LyX-Code icalparameter_new_cutype(ICAL_CUTYPE_GROUP), -\layout Verbatim +\layout LyX-Code 0 -\layout Verbatim +\layout LyX-Code ), -\layout Verbatim +\layout LyX-Code icalproperty_new_location( -\layout Verbatim +\layout LyX-Code "1CP Conference Room 4350"), -\layout Verbatim +\layout LyX-Code 0 -\layout Verbatim +\layout LyX-Code ), -\layout Verbatim +\layout LyX-Code 0 -\layout Verbatim +\layout LyX-Code ); \layout Standard @@ -769,41 +869,63 @@ new \layout Subsubsection -Parsing Text Files +Parsing Text +\layout Standard + +Several routines are available for generating objects from text. + For properties, use: +\layout LyX-Code + +icalproperty* p; +\layout LyX-Code + +p = icalproperty_new_from_string("DTSTART:19970101T120000Z +\backslash +n"); +\layout Standard + +For parameters, use: +\layout LyX-Code + +icalparameter *param +\layout LyX-Code + +param = icalparameter_new_from_string("PARTSTAT=ACCEPTED"); \layout Standard The final way to create components will probably be the most common; you can create components from RFC2445 compliant text. If you have the string in memory, use -\layout Verbatim +\layout LyX-Code -icalcomponent* icalparser_parse_string(char* str); +icalcomponent* icalcomponent_new_from_string(char* str); \layout Standard -If the string contains only one component, the parser will return the component +If the string contains only one component, the routine will return the component in libical form. If the string contains multiple components, the multiple components will be returned as the children of an ICAL_XROOT_COMPONENT component. - + This routine is identical to ( and actually uses ) icalparser_parse_string(char +* str). \layout Standard Parsing a whole string may seem wasteful if you want to pull a large component off of the network or from a file; you may prefer to parse the component line by line. This is possible too by using: -\layout Verbatim +\layout LyX-Code icalparser* icalparser_new(); -\layout Verbatim +\layout LyX-Code void icalparser_free(icalparser* parser); -\layout Verbatim +\layout LyX-Code icalparser_get_line(parser,read_stream); -\layout Verbatim +\layout LyX-Code icalparser_add_line(parser,line); -\layout Verbatim +\layout LyX-Code icalparser_set_gen_data(parser,stream) \layout Standard @@ -813,74 +935,74 @@ These routines will construct a parser object to which you can add lines These routines work by specifing an adaptor routine to get string data from a source. For an example: -\layout Verbatim +\layout LyX-Code char* read_stream(char *s, size_t size, void *d) -\layout Verbatim +\layout LyX-Code { -\layout Verbatim +\layout LyX-Code char *c = fgets(s,size, (FILE*)d); -\layout Verbatim +\layout LyX-Code return c; -\layout Verbatim +\layout LyX-Code } -\layout Verbatim +\layout LyX-Code main() { -\layout Verbatim +\layout LyX-Code char* line; -\layout Verbatim +\layout LyX-Code icalcomponent *c; -\layout Verbatim +\layout LyX-Code icalparser *parser = icalparser_new(); -\layout Verbatim +\layout LyX-Code FILE* stream = fopen(argv[1],"r"); -\layout Verbatim +\layout LyX-Code icalparser_set_gen_data(parser,stream); -\layout Verbatim +\layout LyX-Code do{ -\layout Verbatim +\layout LyX-Code line = icalparser_get_line(parser,read_stream); -\layout Verbatim +\layout LyX-Code c = icalparser_add_line(parser,line); -\layout Verbatim +\layout LyX-Code if (c != 0){ -\layout Verbatim +\layout LyX-Code printf("%s",icalcomponent_as_ical_string(c)); -\layout Verbatim +\layout LyX-Code icalparser_claim(parser); -\layout Verbatim +\layout LyX-Code printf(" \backslash n--------------- \backslash n"); -\layout Verbatim +\layout LyX-Code icalcomponent_free(c); -\layout Verbatim +\layout LyX-Code } -\layout Verbatim +\layout LyX-Code } while ( line != 0); -\layout Verbatim +\layout LyX-Code } \layout Standard @@ -908,10 +1030,10 @@ Using the same mechanism, other implementations could read from memory buffers, Since the example code is a very common way to use the parser, there is a convenience routine; -\layout Verbatim +\layout LyX-Code icalcomponent* icalparser_parse(icalparser *parser, -\layout Verbatim +\layout LyX-Code char* (*line_gen_func)(char *s, size_t size, void* d)) \layout Standard @@ -932,7 +1054,7 @@ Accessing Components Given a reference to a component, you probably will want to access the propertie s, parameters and values inside. - Libical interfaces let you find sub-component, add and remove sub-components, + Libical interfaces let you find sub-components, add and remove sub-components, and do the same three operations on properties. \layout Subsubsection @@ -941,38 +1063,38 @@ Finding Components \layout Standard To find a sub-component of a component, use: -\layout Verbatim +\layout LyX-Code icalcomponent* icalcomponent_get_first_component( -\layout Verbatim +\layout LyX-Code icalcomponent* component, -\layout Verbatim +\layout LyX-Code icalcomponent_kind kind); \layout Standard This routine will return a reference to the first component of the type 'kind.' The key kind values, listed in icalenums.h are: -\layout Verbatim +\layout LyX-Code ICAL_ANY_COMPONENT -\layout Verbatim +\layout LyX-Code ICAL_VEVENT_COMPONENT -\layout Verbatim +\layout LyX-Code ICAL_VTODO_COMPONENT -\layout Verbatim +\layout LyX-Code ICAL_VJOURNAL_COMPONENT -\layout Verbatim +\layout LyX-Code ICAL_VCALENDAR_COMPONENT -\layout Verbatim +\layout LyX-Code ICAL_VFREEBUSY_COMPONENT -\layout Verbatim +\layout LyX-Code ICAL_VALARM_COMPONENT \layout Standard @@ -992,35 +1114,35 @@ Iterating Through Components Iteration requires a second routine to get the next subcomponent after the first: -\layout Verbatim +\layout LyX-Code icalcomponent* icalcomponent_get_next_component( -\layout Verbatim +\layout LyX-Code icalcomponent* component, -\layout Verbatim +\layout LyX-Code icalcomponent_kind kind); \layout Standard With the 'first' and 'next' routines, you can create a for loop to iterate through all of a components subcomponents -\layout Verbatim +\layout LyX-Code for(c = icalcomponent_get_first_component(comp,ICAL_ANY_COMPONENT); -\layout Verbatim +\layout LyX-Code c != 0; -\layout Verbatim +\layout LyX-Code c = icalcomponent_get_next_component(comp,ICAL_ANY_COMPONENT)) -\layout Verbatim +\layout LyX-Code { -\layout Verbatim +\layout LyX-Code do_something(c); -\layout Verbatim +\layout LyX-Code } \layout Standard @@ -1044,21 +1166,21 @@ The iteration model in the previous section requires the component to keep To solve this problem, there are also external iterators for components. The routines associated with these external iterators are: -\layout Verbatim +\layout LyX-Code icalcompiter icalcomponent_begin_component(icalcomponent* component, icalcompone nt_kind kind); -\layout Verbatim +\layout LyX-Code icalcompiter icalcomponent_end_component(icalcomponent* component, icalcomponent _kind kind); -\layout Verbatim +\layout LyX-Code icalcomponent* icalcompiter_next(icalcompiter* i); -\layout Verbatim +\layout LyX-Code icalcomponent* icalcompiter_prior(icalcompiter* i); -\layout Verbatim +\layout LyX-Code icalcomponent* icalcompiter_deref(icalcompiter* i); \layout Standard @@ -1078,26 +1200,26 @@ After creating an iterators, use _next_() and _prior_() to step forward \layout Standard Here is an example of a loop using these routines: -\layout Verbatim +\layout LyX-Code for( -\layout Verbatim +\layout LyX-Code i = icalcomponent_begin_component(impl->cluster,ICAL_ANY_COMPONENT); -\layout Verbatim +\layout LyX-Code icalcompiter_deref(&i)!= 0; -\layout Verbatim +\layout LyX-Code icalcompiter_next(&i) -\layout Verbatim +\layout LyX-Code ) { -\layout Verbatim +\layout LyX-Code icalcomponent *this = icalcompiter_deref(&i); -\layout Verbatim +\layout LyX-Code } \layout Subsubsection @@ -1113,26 +1235,26 @@ Removing an element from a list while iterating through the list with the per iteration, and you will remove only every other component. To avoid the problem, you will need to step the iterator ahead of the element you are going to remove, like this: -\layout Verbatim +\layout LyX-Code for(c = icalcomponent_get_first_component(parent_comp,ICAL_ANY_COMPONENT); -\layout Verbatim +\layout LyX-Code c != 0; -\layout Verbatim +\layout LyX-Code c = next -\layout Verbatim +\layout LyX-Code { -\layout Verbatim +\layout LyX-Code next = icalcomponent_get_next_component(parent_comp,ICAL_ANY_COMPONENT); -\layout Verbatim +\layout LyX-Code icalcomponent_remove_component(parent_comp,c); -\layout Verbatim +\layout LyX-Code } \layout Standard @@ -1142,29 +1264,29 @@ remove_component: if component iterator in the parent component is pointing to the child that will be removed, it will move the iterator to the component after the child. The following code will exploit this behavior: -\layout Verbatim +\layout LyX-Code icalcomponent_get_first_component(parent_comp,ICAL_VEVENT_COMPONENT); -\layout Verbatim +\layout LyX-Code while((c=icalcomponent_get_current_component(c)) != 0 ){ -\layout Verbatim +\layout LyX-Code if(icalcomponent_isa(c) == ICAL_VEVENT_COMPONENT){ -\layout Verbatim +\layout LyX-Code icalcomponent_remove_component(parent_comp,inner); -\layout Verbatim +\layout LyX-Code } else { -\layout Verbatim +\layout LyX-Code icalcomponent_get_next_component(parent_comp,ICAL_VEVENT_COMPONENT); -\layout Verbatim +\layout LyX-Code } -\layout Verbatim +\layout LyX-Code } \layout Subsubsection @@ -1175,79 +1297,79 @@ Working with properties and parameters Finding, iterating and removing properties works the same as it does for components, using the property-specific or parameter-specific interfaces: -\layout Verbatim +\layout LyX-Code icalproperty* icalcomponent_get_first_property( -\layout Verbatim +\layout LyX-Code icalcomponent* component, -\layout Verbatim +\layout LyX-Code icalproperty_kind kind); -\layout Verbatim +\layout LyX-Code icalproperty* icalcomponent_get_next_property( -\layout Verbatim +\layout LyX-Code icalcomponent* component, -\layout Verbatim +\layout LyX-Code icalproperty_kind kind); -\layout Verbatim +\layout LyX-Code void icalcomponent_add_property( -\layout Verbatim +\layout LyX-Code icalcomponent* component, -\layout Verbatim +\layout LyX-Code icalproperty* property); -\layout Verbatim +\layout LyX-Code void icalcomponent_remove_property( -\layout Verbatim +\layout LyX-Code icalcomponent* component, -\layout Verbatim +\layout LyX-Code icalproperty* property); \layout Standard For parameters: -\layout Verbatim +\layout LyX-Code icalparameter* icalproperty_get_first_parameter( -\layout Verbatim +\layout LyX-Code icalproperty* prop, -\layout Verbatim +\layout LyX-Code icalparameter_kind kind); -\layout Verbatim +\layout LyX-Code icalparameter* icalproperty_get_next_parameter( -\layout Verbatim +\layout LyX-Code icalproperty* prop, -\layout Verbatim +\layout LyX-Code icalparameter_kind kind); -\layout Verbatim +\layout LyX-Code void icalproperty_add_parameter( -\layout Verbatim +\layout LyX-Code icalproperty* prop, -\layout Verbatim +\layout LyX-Code icalparameter* parameter); -\layout Verbatim +\layout LyX-Code void icalproperty_remove_parameter( -\layout Verbatim +\layout LyX-Code icalproperty* prop, -\layout Verbatim +\layout LyX-Code icalparameter_kind kind); \layout Standard @@ -1274,10 +1396,10 @@ The most common way to work with values to is to manipulate them from they For each property, there are a _get_ and a _set_ routine that access the internal value. For instanace, for the UID property, the routines are: -\layout Verbatim +\layout LyX-Code void icalproperty_set_uid(icalproperty* prop, const char* v) -\layout Verbatim +\layout LyX-Code const char* icalproperty_get_uid(icalproperty* prop) \layout Standard @@ -1289,10 +1411,10 @@ For multi-valued properties, like ATTACH, the value type is usually a struct If you want to work with the underlying value object, you can get and set it with: -\layout Verbatim +\layout LyX-Code icalvalue* icalproperty_get_value (icalproperty* prop) -\layout Verbatim +\layout LyX-Code void icalproperty_set_value(icalproperty* prop, icalvalue* value); \layout Standard @@ -1302,10 +1424,10 @@ Icalproperty_get_value() will return a reference that you can manipulate 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 manipulate it with: -\layout Verbatim +\layout LyX-Code struct icaltimetype icalvalue_get_datetime(icalvalue* value); -\layout Verbatim +\layout LyX-Code void icalvalue_set_datetime(icalvalue* value, struct icaltimetype v); \layout Standard @@ -1313,20 +1435,20 @@ void icalvalue_set_datetime(icalvalue* value, struct icaltimetype v); 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 +\layout LyX-Code void icalproperty_set_x(icalproperty* prop, char* v); -\layout Verbatim +\layout LyX-Code char* icalproperty_get_x(icalproperty* prop); \layout Standard All X properties have the type of ICAL_X_PROPERTY, so you will need these routines to get and set the name of the property: -\layout Verbatim +\layout LyX-Code char* icalproperty_get_x_name(icalproperty* prop) -\layout Verbatim +\layout LyX-Code void icalproperty_set_x_name(icalproperty* prop, char* name); \layout Subsubsection @@ -1347,7 +1469,7 @@ RFC 2446 defines rules for what properties must exist in a component to \layout Standard Libical can check these restrictions with the routine: -\layout Verbatim +\layout LyX-Code int icalrestriction_check(icalcomponent* comp); \layout Standard @@ -1373,16 +1495,16 @@ Converting Components to Text To create an RFC2445 compliant text representation of an object, use one of the *_as_ical_string() routines: -\layout Verbatim +\layout LyX-Code char* icalcomponent_as_ical_string (icalcomponent* component) -\layout Verbatim +\layout LyX-Code char* icalproperty_as_ical_string (icalproperty* property) -\layout Verbatim +\layout LyX-Code char* icalparameter_as_ical_string (icalparameter* parameter) -\layout Verbatim +\layout LyX-Code char* icalvalue_as_ical_string (icalvalue* value) \layout Standard @@ -1445,31 +1567,31 @@ struct tm, but that structure does not differentiate between dates and times, and between local time and UTC. The libical structure is: -\layout Verbatim +\layout LyX-Code struct icaltimetype { -\layout Verbatim +\layout LyX-Code int year; -\layout Verbatim +\layout LyX-Code int month; -\layout Verbatim +\layout LyX-Code int day; -\layout Verbatim +\layout LyX-Code int hour; -\layout Verbatim +\layout LyX-Code int minute; -\layout Verbatim +\layout LyX-Code int second; -\layout Verbatim +\layout LyX-Code int is_utc; /* 1-> time is in UTC timezone */ -\layout Verbatim +\layout LyX-Code int is_date; /* 1 -> interpret this as date. */ }; @@ -1489,19 +1611,18 @@ Creating time structures \layout Standard There are several ways to create a new icaltimetype structure: -\layout Verbatim +\layout LyX-Code struct icaltimetype icaltime_from_string(const char* str); -\layout Verbatim +\layout LyX-Code struct icaltimetype icaltime_from_timet(time_t v, int is_date); -\layout Verbatim +\layout LyX-Code -struct icaltimetype icaltime_from_int(int v, int is_date, int is_utc); \layout Standard Icaltime_from_string takes any RFC2445 compliant time string: -\layout Verbatim +\layout LyX-Code struct icaltimetype tt = icaltime_from_string("19970101T103000"); \layout Standard @@ -1513,12 +1634,6 @@ Icaltime_from_timet takes a timet value, representing seconds past the POSIX Dates act differently in sorting an comparision, and they have a different string representation in RFC2445. -\layout Standard - -The icaltime_from_int is like icaltime_from_timet, but with an arbitrary - epoch. - This routine was a mistake and is deprecated. - \layout Subsubsection Time manipulating routines @@ -1526,10 +1641,10 @@ Time manipulating routines The null time value is used to indicate that the data in the structure is not a valid time. -\layout Verbatim +\layout LyX-Code struct icaltimetype icaltime_null_time(void); -\layout Verbatim +\layout LyX-Code int icaltime_is_null_time(struct icaltimetype t); \layout Standard @@ -1541,14 +1656,14 @@ It is sensible for the broken-out time fields to contain values that are The excessive values will be rolled over into the next larger field when the structure is normalized. -\layout Verbatim +\layout LyX-Code struct icaltimetype icaltime_normalize(struct icaltimetype t); \layout Standard Normalizing allows you to do arithmetic operations on time values. -\layout Verbatim +\layout LyX-Code struct icaltimetype tt = icaltime_from_string( \begin_inset Quotes eld @@ -1559,38 +1674,38 @@ struct icaltimetype tt = icaltime_from_string( \end_inset ); -\layout Verbatim +\layout LyX-Code tt.days +=3 -\layout Verbatim +\layout LyX-Code tt.second += 70; -\layout Verbatim +\layout LyX-Code tt = icaltime_normalize(tt); \layout Standard There are several routines to get the day of the week or month, etc, from a time structure. -\layout Verbatim +\layout LyX-Code short icaltime_day_of_year(struct icaltimetype t); -\layout Verbatim +\layout LyX-Code struct icaltimetype icaltime_from_day_of_year(short doy, short year); -\layout Verbatim +\layout LyX-Code short icaltime_day_of_week(struct icaltimetype t); -\layout Verbatim +\layout LyX-Code short icaltime_start_doy_of_week(struct icaltimetype t); -\layout Verbatim +\layout LyX-Code short icaltime_week_number(short day_of_month, short month, short year); -\layout Verbatim +\layout LyX-Code struct icaltimetype icaltime_from_week_number(short week_number, short year); -\layout Verbatim +\layout LyX-Code short icaltime_days_in_month(short month,short year); \layout Standard @@ -1599,17 +1714,17 @@ Two routines convert time structures to and from the number of seconds since the POSIX epoch. The is_date field indicates whether or not the hour, minute and second fields should be used in the conversion. -\layout Verbatim +\layout LyX-Code struct icaltimetype icaltime_from_timet(time_t v, int is_date); -\layout Verbatim +\layout LyX-Code time_t icaltime_as_timet(struct icaltimetype); \layout Standard The compare routine works exactly like strcmp, but on time structures. -\layout Verbatim +\layout LyX-Code int icaltime_compare(struct icaltimetype a,struct icaltimetype b); \layout Standard @@ -1641,19 +1756,19 @@ The tt parameter in the following routines indicates the date on which the 15, but for other years March 15 may be standard time, and some years may have standard time all year. -\layout Verbatim +\layout LyX-Code int icaltime_utc_offset(struct icaltimetype tt, char* tzid); -\layout Verbatim +\layout LyX-Code int icaltime_local_utc_offset(); -\layout Verbatim +\layout LyX-Code struct icaltimetype icaltime_as_utc(struct icaltimetype tt,char* tzid); -\layout Verbatim +\layout LyX-Code struct icaltimetype icaltime_as_zone(struct icaltimetype tt,char* tzid); -\layout Verbatim +\layout LyX-Code struct icaltimetype icaltime_as_local(struct icaltimetype tt); \layout Subsection @@ -1678,60 +1793,60 @@ The file storage routines are organized in an inheritance heirarchy that \layout Standard All of the icalset derived classes have the same interface: -\layout Verbatim +\layout LyX-Code -\layout Verbatim +\layout LyX-Code icaldirset* icaldirset_new(const char* path); -\layout Verbatim +\layout LyX-Code void icaldirset_free(icaldirset* store); -\layout Verbatim +\layout LyX-Code const char* icaldirset_path(icaldirset* store); -\layout Verbatim +\layout LyX-Code void icaldirset_mark(icaldirset* store); -\layout Verbatim +\layout LyX-Code icalerrorenum icaldirset_commit(icaldirset* store); -\layout Verbatim +\layout LyX-Code icalerrorenum icaldirset_add_component(icaldirset* store, icalcomponent* comp); -\layout Verbatim +\layout LyX-Code icalerrorenum icaldirset_remove_component(icaldirset* store, icalcomponent* comp); -\layout Verbatim +\layout LyX-Code int icaldirset_count_components(icaldirset* store, icalcomponent_kind kind); -\layout Verbatim +\layout LyX-Code icalerrorenum icaldirset_select(icaldirset* store, icalcomponent* gauge); -\layout Verbatim +\layout LyX-Code void icaldirset_clear(icaldirset* store); -\layout Verbatim +\layout LyX-Code icalcomponent* icaldirset_fetch(icaldirset* store, const char* uid); -\layout Verbatim +\layout LyX-Code int icaldirset_has_uid(icaldirset* store, const char* uid); -\layout Verbatim +\layout LyX-Code icalcomponent* icaldirset_fetch_match(icaldirset* set, icalcomponent *c); -\layout Verbatim +\layout LyX-Code icalerrorenum icaldirset_modify(icaldirset* store, icalcomponent *oldc, icalcomponent *newc); -\layout Verbatim +\layout LyX-Code icalcomponent* icaldirset_get_current_component(icaldirset* store); -\layout Verbatim +\layout LyX-Code icalcomponent* icaldirset_get_first_component(icaldirset* store); -\layout Verbatim +\layout LyX-Code icalcomponent* icaldirset_get_next_component(icaldirset* store); \layout Subsubsection @@ -1741,26 +1856,26 @@ Creating a new set You can create a new set from either the base class or the direved class. From the base class use one of: -\layout Verbatim +\layout LyX-Code icalset* icalset_new_file(const char* path); -\layout Verbatim +\layout LyX-Code icalset* icalset_new_dir(const char* path); -\layout Verbatim +\layout LyX-Code icalset* icalset_new_heap(void); -\layout Verbatim +\layout LyX-Code icalset* icalset_new_mysql(const char* path); \layout Standard You can also create a new set based on the derived class, For instance, with icalfileset: -\layout Verbatim +\layout LyX-Code icalfileset* icalfileset_new(const char* path); -\layout Verbatim +\layout LyX-Code icalfileset* icalfileset_new_open(const char* path, int flags, mode_t mode); \layout Standard @@ -1786,7 +1901,7 @@ Adding, Finding and Removing Components \layout Standard To add components to a set, use: -\layout Verbatim +\layout LyX-Code icalerrorenum icalfileset_add_component(icalfileset* cluster, icalcomponent* child); @@ -1795,10 +1910,10 @@ icalerrorenum icalfileset_add_component(icalfileset* cluster, icalcomponent* The fileset keeps an inmemory copy of the components, and this set must be written back to the file ocassionally. There are two routines to manage this: -\layout Verbatim +\layout LyX-Code void icalfileset_mark(icalfileset* cluster); -\layout Verbatim +\layout LyX-Code icalerrorenum icalfileset_commit(icalfileset* cluster); \layout Standard @@ -1812,13 +1927,13 @@ Icalfileset_mark indicates that the in-memory components have changed. \layout Standard To iterate through the components in a set, use: -\layout Verbatim +\layout LyX-Code icalcomponent* icalfileset_get_first_component(icalfileset* cluster); -\layout Verbatim +\layout LyX-Code icalcomponent* icalfileset_get_next_component(icalfileset* cluster); -\layout Verbatim +\layout LyX-Code icalcomponent* icalfileset_get_current_component (icalfileset* cluster); @@ -1829,160 +1944,160 @@ These routines work like the corresponding routines from icalcomponent, A gauge is a test for the properties within a components; only components that pass the test are returned. A gauge can be constructed from a MINSQL string with: -\layout Verbatim +\layout LyX-Code icalgauge* icalgauge_new_from_sql(char* sql); \layout Standard Then, you can add the gauge to the set with : -\layout Verbatim +\layout LyX-Code icalerrorenum icalfileset_select(icalfileset* store, icalgauge* gauge); \layout Standard Here is an example that puts all of these routines together: -\layout Verbatim +\layout LyX-Code \latex no_latex void test_fileset() -\layout Verbatim +\layout LyX-Code \latex no_latex { -\layout Verbatim +\layout LyX-Code \latex no_latex icalfileset *fs; -\layout Verbatim +\layout LyX-Code \latex no_latex icalcomponent *c; -\layout Verbatim +\layout LyX-Code \latex no_latex int i; -\layout Verbatim +\layout LyX-Code \latex no_latex char *path = "test_fileset.ics"; -\layout Verbatim +\layout LyX-Code \latex no_latex icalgauge *g = icalgauge_new_from_sql( -\layout Verbatim +\layout LyX-Code \latex no_latex "SELECT * FROM VEVENT WHERE DTSTART > '20000103T120000Z' AND DTSTART <= '20000106T120000Z'"); -\layout Verbatim +\layout LyX-Code \latex no_latex -\layout Verbatim +\layout LyX-Code \latex no_latex fs = icalfileset_new(path); -\layout Verbatim +\layout LyX-Code -\layout Verbatim +\layout LyX-Code \latex no_latex for (i = 0; i!= 10; i++){ -\layout Verbatim +\layout LyX-Code \latex no_latex c = make_component(i); \latex default /* Make a new component where DTSTART has month of i */ -\layout Verbatim +\layout LyX-Code \latex no_latex icalfileset_add_component(fs,c); -\layout Verbatim +\layout LyX-Code \latex no_latex } -\layout Verbatim +\layout LyX-Code -\layout Verbatim +\layout LyX-Code \latex no_latex icalfileset_commit(fs); \latex default /* Write to disk */ -\layout Verbatim +\layout LyX-Code -\layout Verbatim +\layout LyX-Code \latex no_latex icalfileset_select(fs,g); \latex default /* Set the gauge to filter components */ -\layout Verbatim +\layout LyX-Code \latex no_latex -\layout Verbatim +\layout LyX-Code \latex no_latex for (c = icalfileset_get_first_component(fs); -\layout Verbatim +\layout LyX-Code \latex no_latex c != 0; -\layout Verbatim +\layout LyX-Code \latex no_latex c = icalfileset_get_next_component(fs)){ -\layout Verbatim +\layout LyX-Code \latex no_latex struct icaltimetype t = icalcomponent_get_dtstart(c); -\layout Verbatim +\layout LyX-Code \latex no_latex -\layout Verbatim +\layout LyX-Code \latex no_latex printf("%s \backslash n",icaltime_as_ctime(t)); -\layout Verbatim +\layout LyX-Code \latex no_latex } -\layout Verbatim +\layout LyX-Code \latex no_latex icalfileset_free(fs); -\layout Verbatim +\layout LyX-Code \latex no_latex @@ -2071,45 +2186,99 @@ lerror.h. be the same as icalerrno. You can use icalerror_strerror() to get a string that describes the error. The enumerations are: -\layout Itemize - -ICAL_BADARG_ERROR -- One of the argument to a routine was bad. - Typically for a null pointer. - -\layout Itemize - -ICAL_NEWFAILED_ERROR -- A new() or malloc() failed -\layout Itemize - -ICAL_MALFORMEDDATA_ERROR -- An input string was not in the correct format -\layout Itemize - -ICAL_PARSE_ERROR -- The parser failed to parse an incomming component -\layout Itemize - -ICAL_INTERNAL_ERROR -- Largely equivalent to an assert -\layout Itemize - -ICAL_FILE_ERROR -- A file operation failed. - Check errno for more detail. -\layout Itemize +\layout Standard +\added_space_top 0.3cm \added_space_bottom 0.3cm \align center \LyXTable +multicol5 +12 2 0 0 -1 -1 -1 -1 +1 1 0 0 +1 0 0 0 +1 0 0 0 +1 0 0 0 +1 0 0 0 +1 0 0 0 +1 0 0 0 +1 0 0 0 +1 0 0 0 +1 0 0 0 +1 0 0 0 +1 1 0 0 +2 1 0 "" "" +2 1 1 "" "" +0 8 1 0 0 0 0 "" "" +0 8 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" +0 2 1 0 0 0 0 "" "" -ICAL_ALLOCATION_ERROR -- ? -\layout Itemize -ICAL_USAGE_ERROR -- ? -\layout Itemize +\newline -ICAL_NO_ERROR -- No error -\layout Itemize +\newline +ICAL_BADARG_ERROR +\newline +One of the argument to a routine was bad. + Typically for a null pointer. +\newline +ICAL_NEWFAILED_ERROR +\newline +A new() or malloc() failed +\newline +ICAL_MALFORMEDDATA_ERROR +\newline +An input string was not in the correct format +\newline +ICAL_PARSE_ERROR +\newline +the parser failed to parse an incomming component +\newline +ICAL_INTERNAL_ERROR +\newline +Largely equivalent to an assert; it indicates a bug in the libical code +\newline +ICAL_FILE_ERROR +\newline +A file operation failed. + Check errno for more detai +\newline +ICAL_ALLOCATION_ERROR +\newline -ICAL_MULTIPLEINCLUSION_ERROR -- ? -\layout Itemize +\newline +ICAL_NO_ERROR +\newline +No error has occured +\newline +ICAL_TIMEDOUT_ERROR +\newline +Failed to acquire a lock on a file, or the CSTP protocol timed out. + +\newline +ICAL_MULTIPLEINCLUSION_ERROR +\newline -ICAL_TIMEDOUT_ERROR -- For CSTP and acquiring locks -\layout Itemize +\newline +ICAL_UNKNOWN_ERROR +\newline -ICAL_UNKNOWN_ERROR -- ? \layout Subsubsection X-LIC-ERROR and X-LIC-INVALID-COMPONENT @@ -2122,12 +2291,12 @@ The library handles semantic and syntactic errors in components by inserting the requirements of RFC2446 ( a semantic error) the library will insert properties of the type X-LIC-ERROR to describe the error. Here is an example of the error property: -\layout Verbatim +\layout LyX-Code X-LIC-ERROR;X-LIC-ERRORTYPE=INVALID_ITIP :Failed iTIP restrictions for property DTSTART. -\layout Verbatim +\layout LyX-Code Expected 1 instances of the property and got 0 \layout Standard @@ -2139,25 +2308,20 @@ This error resulted from a call to icalrestriction_check(), which discovered There are a few routines to manipulate error properties: \layout Standard - -[ The following data is supposed to be in a table. - It looks OK in LyX, but does not format propertly in output. - ] -\layout Standard \LyXTable multicol5 10 2 0 0 -1 -1 -1 -1 1 1 0 0 -1 0 0 0 +0 0 0 0 0 1 1 0 -1 0 0 0 +0 0 0 0 0 1 1 0 -1 1 0 0 +0 1 0 0 0 1 1 0 -1 1 0 0 +0 1 0 0 0 1 1 0 0 1 1 0 -2 1 0 "" "" +2 1 1 "" "" 2 1 1 "3in" "" 0 2 1 1 0 0 0 "" "" 0 8 1 0 0 0 0 "" "" @@ -2224,25 +2388,25 @@ process the component as an iTIP request. The types of errors are listed in icalerror.h. They are: -\layout Verbatim +\layout LyX-Code ICAL_XLICERRORTYPE_COMPONENTPARSEERROR -\layout Verbatim +\layout LyX-Code ICAL_XLICERRORTYPE_PARAMETERVALUEPARSEERROR -\layout Verbatim +\layout LyX-Code ICAL_XLICERRORTYPE_PARAMETERNAMEPARSEERROR -\layout Verbatim +\layout LyX-Code ICAL_XLICERRORTYPE_PROPERTYPARSEERROR -\layout Verbatim +\layout LyX-Code ICAL_XLICERRORTYPE_VALUEPARSEERROR -\layout Verbatim +\layout LyX-Code ICAL_XLICERRORTYPE_UNKVCALPROP -\layout Verbatim +\layout LyX-Code ICAL_XLICERRORTYPE_INVALIDITIP \layout Standard diff --git a/libical/doc/UsingLibical.txt b/libical/doc/UsingLibical.txt index 6dc4958a74..6b203d43d2 100644 --- a/libical/doc/UsingLibical.txt +++ b/libical/doc/UsingLibical.txt @@ -857,10 +857,11 @@ struct icaltimetype { int is_date; /* 1 -> interpret this as date. */ }; -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. +The year, month, day, hour, minute and second fields hold the broken-out +time values. The is_utc field distinguishes between times in UTC and +a local time zone. The is_date field indicates if the time should +be interpreted only as a date. If it is a date, the hour, minute and +second fields are assumed to be zero, regardless of their actual vaules. 5.3.2 Creating time structures @@ -878,7 +879,7 @@ struct icaltimetype tt = icaltime_from_string("19970101T103000"); Icaltime_from_timet takes a timet value, representing seconds past the POSIX epoch, and a flag to indicate if the time is a date. Dates -have an identical structure to a time, but they time portion ( hours, +have an identical structure to a time, but the time portion ( hours, minuts and seconds ) is always 00:00:00. Dates act differently in sorting an comparision, and they have a different string representation in RFC2445. @@ -1207,7 +1208,34 @@ Most routines will set the global error value icalerrno on errors. This variable is an enumeration; permissible values can be found in libical/icalerror.h. If the routine returns an enum icalerrorenum, then the return value will be the same as icalerrno. You can use icalerror_strerror() -to get a string that describes the error +to get a string that describes the error. The enumerations are: + +* ICAL_BADARG_ERROR -- One of the argument to a routine was bad. Typically + for a null pointer. + +* ICAL_NEWFAILED_ERROR -- A new() or malloc() failed + +* ICAL_MALFORMEDDATA_ERROR -- An input string was not in the correct + format + +* ICAL_PARSE_ERROR -- The parser failed to parse an incomming component + +* ICAL_INTERNAL_ERROR -- Largely equivalent to an assert + +* ICAL_FILE_ERROR -- A file operation failed. Check errno for more + detail. + +* ICAL_ALLOCATION_ERROR -- ? + +* ICAL_USAGE_ERROR -- ? + +* ICAL_NO_ERROR -- No error + +* ICAL_MULTIPLEINCLUSION_ERROR -- ? + +* ICAL_TIMEDOUT_ERROR -- For CSTP and acquiring locks + +* ICAL_UNKNOWN_ERROR -- ? 5.6.3 X-LIC-ERROR and X-LIC-INVALID-COMPONENT @@ -1284,6 +1312,16 @@ As of libical version0.18, this routine only convert *PARSEERROR errors and it always generates a 3.x ( failure ) code. This makes it more of a good idea than a really useful bit of code. +5.6.4 ICAL_ERRORS_ARE_FATAL and icalerror_errors_are_fatal + +If the global variable icalerror_errors_are_fatal is set to 1, then +any error condition will cause the program to abort. The abort occurs +in icalerror_set_errno(), and is done with an assert(0) if NDEBUG +is undefined, and with icalerror_crash_here if NDEBUG is defined. +The default value of icalerror_errors_are_fatal is 1 when ICAL_ERRORS_ARE_FATAL +is defined, and 0 otherwise. Since ICAL_ERRORS_ARE_FATAL is defined +by default, icalerror_errors_are_fatal is also defined by default. + 5.7 Naming Standard Structures that you access with the "struct" keyword, such as "struct @@ -1314,3 +1352,33 @@ are irregular. There are a lot of hacks in the library -- bits of code that I am not proud of and should probably be changed. These are marked with the comment string "HACK." + +7 Library Reference + +7.1 Manipulating struct icaltimetype + +7.1.1 Struct icaltimetype + +struct icaltimetype + +{ + + int year; + + int month; + + int day; + + int hour; + + int minute; + + int second; + + int is_utc; + + int is_date; + + const char* zone; + +}; |