Libical API Documentation  3.0
icalcomponent.h
Go to the documentation of this file.
1 /*======================================================================
2  FILE: icalcomponent.h
3  CREATOR: eric 20 March 1999
4 
5  (C) COPYRIGHT 2000, Eric Busboom <eric@civicknowledge.com>
6 
7  This library is free software; you can redistribute it and/or modify
8  it under the terms of either:
9 
10  The LGPL as published by the Free Software Foundation, version
11  2.1, available at: https://www.gnu.org/licenses/lgpl-2.1.html
12 
13  Or:
14 
15  The Mozilla Public License Version 2.0. You may obtain a copy of
16  the License at https://www.mozilla.org/MPL/
17 ======================================================================*/
18 
23 #ifndef ICALCOMPONENT_H
24 #define ICALCOMPONENT_H
25 
26 #include "libical_ical_export.h"
27 #include "icalenums.h" /* Defines icalcomponent_kind */
28 #include "icalproperty.h"
29 #include "pvl.h"
30 
31 typedef struct icalcomponent_impl icalcomponent;
32 
33 /* This is exposed so that callers will not have to allocate and
34  deallocate iterators. Pretend that you can't see it. */
35 typedef struct icalcompiter
36 {
37  icalcomponent_kind kind;
38  pvl_elem iter;
39 
40 } icalcompiter;
41 
44 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new(icalcomponent_kind kind);
45 
48 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_clone(icalcomponent *component);
49 
52 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_from_string(const char *str);
53 
58 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_vanew(icalcomponent_kind kind, ...);
59 
62 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_x(const char *x_name);
63 
64 /*** @brief Destructor
65  */
66 LIBICAL_ICAL_EXPORT void icalcomponent_free(icalcomponent *component);
67 
68 LIBICAL_ICAL_EXPORT char *icalcomponent_as_ical_string(icalcomponent *component);
69 
70 LIBICAL_ICAL_EXPORT char *icalcomponent_as_ical_string_r(icalcomponent *component);
71 
72 LIBICAL_ICAL_EXPORT int icalcomponent_is_valid(icalcomponent *component);
73 
74 LIBICAL_ICAL_EXPORT icalcomponent_kind icalcomponent_isa(const icalcomponent *component);
75 
76 LIBICAL_ICAL_EXPORT int icalcomponent_isa_component(void *component);
77 
78 /*
79  * Working with properties
80  */
81 
82 LIBICAL_ICAL_EXPORT void icalcomponent_add_property(icalcomponent *component,
83  icalproperty *property);
84 
85 LIBICAL_ICAL_EXPORT void icalcomponent_remove_property(icalcomponent *component,
86  icalproperty *property);
87 
88 LIBICAL_ICAL_EXPORT int icalcomponent_count_properties(icalcomponent *component,
89  icalproperty_kind kind);
90 
95 LIBICAL_ICAL_EXPORT void icalproperty_set_parent(icalproperty *property,
96  icalcomponent *component);
97 
101 LIBICAL_ICAL_EXPORT icalcomponent *icalproperty_get_parent(const icalproperty *property);
102 
103 /* Iterate through the properties */
104 LIBICAL_ICAL_EXPORT icalproperty *icalcomponent_get_current_property(icalcomponent *component);
105 
106 LIBICAL_ICAL_EXPORT icalproperty *icalcomponent_get_first_property(icalcomponent *component,
107  icalproperty_kind kind);
108 LIBICAL_ICAL_EXPORT icalproperty *icalcomponent_get_next_property(icalcomponent *component,
109  icalproperty_kind kind);
110 
111 /*
112  * Working with components
113  */
114 
117 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_inner(icalcomponent *comp);
118 
119 LIBICAL_ICAL_EXPORT void icalcomponent_add_component(icalcomponent *parent, icalcomponent *child);
120 
121 LIBICAL_ICAL_EXPORT void icalcomponent_remove_component(icalcomponent *parent,
122  icalcomponent *child);
123 
124 LIBICAL_ICAL_EXPORT int icalcomponent_count_components(icalcomponent *component,
125  icalcomponent_kind kind);
126 
132 LIBICAL_ICAL_EXPORT void icalcomponent_merge_component(icalcomponent *comp,
133  icalcomponent *comp_to_merge);
134 
135 /* Iteration Routines. There are two forms of iterators, internal and
136 external. The internal ones came first, and are almost completely
137 sufficient, but they fail badly when you want to construct a loop that
138 removes components from the container.*/
139 
140 /* Iterate through components */
141 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_current_component(icalcomponent *component);
142 
143 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_first_component(icalcomponent *component,
144  icalcomponent_kind kind);
145 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_next_component(icalcomponent *component,
146  icalcomponent_kind kind);
147 
148 /* Using external iterators */
149 LIBICAL_ICAL_EXPORT icalcompiter icalcomponent_begin_component(icalcomponent *component,
150  icalcomponent_kind kind);
151 
152 LIBICAL_ICAL_EXPORT icalcompiter icalcomponent_end_component(icalcomponent *component,
153  icalcomponent_kind kind);
154 
155 LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_next(icalcompiter * i);
156 
157 LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_prior(icalcompiter * i);
158 
159 LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_deref(icalcompiter * i);
160 
161 /* Working with embedded error properties */
162 
163 /* Check the component against itip rules and insert error properties*/
164 /* Working with embedded error properties */
165 LIBICAL_ICAL_EXPORT int icalcomponent_check_restrictions(icalcomponent *comp);
166 
172 LIBICAL_ICAL_EXPORT int icalcomponent_count_errors(icalcomponent *component);
173 
175 LIBICAL_ICAL_EXPORT void icalcomponent_strip_errors(icalcomponent *component);
176 
178 LIBICAL_ICAL_EXPORT void icalcomponent_convert_errors(icalcomponent *component);
179 
180 /* Internal operations. They are private, and you should not be using them. */
181 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_parent(icalcomponent *component);
182 
183 LIBICAL_ICAL_EXPORT void icalcomponent_set_parent(icalcomponent *component,
184  icalcomponent *parent);
185 
186 /* Kind conversion routines */
187 
188 LIBICAL_ICAL_EXPORT int icalcomponent_kind_is_valid(const icalcomponent_kind kind);
189 
190 LIBICAL_ICAL_EXPORT icalcomponent_kind icalcomponent_string_to_kind(const char *string);
191 
192 LIBICAL_ICAL_EXPORT const char *icalcomponent_kind_to_string(icalcomponent_kind kind);
193 
194 /************* Derived class methods. ****************************
195 
196 If the code was in an OO language, the remaining routines would be
197 members of classes derived from icalcomponent. Don't call them on the
198 wrong component subtypes. */
199 
204 
221 LIBICAL_ICAL_EXPORT struct icaltime_span icalcomponent_get_span(icalcomponent *comp);
222 
223 /******************** Convenience routines **********************/
224 
230 LIBICAL_ICAL_EXPORT void icalcomponent_set_dtstart(icalcomponent *comp, struct icaltimetype v);
231 
241 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtstart(icalcomponent *comp);
242 
243 /* For the icalcomponent routines only, dtend and duration are tied
244  together. If you call the get routine for one and the other exists,
245  the routine will calculate the return value. That is, if there is a
246  DTEND and you call get_duration, the routine will return the difference
247  between DTEND and DTSTART. However, if you call a set routine for
248  one and the other exists, no action will be taken and icalerrno will
249  be set to ICAL_MALFORMEDDATA_ERROR. If you call a set routine and
250  neither exists, the routine will create the appropriate property. */
251 
277 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtend(icalcomponent *comp);
278 
294 LIBICAL_ICAL_EXPORT void icalcomponent_set_dtend(icalcomponent *comp, struct icaltimetype v);
295 
303 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_due(icalcomponent *comp);
304 
316 LIBICAL_ICAL_EXPORT void icalcomponent_set_due(icalcomponent *comp, struct icaltimetype v);
317 
333 LIBICAL_ICAL_EXPORT void icalcomponent_set_duration(icalcomponent *comp,
334  struct icaldurationtype v);
335 
348 LIBICAL_ICAL_EXPORT struct icaldurationtype icalcomponent_get_duration(icalcomponent *comp);
349 
352 LIBICAL_ICAL_EXPORT void icalcomponent_set_method(icalcomponent *comp, icalproperty_method method);
353 
356 LIBICAL_ICAL_EXPORT icalproperty_method icalcomponent_get_method(icalcomponent *comp);
357 
358 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtstamp(icalcomponent *comp);
359 
360 LIBICAL_ICAL_EXPORT void icalcomponent_set_dtstamp(icalcomponent *comp, struct icaltimetype v);
361 
362 LIBICAL_ICAL_EXPORT void icalcomponent_set_summary(icalcomponent *comp, const char *v);
363 
364 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_summary(icalcomponent *comp);
365 
366 LIBICAL_ICAL_EXPORT void icalcomponent_set_comment(icalcomponent *comp, const char *v);
367 
368 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_comment(icalcomponent *comp);
369 
370 LIBICAL_ICAL_EXPORT void icalcomponent_set_uid(icalcomponent *comp, const char *v);
371 
372 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_uid(icalcomponent *comp);
373 
374 LIBICAL_ICAL_EXPORT void icalcomponent_set_relcalid(icalcomponent *comp, const char *v);
375 
376 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_relcalid(icalcomponent *comp);
377 
378 LIBICAL_ICAL_EXPORT void icalcomponent_set_recurrenceid(icalcomponent *comp,
379  struct icaltimetype v);
380 
381 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_recurrenceid(icalcomponent *comp);
382 
383 LIBICAL_ICAL_EXPORT void icalcomponent_set_description(icalcomponent *comp, const char *v);
384 
385 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_description(icalcomponent *comp);
386 
387 LIBICAL_ICAL_EXPORT void icalcomponent_set_location(icalcomponent *comp, const char *v);
388 
389 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_location(icalcomponent *comp);
390 
391 LIBICAL_ICAL_EXPORT void icalcomponent_set_sequence(icalcomponent *comp, int v);
392 
393 LIBICAL_ICAL_EXPORT int icalcomponent_get_sequence(icalcomponent *comp);
394 
395 LIBICAL_ICAL_EXPORT void icalcomponent_set_status(icalcomponent *comp, enum icalproperty_status v);
396 
397 LIBICAL_ICAL_EXPORT enum icalproperty_status icalcomponent_get_status(icalcomponent *comp);
398 
402 LIBICAL_ICAL_EXPORT void icalcomponent_foreach_tzid(icalcomponent *comp,
403  void (*callback) (icalparameter *param,
404  void *data),
405  void *callback_data);
406 
410 LIBICAL_ICAL_EXPORT icaltimezone *icalcomponent_get_timezone(icalcomponent *comp,
411  const char *tzid);
412 
435 LIBICAL_ICAL_EXPORT int icalproperty_recurrence_is_excluded(icalcomponent *comp,
436  struct icaltimetype *dtstart,
437  struct icaltimetype *recurtime);
438 
457 LIBICAL_ICAL_EXPORT void icalcomponent_foreach_recurrence(icalcomponent *comp,
458  struct icaltimetype start,
459  struct icaltimetype end,
460  void (*callback) (icalcomponent *comp,
461  struct icaltime_span *
462  span, void *data),
463  void *callback_data);
464 
469 LIBICAL_ICAL_EXPORT void icalcomponent_normalize(icalcomponent *comp);
470 
481 LIBICAL_ICAL_EXPORT struct icaltimetype icalproperty_get_datetime_with_component(
482  icalproperty *prop,
483  icalcomponent *comp);
484 /*************** Type Specific routines ***************/
485 
486 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vcalendar(void);
487 
488 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vevent(void);
489 
490 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vtodo(void);
491 
492 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vjournal(void);
493 
494 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_valarm(void);
495 
496 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vfreebusy(void);
497 
498 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vtimezone(void);
499 
500 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xstandard(void);
501 
502 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xdaylight(void);
503 
504 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vagenda(void);
505 
506 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vquery(void);
507 
508 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vavailability(void);
509 
510 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xavailable(void);
511 
512 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vpoll(void);
513 
514 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vvoter(void);
515 
516 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xvote(void);
517 
518 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vpatch(void);
519 
520 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xpatch(void);
521 
522 #endif /* !ICALCOMPONENT_H */
icalproperty_method icalcomponent_get_method(icalcomponent *comp)
Returns the METHOD property.
Definition: icalcomponent.c:1322
icalcomponent * icalcomponent_vanew(icalcomponent_kind kind,...)
Constructor.
Definition: icalcomponent.c:116
void icalcomponent_foreach_recurrence(icalcomponent *comp, struct icaltimetype start, struct icaltimetype end, void(*callback)(icalcomponent *comp, struct icaltime_span * span, void *data), void *callback_data)
Cycles through all recurrences of an event.
Definition: icaltime.h:95
void icalcomponent_foreach_tzid(icalcomponent *comp, void(*callback)(icalparameter *param, void *data), void *callback_data)
Calls the given function for each TZID parameter found in the component, and any subcomponents.
struct icaldurationtype icalcomponent_get_duration(icalcomponent *comp)
Gets the DURATION property as an icalduration.
Definition: icalcomponent.c:1476
struct icaltimetype icalcomponent_get_dtend(icalcomponent *comp)
Gets the DTEND property as an icaltime.
Definition: icalcomponent.c:1377
icalcomponent * icalcomponent_get_first_real_component(icalcomponent *c)
Returns a reference to the first VEVENT, VTODO or VJOURNAL in the component.
Definition: icalcomponent.c:581
void icalcomponent_set_method(icalcomponent *comp, icalproperty_method method)
Sets the METHOD property to the given method.
Definition: icalcomponent.c:1310
struct icaltimetype icalproperty_get_datetime_with_component(icalproperty *prop, icalcomponent *comp)
Gets a DATE or DATE-TIME property as an icaltime.
Definition: icalproperty.c:1052
icalcomponent * icalcomponent_new(icalcomponent_kind kind)
Constructor.
Definition: icalcomponent.c:111
void icalcomponent_set_due(icalcomponent *comp, struct icaltimetype v)
Sets the due date of a VTODO task.
Definition: icalcomponent.c:2410
icalcomponent * icalcomponent_new_from_string(const char *str)
Constructor.
Definition: icalcomponent.c:135
A struct representing a duration.
Definition: icalduration.h:36
void icalcomponent_set_relcalid(icalcomponent *comp, const char *v)
Sets the RELCALID property of a component.
Definition: icalcomponent.c:2348
void icalcomponent_set_duration(icalcomponent *comp, struct icaldurationtype v)
Sets the DURATION property to given icalduration.
Definition: icalcomponent.c:1459
int icalcomponent_count_errors(icalcomponent *component)
Returns the number of errors encountered parsing the data.
Definition: icalcomponent.c:984
Definition: icalcomponent.c:35
Definition: icalcomponent.h:35
Definition: pvl.h:33
void icalcomponent_convert_errors(icalcomponent *component)
Converts some X-LIC-ERROR properties into RETURN-STATUS properties.
Definition: icalcomponent.c:1036
Definition: icaltime.h:104
void icalcomponent_set_dtstart(icalcomponent *comp, struct icaltimetype v)
Sets the DTSTART property to the given icaltime,.
Definition: icalcomponent.c:1344
int icalproperty_recurrence_is_excluded(icalcomponent *comp, struct icaltimetype *dtstart, struct icaltimetype *recurtime)
Decides if a recurrence is acceptable.
Definition: icalcomponent.c:672
struct icaltimetype icalcomponent_get_dtstart(icalcomponent *comp)
Gets the DTSTART property as an icaltime.
Definition: icalcomponent.c:1364
icalcomponent * icalproperty_get_parent(const icalproperty *property)
Returns the parent icalcomponent for the specified property.
Definition: icalproperty.c:915
void icalcomponent_strip_errors(icalcomponent *component)
Removes all X-LIC-ERROR properties.
Definition: icalcomponent.c:1010
icaltimezone * icalcomponent_get_timezone(icalcomponent *comp, const char *tzid)
Returns the icaltimezone in the component corresponding to the TZID, or NULL if it can't be found...
Definition: icalcomponent.c:2220
Definition: icaltimezoneimpl.h:22
icalcomponent * icalcomponent_new_clone(icalcomponent *component)
Constructor.
Definition: icalcomponent.c:140
void icalcomponent_normalize(icalcomponent *comp)
Normalizes (reorders and sorts the properties) the specified icalcomponent comp.
Definition: icalcomponent.c:2607
icalcomponent * icalcomponent_get_inner(icalcomponent *comp)
Definition: icalcomponent.c:1301
void icalproperty_set_parent(icalproperty *property, icalcomponent *component)
Sets the parent icalcomponent for the specified icalproperty property.
Definition: icalproperty.c:908
void icalcomponent_set_dtend(icalcomponent *comp, struct icaltimetype v)
Sets the DTEND property to given icaltime.
Definition: icalcomponent.c:1434
void icalcomponent_merge_component(icalcomponent *comp, icalcomponent *comp_to_merge)
Definition: icalcomponent.c:1938
icalcomponent * icalcomponent_new_x(const char *x_name)
Constructor.
Definition: icalcomponent.c:168
const char * icalcomponent_get_relcalid(icalcomponent *comp)
Gets the RELCALID property of a component.
Definition: icalcomponent.c:2366
struct icaltime_span icalcomponent_get_span(icalcomponent *comp)
Gets the timespan covered by this component, in UTC.
Definition: icalcomponent.c:604
struct icaltimetype icalcomponent_get_due(icalcomponent *comp)
Returns the time a VTODO task is DUE.
Definition: icalcomponent.c:2388