summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorPatrick Elsen <pelsen@xfbs.net>2017-07-11 15:15:01 +0200
committerPatrick Elsen <pelsen@xfbs.net>2017-07-11 15:15:01 +0200
commitadb41eb26b4da4ea85249b2655bea336d1cf8c20 (patch)
tree5b5ec60970ea3409211ab9a7edad1ea76a405394 /doc
parentf1ed8b34e1fdacbd38bd2716242adf707f20a9e0 (diff)
downloadlibical-git-adb41eb26b4da4ea85249b2655bea336d1cf8c20.tar.gz
doc/UsingLibical.md - cleans up the example code, somewhat
Diffstat (limited to 'doc')
-rw-r--r--doc/UsingLibical.md629
1 files changed, 303 insertions, 326 deletions
diff --git a/doc/UsingLibical.md b/doc/UsingLibical.md
index fa21e589..28b26dc5 100644
--- a/doc/UsingLibical.md
+++ b/doc/UsingLibical.md
@@ -1,7 +1,8 @@
# Using Libical
-> Eric Busboom (eric@softwarestudio.org)
-> January 2001
+> Author: Eric Busboom <eric@softwarestudio.org>
+>
+> Date: January 2001
## 1 Introduction
@@ -87,41 +88,23 @@ will look something like:
```ical
BEGIN:VCALENDAR
-
METHOD:REQUEST
-
PRODID: -//hacksw/handcal//NONSGML v1.0//EN
-
BEGIN:VEVENT
-
DTSTAMP:19980309T231000Z
-
UID:guid-1.host1.com
-
ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com
-
ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP:
-
MAILTO:employee-A@host.com
-
DESCRIPTION:Project XYZ Review Meeting
-
CATEGORIES:MEETING
-
CLASS:PUBLIC
-
CREATED:19980309T130000Z
-
SUMMARY:XYZ Project Review
-
DTSTART;TZID=US-Eastern:19980312T083000
-
DTEND;TZID=US-Eastern:19980312T093000
-
LOCATION:1CP Conference Room 4350
-
END:VEVENT
-
END:VCALENDAR
```
@@ -210,15 +193,13 @@ like components, but are not defined as components in the specification.
group properties within the `VTIMEZONE` components. For instanace, the
timezone properties associated with daylight savings time starts with
`BEGIN:DAYLIGHT` and ends with `END:DAYLIGHT`, just like other components,
-but is not defined as a component in
-[RFC5545](https://tools.ietf.org/html/rfc5545)
-(see [section 3.6.5](https://tools.ietf.org/html/rfc5545#section-3.6.5))
+but is not defined as a component in [RFC5545][] (see [section 3.6.5][RFC5545 3.6.5])
In libical, this grouping is represented by the `XDAYLIGHT` component.
Standard iCal components all start with the letter "V," while pseudo
components start with "X."
There are also pseudo components that are conceptually derived classes
-of `VALARM`. RFC5546 defines what properties may be included in each
+of `VALARM`. [RFC5546][] 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.
@@ -231,6 +212,8 @@ To handle these various, complex restrictions, libical has pseudo components
for each type of alarm: `XAUDIOALARM`, `XDISPLAYALARM`, `XEMAILALARM` and
`XPROCEDUREALARM`.
+[RFC5545 3.6.5]: <https://tools.ietf.org/html/rfc5545#section-3.6.5>
+
### 4.2 Combined Values
Many values can take more than one type. `TRIGGER`, for instance, can
@@ -290,30 +273,26 @@ and then assemble them in to components:
```c
icalcomponent *event;
-
icalproperty *prop;
-
icalparameter *param;
-
struct icaltimetype atime;
+// create new VEVENT component
event = icalcomponent_new(ICAL_VEVENT_COMPONENT);
-prop = icalproperty_new_dtstamp(atime) ;
-
+// add DTSTAMP property to the event
+prop = icalproperty_new_dtstamp(atime);
icalcomponent_add_property(event, prop);
-prop = icalproperty_new_uid("guid-1.host1.com");
-
-icalcomponent_add_property(event,prop);
-
-prop=icalproperty_new_organizer("mrbig@host.com");
-
-param = icalparameter_new_role(ICAL_ROLE_CHAIR)
+// add UID property to the event
+prop = icalproperty_new_uid("guid-1.example.com");
+icalcomponent_add_property(event, prop);
+// add ORGANIZER (with ROLE=CHAIR) to the event
+prop = icalproperty_new_organizer("mrbig@example.com");
+param = icalparameter_new_role(ICAL_ROLE_CHAIR);
icalproperty_add_parameter(prop, param);
-
-icalcomponent_add_property(event,prop);
+icalcomponent_add_property(event, prop);
```
Notice that libical uses a semi-object-oriented style of interface.
@@ -329,7 +308,7 @@ reference, libical will either silently ignore the error or will abort
with an error message. This behavior is controlled by a compile time
flag (`ICAL_ERRORS_ARE_FATAL`), and will abort by default.
-5.1.2 varargs Constructors
+#### 5.1.2 varargs Constructors
There is another way to create complex components, which is arguably
more elegant, if you are not horrified by varargs. The varargs constructor
@@ -337,71 +316,42 @@ interface allows you to create intricate components in a single block
of code. Here is the previous examples in the vaargs style.
```c
- calendar =
+icalcomponent *calendar;
+struct icaltimetype atime;
+calendar =
+ icalcomponent_vanew(
+ ICAL_VCALENDAR_COMPONENT,
+ icalproperty_new_version("2.0"),
+ icalproperty_new_prodid(
+ "-//RDU Software//NONSGML HandCal//EN"),
icalcomponent_vanew(
-
- ICAL_VCALENDAR_COMPONENT,
-
- icalproperty_new_version(''2.0''),
-
- icalproperty_new_prodid(
-
- ''-//RDU Software//NONSGML HandCal//EN''),
-
- icalcomponent_vanew(
-
- ICAL_VEVENT_COMPONENT,
-
- icalproperty_new_dtstamp(atime),
-
- icalproperty_new_uid(''guid-1.host1.com''),
-
- icalproperty_vanew_organizer(
-
- ''mrbig@host.com''),
-
- icalparameter_new_role(ICAL_ROLE_CHAIR),
-
- 0
-
- ),
-
- icalproperty_vanew_attendee(
-
- ''employee-A@host.com'',
-
- icalparameter_new_role(
-
- ICAL_ROLE_REQPARTICIPANT),
-
- icalparameter_new_rsvp(1),
-
- icalparameter_new_cutype(ICAL_CUTYPE_GROUP),
-
- 0
-
- ),
-
- icalproperty_new_location(
-
- "1CP Conference Room 4350"),
-
- 0
-
- ),
-
- 0
-
- );
+ ICAL_VEVENT_COMPONENT,
+ icalproperty_new_dtstamp(atime),
+ icalproperty_new_uid("guid-1.host1.com"),
+ icalproperty_vanew_organizer(
+ "mrbig@host.com",
+ icalparameter_new_role(ICAL_ROLE_CHAIR),
+ 0),
+ icalproperty_vanew_attendee(
+ "employee-A@host.com",
+ icalparameter_new_role(
+ ICAL_ROLE_REQPARTICIPANT),
+ icalparameter_new_rsvp(1),
+ icalparameter_new_cutype(ICAL_CUTYPE_GROUP),
+ 0),
+ icalproperty_new_location(
+ "1CP Conference Room 4350"),
+ 0),
+ 0);
```
This form is similar to the constructor form, except that the constructors
-have "vanew" instead of "new" in the name. The arguments are similar
+have `vanew` instead of `new` in the name. The arguments are similar
too, except that the component constructor can have a list of properties,
-and the property constructor can have a list of parameters. Be sure
+and the property constructor can have a list of parameters. *Be sure
to terminate every list with a '0', or your code will crash, if you
-are lucky.
+are lucky*.
#### 5.1.3 Parsing Text Files
@@ -425,13 +375,20 @@ the component line by line. This is possible too by using:
```c
icalparser* icalparser_new();
-void icalparser_free(icalparser* parser);
+void icalparser_free(
+ icalparser* parser);
-icalparser_get_line(parser,read_stream);
+icalparser_get_line(
+ icalparser *parser,
+ char* (*read_stream)(char *s, size_t size, void* d));
-icalparser_add_line(parser,line);
+icalparser_add_line(
+ icalparser *parser,
+ char *line);
-icalparser_set_gen_data(parser,stream)
+icalparser_set_gen_data(
+ icalparser *parser,
+ void *data);
```
These routines will construct a parser object to which you can add
@@ -441,47 +398,42 @@ to get string data from a source. For example:
```c
char* read_stream(char *s, size_t size, void *d)
-
{
-
- char *c = fgets(s,size, (FILE*)d);
-
- return c;
-
+ return fgets(s, size, (FILE*)d);
}
-main() {
-
- char* line;
-
- icalcomponent *c;
-
- icalparser *parser = icalparser_new();
-
- FILE* stream = fopen(argv[1],"r");
-
- icalparser_set_gen_data(parser,stream);
-
- do {
-
- line = icalparser_get_line(parser,read_stream);
-
- c = icalparser_add_line(parser,line);
-
- if (c != 0){
+int main(int argc, char *argv[])
+{
+ char *line;
+ icalcomponent *component;
+ icalparser *parser = icalparser_new();
- printf("%s",icalcomponent_as_ical_string(c));
+ // open file (first command-line argument)
+ FILE* stream = fopen(argv[1], "r");
- icalparser_claim(parser);
+ // associate the FILE with the parser so that read_stream
+ // will have access to it
+ icalparser_set_gen_data(parser, stream);
- printf("\n---------------\n");
+ do {
+ // read the file, line-by-line, and parse the data
+ line = icalparser_get_line(parser, read_stream);
+ component = icalparser_add_line(parser, line);
- icalcomponent_free(c);
+ // if icalparser has finished parsing a component,
+ // it will return it
+ if (component != 0) {
+ // print the parsed component
+ printf("%s", icalcomponent_as_ical_string(component));
+ icalparser_clean(parser);
- }
+ printf("\n---------------\n");
- } while (line != 0);
+ icalcomponent_free(component);
+ }
+ } while (line != 0);
+ return 0;
}
```
@@ -501,9 +453,9 @@ Since the example code is a very common way to use the parser, there
is a convenience routine;
```c
-icalcomponent* icalparser_parse(icalparser *parser,
-
- char* (*line_gen_func)(char *s, size_t size, void* d))
+icalcomponent* icalparser_parse(
+ icalparser *parser,
+ char* (*line_gen_func)(char *s, size_t size, void* d));
```
To use this routine, you still must construct the parser object and
@@ -514,6 +466,40 @@ components from the input, it will return a reference to an `XROOT`
component (of type `ICAL_XROOT_COMPONENT`.) This `XROOT` component will
hold all of the components constructed from the input as children.
+```c
+char* read_stream(char *s, size_t size, void *d)
+{
+ return fgets(s, size, (FILE*)d);
+}
+
+int main(int argc, char *argv[])
+{
+ char* line;
+ icalcomponent *component;
+ icalparser *parser = icalparser_new();
+
+ // open file (first command-line argument)
+ FILE* stream = fopen(argv[1], "r");
+
+ // associate the FILE with the parser so that read_stream
+ // will have access to it
+ icalparser_set_gen_data(parser, stream);
+
+ // parse the opened file
+ component = icalparser_parse(parser, read_stream);
+
+ if (component != 0) {
+ // print the parsed component
+ printf("%s", icalcomponent_as_ical_string(component));
+ icalcomponent_free(component);
+ }
+
+ icalparser_free(parser);
+
+ return 0;
+}
+```
+
### 5.2 Accessing Components
Given a reference to a component, you probably will want to access
@@ -527,8 +513,8 @@ To find a sub-component of a component, use:
```c
icalcomponent* icalcomponent_get_first_component(
- icalcomponent* component,
- icalcomponent_kind kind);
+ icalcomponent* component,
+ icalcomponent_kind kind);
```
This routine will return a reference to the first component of the
@@ -556,27 +542,21 @@ the first:
```c
icalcomponent* icalcomponent_get_next_component(
-
- icalcomponent* component,
-
- icalcomponent_kind kind);
+ icalcomponent* component,
+ icalcomponent_kind kind);
```
With the 'first' and 'next' routines, you can create a for loop to
iterate through all of a components subcomponents
```c
- for(c = icalcomponent_get_first_component(comp,ICAL_ANY_COMPONENT);
-
- c != 0;
-
-
- c = icalcomponent_get_next_component(comp,ICAL_ANY_COMPONENT))
+icalcomponent *c;
+for(c = icalcomponent_get_first_component(comp, ICAL_ANY_COMPONENT);
+ c != 0;
+ c = icalcomponent_get_next_component(comp, ICAL_ANY_COMPONENT))
{
-
do_something(c);
-
}
```
@@ -597,17 +577,22 @@ To solve this problem, there are also external iterators for components.
The routines associated with these external iterators are:
```c
-icalcompiter icalcomponent_begin_component(icalcomponent* component,
-icalcomponent_kind kind);
+icalcompiter icalcomponent_begin_component(
+ icalcomponent* component,
+ icalcomponent_kind kind);
-icalcompiter icalcomponent_end_component(icalcomponent* component,
-icalcomponent_kind kind);
+icalcompiter icalcomponent_end_component(
+ icalcomponent* component,
+ icalcomponent_kind kind);
-icalcomponent* icalcompiter_next(icalcompiter* i);
+icalcomponent* icalcompiter_next(
+ icalcompiter* i);
-icalcomponent* icalcompiter_prior(icalcompiter* i);
+icalcomponent* icalcompiter_prior(
+ icalcompiter* i);
-icalcomponent* icalcompiter_deref(icalcompiter* i);
+icalcomponent* icalcompiter_deref(
+ icalcompiter* i);
```
The `*_begin_*()` and `*_end_*()` routines return a new iterator that points
@@ -624,18 +609,11 @@ when they move to point off the end of the list.
Here is an example of a loop using these routines:
```c
-for(
-
- i = icalcomponent_begin_component(impl->cluster,ICAL_ANY_COMPONENT);
-
- icalcompiter_deref(&i)!= 0;
-
- icalcompiter_next(&i)
-
-) {
-
- icalcomponent *this = icalcompiter_deref(&i);
-
+for(i = icalcomponent_begin_component(impl->cluster, ICAL_ANY_COMPONENT);
+ icalcompiter_deref(&i)!= 0;
+ icalcompiter_next(&i))
+{
+ icalcomponent *this = icalcompiter_deref(&i);
}
```
@@ -651,18 +629,12 @@ avoid the problem, you will need to step the iterator ahead of the
element you are going to remove, like this:
```c
-for(c = icalcomponent_get_first_component(parent_comp,ICAL_ANY_COMPONENT);
-
- c != 0;
-
- c = next
-
+for(c = icalcomponent_get_first_component(parent_comp, ICAL_ANY_COMPONENT);
+ c != 0;
+ c = next)
{
-
- next = icalcomponent_get_next_component(parent_comp,ICAL_ANY_COMPONENT);
-
+ next = icalcomponent_get_next_component(parent_comp, ICAL_ANY_COMPONENT);
icalcomponent_remove_component(parent_comp,c);
-
}
```
@@ -675,18 +647,12 @@ the child. The following code will exploit this behavior:
```c
icalcomponent_get_first_component(parent_comp,ICAL_VEVENT_COMPONENT);
-while((c=icalcomponent_get_current_component(c)) != 0 ){
-
+while((c=icalcomponent_get_current_component(c)) != 0){
if(icalcomponent_isa(c) == ICAL_VEVENT_COMPONENT){
-
icalcomponent_remove_component(parent_comp,inner);
-
} else {
-
icalcomponent_get_next_component(parent_comp,ICAL_VEVENT_COMPONENT);
-
}
-
}
```
@@ -698,55 +664,39 @@ interfaces:
```c
icalproperty* icalcomponent_get_first_property(
-
- icalcomponent* component,
-
- icalproperty_kind kind);
+ icalcomponent* component,
+ icalproperty_kind kind);
icalproperty* icalcomponent_get_next_property(
-
- icalcomponent* component,
-
- icalproperty_kind kind);
+ icalcomponent* component,
+ icalproperty_kind kind);
void icalcomponent_add_property(
-
- icalcomponent* component,
-
- icalproperty* property);
+ icalcomponent* component,
+ icalproperty* property);
void icalcomponent_remove_property(
-
- icalcomponent* component,
-
- icalproperty* property);
+ icalcomponent* component,
+ icalproperty* property);
```
For parameters:
```c
icalparameter* icalproperty_get_first_parameter(
-
icalproperty* prop,
-
icalparameter_kind kind);
icalparameter* icalproperty_get_next_parameter(
-
icalproperty* prop,
-
icalparameter_kind kind);
void icalproperty_add_parameter(
-
icalproperty* prop,
-
icalparameter* parameter);
void icalproperty_remove_parameter_by_kind(
-
icalproperty* prop,
-
icalparameter_kind kind);
```
@@ -769,9 +719,12 @@ accesses the internal value. For instanace, for the `UID` property, the
routines are:
```c
-void icalproperty_set_uid(icalproperty* prop, const char* v)
+void icalproperty_set_uid(
+ icalproperty* prop,
+ const char* v);
-const char* icalproperty_get_uid(icalproperty* prop)
+const char* icalproperty_get_uid(
+ icalproperty* prop);
```
For multi-valued properties, like `ATTACH`, the value type is usually
@@ -781,9 +734,12 @@ If you want to work with the underlying value object, you can get and
set it with:
```c
-icalvalue* icalproperty_get_value (icalproperty* prop)
+icalvalue* icalproperty_get_value(
+ icalproperty* prop);
-void icalproperty_set_value(icalproperty* prop, icalvalue* value);
+void icalproperty_set_value(
+ icalproperty* prop,
+ icalvalue* value);
```
`icalproperty_get_value()` will return a reference that you can manipulate
@@ -792,9 +748,12 @@ 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:
```c
-struct icaltimetype icalvalue_get_datetime(icalvalue* value);
+struct icaltimetype icalvalue_get_datetime(
+ icalvalue* value);
-void icalvalue_set_datetime(icalvalue* value, struct icaltimetype v);
+void icalvalue_set_datetime(
+ icalvalue* value,
+ struct icaltimetype v);
```
When working with an extension property or value (and `X-PROPERTY` or
@@ -802,18 +761,24 @@ a property that has the parameter `VALUE=x-name`), the value type is
always a string. To get and set the value, use:
```x
-void icalproperty_set_x(icalproperty* prop, char* v);
+void icalproperty_set_x(
+ icalproperty* prop,
+ char* v);
-char* icalproperty_get_x(icalproperty* prop);
+char* icalproperty_get_x(
+ icalproperty* prop);
```
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:
```c
-char* icalproperty_get_x_name(icalproperty* prop)
+char* icalproperty_get_x_name(
+ icalproperty* prop)
-void icalproperty_set_x_name(icalproperty* prop, char* name);
+void icalproperty_set_x_name(
+ icalproperty* prop,
+ char* name);
```
#### 5.2.7 Checking Component Validity
@@ -848,13 +813,13 @@ To create an RFC5545 compliant text representation of an object, use
one of the `*_as_ical_string()` routines:
```c
-char* icalcomponent_as_ical_string (icalcomponent* component)
+char* icalcomponent_as_ical_string(icalcomponent* component)
-char* icalproperty_as_ical_string (icalproperty* property)
+char* icalproperty_as_ical_string(icalproperty* property)
-char* icalparameter_as_ical_string (icalparameter* parameter)
+char* icalparameter_as_ical_string(icalparameter* parameter)
-char* icalvalue_as_ical_string (icalvalue* value)
+char* icalvalue_as_ical_string(icalvalue* value)
```
In most cases, you will only use `icalcomponent_as_ical_string()`, since
@@ -876,22 +841,15 @@ local time and UTC. The libical structure is:
```c
struct icaltimetype {
-
int year;
-
int month;
-
int day;
-
int hour;
-
int minute;
-
int second;
-
int is_utc; /* 1-> time is in UTC timezone */
-
- int is_date; /* 1 -> interpret this as date. */ };
+ int is_date; /* 1 -> interpret this as date. */
+};
```
The `year`, `month`, `day`, `hour`, `minute` and `second` fields
@@ -906,14 +864,18 @@ second fields are assumed to be zero, regardless of their actual vaules.
There are several ways to create a new icaltimetype structure:
```c
-struct icaltimetype icaltime_from_string(const char* str);
+struct icaltimetype icaltime_from_string(
+ const char* str);
-struct icaltimetype icaltime_from_timet_with_zone(time_t v,
- int is_date,
- icaltimezone* zone);
+struct icaltimetype icaltime_from_timet_with_zone(
+ time_t v,
+ int is_date,
+ icaltimezone* zone);
+```
-icaltime_from_string takes any RFC5545 compliant time string:
+`icaltime_from_string()` takes any RFC5545 compliant time string:
+```c
struct icaltimetype tt = icaltime_from_string("19970101T103000");
```
@@ -951,7 +913,6 @@ Normalizing allows you to do arithmetic operations on time values.
struct icaltimetype tt = icaltime_from_string("19970101T103000");
tt.days +=3
-
tt.second += 70;
tt = icaltime_normalize(tt);
@@ -961,17 +922,28 @@ There are several routines to get the day of the week or month, etc,
from a time structure.
```c
-short icaltime_day_of_year(struct icaltimetype t);
+short icaltime_day_of_year(
+ struct icaltimetype t);
-struct icaltimetype icaltime_from_day_of_year(short doy, short year);
+struct icaltimetype icaltime_from_day_of_year(
+ short doy,
+ short year);
-short icaltime_day_of_week(struct icaltimetype t);
+short icaltime_day_of_week(
+ struct icaltimetype t);
-short icaltime_start_doy_week(struct icaltimetype t, int fdow);
+short icaltime_start_doy_week(
+ struct icaltimetype t,
+ int fdow);
-short icaltime_week_number(short day_of_month, short month, short year);
+short icaltime_week_number(
+ short day_of_month,
+ short month,
+ short year);
-short icaltime_days_in_month(short month,short year);
+short icaltime_days_in_month(
+ short month,
+ short year);
```
Two routines convert time structures to and from the number of seconds
@@ -979,17 +951,21 @@ since the POSIX epoch. The `is_date` field indicates whether or not
the hour, minute and second fields should be used in the conversion.
```c
-struct icaltimetype icaltime_from_timet_with_zone(time_t v,
- int is_date,
- icaltimezone* zone);
+struct icaltimetype icaltime_from_timet_with_zone(
+ time_t v,
+ int is_date,
+ icaltimezone* zone);
-time_t icaltime_as_timet(struct icaltimetype);
+time_t icaltime_as_timet(
+ struct icaltimetype);
```
The compare routine works exactly like `strcmp()`, but on time structures.
```c
-int icaltime_compare(struct icaltimetype a, struct icaltimetype b);
+int icaltime_compare(
+ struct icaltimetype a,
+ struct icaltimetype b);
```
The following routines convert between UTC and a named timezone. The
@@ -1008,15 +984,22 @@ years March 15 may be standard time, and some years may have standard
time all year.
```c
-int icaltime_utc_offset(struct icaltimetype tt, char* tzid);
+int icaltime_utc_offset(
+ struct icaltimetype tt,
+ char* tzid);
int icaltime_local_utc_offset();
-struct icaltimetype icaltime_as_utc(struct icaltimetype tt,char* tzid);
+struct icaltimetype icaltime_as_utc(
+ struct icaltimetype tt,
+ char* tzid);
-struct icaltimetype icaltime_as_zone(struct icaltimetype tt,char* tzid);
+struct icaltimetype icaltime_as_zone(
+ struct icaltimetype tt,
+ char* tzid);
-struct icaltimetype icaltime_as_local(struct icaltimetype tt);
+struct icaltimetype icaltime_as_local(
+ struct icaltimetype tt);
```
### 5.4 Storing Objects
@@ -1034,44 +1017,65 @@ for example, could be added in the future.
All of the icalset derived classes have the same interface:
```c
-icaldirset* icaldirset_new(const char* path);
+icaldirset* icaldirset_new(
+ const char* path);
-void icaldirset_free(icaldirset* store);
+void icaldirset_free(
+ icaldirset* store);
-const char* icaldirset_path(icaldirset* store);
+const char* icaldirset_path(
+ icaldirset* store);
-void icaldirset_mark(icaldirset* store);
+void icaldirset_mark(
+ icaldirset* store);
-icalerrorenum icaldirset_commit(icaldirset* store);
+icalerrorenum icaldirset_commit(
+ icaldirset* store);
-icalerrorenum icaldirset_add_component(icaldirset* store, icalcomponent*
-comp);
+icalerrorenum icaldirset_add_component(
+ icaldirset* store,
+ icalcomponent* comp);
-icalerrorenum icaldirset_remove_component(icaldirset* store, icalcomponent*
-comp);
+icalerrorenum icaldirset_remove_component(
+ icaldirset* store,
+ icalcomponent* comp);
-int icaldirset_count_components(icaldirset* store, icalcomponent_kind
-kind);
+int icaldirset_count_components(
+ icaldirset* store,
+ icalcomponent_kind kind);
-icalerrorenum icaldirset_select(icaldirset* store, icalcomponent* gauge);
+icalerrorenum icaldirset_select(
+ icaldirset* store,
+ icalcomponent* gauge);
-void icaldirset_clear(icaldirset* store);
+void icaldirset_clear(
+ icaldirset* store);
-icalcomponent* icaldirset_fetch(icaldirset* store, const char* uid);
+icalcomponent* icaldirset_fetch(
+ icaldirset* store,
+ const char* uid);
-int icaldirset_has_uid(icaldirset* store, const char* uid);
+int icaldirset_has_uid(
+ icaldirset* store,
+ const char* uid);
-icalcomponent* icaldirset_fetch_match(icaldirset* set, icalcomponent
-*c);
+icalcomponent* icaldirset_fetch_match(
+ icaldirset* set,
+ icalcomponent *c);
-icalerrorenum icaldirset_modify(icaldirset* store, icalcomponent *oldc,
-icalcomponent *newc);
+icalerrorenum icaldirset_modify(
+ icaldirset* store,
+ icalcomponent *oldc,
+ icalcomponent *newc);
-icalcomponent* icaldirset_get_current_component(icaldirset* store);
+icalcomponent* icaldirset_get_current_component(
+ icaldirset* store);
-icalcomponent* icaldirset_get_first_component(icaldirset* store);
+icalcomponent* icaldirset_get_first_component(
+ icaldirset* store);
-icalcomponent* icaldirset_get_next_component(icaldirset* store);
+icalcomponent* icaldirset_get_next_component(
+ icaldirset* store);
```
#### 5.4.1 Creating a new set
@@ -1093,9 +1097,13 @@ You can also create a new set based on the derived class, For instance,
with icalfileset:
```c
-icalfileset* icalfileset_new(const char* path);
+icalfileset* icalfileset_new(
+ const char* path);
-icalfileset* icalfileset_new_open(const char* path, int flags, int mode);
+icalfileset* icalfileset_new_open(
+ const char* path,
+ int flags,
+ int mode);
```
`icalset_new_file()` is identical to `icalfileset_new()`. Both routines will
@@ -1114,8 +1122,9 @@ other icalset derived classess will be similar.
To add components to a set, use:
```c
-icalerrorenum icalfileset_add_component(icalfileset* cluster, icalcomponent*
-child);
+icalerrorenum icalfileset_add_component(
+ icalfileset* cluster,
+ icalcomponent* child);
```
The fileset keeps an inmemory copy of the components, and this set
@@ -1158,67 +1167,46 @@ icalgauge* icalgauge_new_from_sql(const char* sql);
Then, you can add the gauge to the set with :
```c
-icalerrorenum icalfileset_select(icalfileset* store, icalgauge* gauge);
+icalerrorenum icalfileset_select(
+ icalfileset* store,
+ icalgauge* gauge);
```
Here is an example that puts all of these routines together:
```c
void test_fileset()
-
{
-
icalfileset *fs;
-
icalcomponent *c;
-
int i;
-
char *path = "test_fileset.ics";
icalgauge *g = icalgauge_new_from_sql(
-
"SELECT * FROM VEVENT WHERE DTSTART > '20000103T120000Z' AND
DTSTART <= '20000106T120000Z'");
-
-
fs = icalfileset_new(path);
-
-
for (i = 0; i!= 10; i++){
-
c = make_component(i); /* Make a new component where DTSTART
has month of i */
-
icalfileset_add_component(fs,c);
-
}
icalfileset_commit(fs); /* Write to disk */
-
- icalfileset_select(fs,g); /* Set the gauge to filter components
-*/
-
-
+ icalfileset_select(fs,g); /* Set the gauge to filter components */
for (c = icalfileset_get_first_component(fs);
-
c != 0;
-
- c = icalfileset_get_next_component(fs)){
-
+ c = icalfileset_get_next_component(fs))
+ {
struct icaltimetype t = icalcomponent_get_dtstart(c);
-
-
-
printf("%s\n",icaltime_as_ctime(t));
}
icalfileset_free(fs);
-
}
```
@@ -1362,7 +1350,6 @@ but does not format propertly in output. ]
The types of errors are listed in icalerror.h. They are:
-
- `ICAL_XLICERRORTYPE_COMPONENTPARSEERROR`
- `ICAL_XLICERRORTYPE_PARAMETERVALUEPARSEERROR`
- `ICAL_XLICERRORTYPE_PARAMETERNAMEPARSEERROR`
@@ -1439,24 +1426,14 @@ comment string "HACK."
struct icaltimetype
{
-
- int year;
-
- int month;
-
- int day;
-
- int hour;
-
- int minute;
-
- int second;
-
- int is_utc;
-
- int is_date;
-
- const char* zone;
-
+ int year;
+ int month;
+ int day;
+ int hour;
+ int minute;
+ int second;
+ int is_utc;
+ int is_date;
+ const char* zone;
};
```