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
44LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new(icalcomponent_kind kind);
45
48LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_clone(icalcomponent *component);
49
52LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_from_string(const char *str);
53
56LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_vanew(icalcomponent_kind kind, ...);
57
60LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_x(const char *x_name);
61
62/*** @brief Destructor
63 */
64LIBICAL_ICAL_EXPORT void icalcomponent_free(icalcomponent *component);
65
66LIBICAL_ICAL_EXPORT char *icalcomponent_as_ical_string(icalcomponent *component);
67
68LIBICAL_ICAL_EXPORT char *icalcomponent_as_ical_string_r(icalcomponent *component);
69
70LIBICAL_ICAL_EXPORT int icalcomponent_is_valid(icalcomponent *component);
71
72LIBICAL_ICAL_EXPORT icalcomponent_kind icalcomponent_isa(const icalcomponent *component);
73
74LIBICAL_ICAL_EXPORT int icalcomponent_isa_component(void *component);
75
76/*
77 * Working with properties
78 */
79
80LIBICAL_ICAL_EXPORT void icalcomponent_add_property(icalcomponent *component,
81 icalproperty *property);
82
83LIBICAL_ICAL_EXPORT void icalcomponent_remove_property(icalcomponent *component,
84 icalproperty *property);
85
86LIBICAL_ICAL_EXPORT int icalcomponent_count_properties(icalcomponent *component,
87 icalproperty_kind kind);
88
93LIBICAL_ICAL_EXPORT void icalproperty_set_parent(icalproperty *property,
94 icalcomponent *component);
95
99LIBICAL_ICAL_EXPORT icalcomponent *icalproperty_get_parent(const icalproperty *property);
100
101/* Iterate through the properties */
102LIBICAL_ICAL_EXPORT icalproperty *icalcomponent_get_current_property(icalcomponent *component);
103
104LIBICAL_ICAL_EXPORT icalproperty *icalcomponent_get_first_property(icalcomponent *component,
105 icalproperty_kind kind);
106LIBICAL_ICAL_EXPORT icalproperty *icalcomponent_get_next_property(icalcomponent *component,
107 icalproperty_kind kind);
108
109/*
110 * Working with components
111 */
112
115LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_inner(icalcomponent *comp);
116
117LIBICAL_ICAL_EXPORT void icalcomponent_add_component(icalcomponent *parent, icalcomponent *child);
118
119LIBICAL_ICAL_EXPORT void icalcomponent_remove_component(icalcomponent *parent,
120 icalcomponent *child);
121
122LIBICAL_ICAL_EXPORT int icalcomponent_count_components(icalcomponent *component,
123 icalcomponent_kind kind);
124
130LIBICAL_ICAL_EXPORT void icalcomponent_merge_component(icalcomponent *comp,
131 icalcomponent *comp_to_merge);
132
133/* Iteration Routines. There are two forms of iterators, internal and
134 external. The internal ones came first, and are almost completely
135 sufficient, but they fail badly when you want to construct a loop that
136 removes components from the container.*/
137
138/* Iterate through components */
139LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_current_component(icalcomponent *component);
140
141LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_first_component(icalcomponent *component,
142 icalcomponent_kind kind);
143LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_next_component(icalcomponent *component,
144 icalcomponent_kind kind);
145
146/* Using external iterators */
147LIBICAL_ICAL_EXPORT icalcompiter icalcomponent_begin_component(icalcomponent *component,
148 icalcomponent_kind kind);
149
150LIBICAL_ICAL_EXPORT icalcompiter icalcomponent_end_component(icalcomponent *component,
151 icalcomponent_kind kind);
152
153LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_next(icalcompiter * i);
154
155LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_prior(icalcompiter * i);
156
157LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_deref(icalcompiter * i);
158
159/* Working with embedded error properties */
160
161/* Check the component against itip rules and insert error properties*/
162/* Working with embedded error properties */
163LIBICAL_ICAL_EXPORT int icalcomponent_check_restrictions(icalcomponent *comp);
164
170LIBICAL_ICAL_EXPORT int icalcomponent_count_errors(icalcomponent *component);
171
173LIBICAL_ICAL_EXPORT void icalcomponent_strip_errors(icalcomponent *component);
174
176LIBICAL_ICAL_EXPORT void icalcomponent_convert_errors(icalcomponent *component);
177
178/* Internal operations. They are private, and you should not be using them. */
179LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_parent(icalcomponent *component);
180
181LIBICAL_ICAL_EXPORT void icalcomponent_set_parent(icalcomponent *component,
182 icalcomponent *parent);
183
184/* Kind conversion routines */
185
186LIBICAL_ICAL_EXPORT int icalcomponent_kind_is_valid(const icalcomponent_kind kind);
187
188LIBICAL_ICAL_EXPORT icalcomponent_kind icalcomponent_string_to_kind(const char *string);
189
190LIBICAL_ICAL_EXPORT const char *icalcomponent_kind_to_string(icalcomponent_kind kind);
191
192/************* Derived class methods. ****************************
193
194 If the code was in an OO language, the remaining routines would be
195 members of classes derived from icalcomponent. Don't call them on the
196 wrong component subtypes. */
197
201LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_first_real_component(icalcomponent *c);
202
219LIBICAL_ICAL_EXPORT struct icaltime_span icalcomponent_get_span(icalcomponent *comp);
220
221/******************** Convenience routines **********************/
222
228LIBICAL_ICAL_EXPORT void icalcomponent_set_dtstart(icalcomponent *comp, struct icaltimetype v);
229
239LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtstart(icalcomponent *comp);
240
241/* For the icalcomponent routines only, dtend and duration are tied
242 together. If you call the get routine for one and the other exists,
243 the routine will calculate the return value. That is, if there is a
244 DTEND and you call get_duration, the routine will return the difference
245 between DTEND and DTSTART. However, if you call a set routine for
246 one and the other exists, no action will be taken and icalerrno will
247 be set to ICAL_MALFORMEDDATA_ERROR. If you call a set routine and
248 neither exists, the routine will create the appropriate property. */
249
268LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtend(icalcomponent *comp);
269
285LIBICAL_ICAL_EXPORT void icalcomponent_set_dtend(icalcomponent *comp, struct icaltimetype v);
286
294LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_due(icalcomponent *comp);
295
307LIBICAL_ICAL_EXPORT void icalcomponent_set_due(icalcomponent *comp, struct icaltimetype v);
308
324LIBICAL_ICAL_EXPORT void icalcomponent_set_duration(icalcomponent *comp,
325 struct icaldurationtype v);
326
340LIBICAL_ICAL_EXPORT struct icaldurationtype icalcomponent_get_duration(icalcomponent *comp);
341
344LIBICAL_ICAL_EXPORT void icalcomponent_set_method(icalcomponent *comp, icalproperty_method method);
345
348LIBICAL_ICAL_EXPORT icalproperty_method icalcomponent_get_method(icalcomponent *comp);
349
350LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtstamp(icalcomponent *comp);
351
352LIBICAL_ICAL_EXPORT void icalcomponent_set_dtstamp(icalcomponent *comp, struct icaltimetype v);
353
354LIBICAL_ICAL_EXPORT void icalcomponent_set_summary(icalcomponent *comp, const char *v);
355
356LIBICAL_ICAL_EXPORT const char *icalcomponent_get_summary(icalcomponent *comp);
357
358LIBICAL_ICAL_EXPORT void icalcomponent_set_comment(icalcomponent *comp, const char *v);
359
360LIBICAL_ICAL_EXPORT const char *icalcomponent_get_comment(icalcomponent *comp);
361
362LIBICAL_ICAL_EXPORT void icalcomponent_set_uid(icalcomponent *comp, const char *v);
363
364LIBICAL_ICAL_EXPORT const char *icalcomponent_get_uid(icalcomponent *comp);
365
366LIBICAL_ICAL_EXPORT void icalcomponent_set_relcalid(icalcomponent *comp, const char *v);
367
368LIBICAL_ICAL_EXPORT const char *icalcomponent_get_relcalid(icalcomponent *comp);
369
370LIBICAL_ICAL_EXPORT void icalcomponent_set_recurrenceid(icalcomponent *comp,
371 struct icaltimetype v);
372
373LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_recurrenceid(icalcomponent *comp);
374
375LIBICAL_ICAL_EXPORT void icalcomponent_set_description(icalcomponent *comp, const char *v);
376
377LIBICAL_ICAL_EXPORT const char *icalcomponent_get_description(icalcomponent *comp);
378
379LIBICAL_ICAL_EXPORT void icalcomponent_set_location(icalcomponent *comp, const char *v);
380
381LIBICAL_ICAL_EXPORT const char *icalcomponent_get_location(icalcomponent *comp);
382
383LIBICAL_ICAL_EXPORT void icalcomponent_set_sequence(icalcomponent *comp, int v);
384
385LIBICAL_ICAL_EXPORT int icalcomponent_get_sequence(icalcomponent *comp);
386
387LIBICAL_ICAL_EXPORT void icalcomponent_set_status(icalcomponent *comp, enum icalproperty_status v);
388
389LIBICAL_ICAL_EXPORT enum icalproperty_status icalcomponent_get_status(icalcomponent *comp);
390
394LIBICAL_ICAL_EXPORT void icalcomponent_foreach_tzid(icalcomponent *comp,
395 void (*callback) (icalparameter *param,
396 void *data),
397 void *callback_data);
398
402LIBICAL_ICAL_EXPORT icaltimezone *icalcomponent_get_timezone(icalcomponent *comp,
403 const char *tzid);
404
427LIBICAL_ICAL_EXPORT int icalproperty_recurrence_is_excluded(icalcomponent *comp,
428 struct icaltimetype *dtstart,
429 struct icaltimetype *recurtime);
430
449LIBICAL_ICAL_EXPORT void icalcomponent_foreach_recurrence(icalcomponent *comp,
450 struct icaltimetype start,
451 struct icaltimetype end,
452 void (*callback) (icalcomponent *comp,
453 struct icaltime_span *
454 span, void *data),
455 void *callback_data);
456
461LIBICAL_ICAL_EXPORT void icalcomponent_normalize(icalcomponent *comp);
462
473LIBICAL_ICAL_EXPORT struct icaltimetype icalproperty_get_datetime_with_component(
474 icalproperty *prop,
475 icalcomponent *comp);
476/*************** Type Specific routines ***************/
477
478LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vcalendar(void);
479
480LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vevent(void);
481
482LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vtodo(void);
483
484LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vjournal(void);
485
486LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_valarm(void);
487
488LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vfreebusy(void);
489
490LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vtimezone(void);
491
492LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xstandard(void);
493
494LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xdaylight(void);
495
496LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vagenda(void);
497
498LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vquery(void);
499
500LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vavailability(void);
501
502LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xavailable(void);
503
504LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vpoll(void);
505
506LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vvoter(void);
507
508LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xvote(void);
509
510LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vpatch(void);
511
512LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xpatch(void);
513
514#endif /* !ICALCOMPONENT_H */
icalcomponent_convert_errors
void icalcomponent_convert_errors(icalcomponent *component)
Converts some X-LIC-ERROR properties into RETURN-STATUS properties.
Definition: icalcomponent.c:1013
icalcomponent_set_relcalid
void icalcomponent_set_relcalid(icalcomponent *comp, const char *v)
Sets the RELCALID property of a component.
Definition: icalcomponent.c:2269
icalcomponent_new_clone
icalcomponent * icalcomponent_new_clone(icalcomponent *component)
Constructor.
Definition: icalcomponent.c:141
icalcomponent_get_dtend
struct icaltimetype icalcomponent_get_dtend(icalcomponent *comp)
Gets the DTEND property as an icaltime.
Definition: icalcomponent.c:1354
icalcomponent_get_dtstart
struct icaltimetype icalcomponent_get_dtstart(icalcomponent *comp)
Gets the DTSTART property as an icaltime.
Definition: icalcomponent.c:1341
icalcomponent_get_method
icalproperty_method icalcomponent_get_method(icalcomponent *comp)
Returns the METHOD property.
Definition: icalcomponent.c:1299
icalcomponent_foreach_recurrence
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: icalcomponent.c:798
icalproperty_get_parent
icalcomponent * icalproperty_get_parent(const icalproperty *property)
Returns the parent icalcomponent for the specified property.
Definition: icalproperty.c:915
icalcomponent_set_dtstart
void icalcomponent_set_dtstart(icalcomponent *comp, struct icaltimetype v)
Sets the DTSTART property to the given icaltime,.
Definition: icalcomponent.c:1321
icalcomponent_strip_errors
void icalcomponent_strip_errors(icalcomponent *component)
Removes all X-LIC-ERROR properties.
Definition: icalcomponent.c:987
icalcomponent_normalize
void icalcomponent_normalize(icalcomponent *comp)
Normalizes (reorders and sorts the properties) the specified icalcomponent comp.
Definition: icalcomponent.c:2485
icalproperty_get_datetime_with_component
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_vanew
icalcomponent * icalcomponent_vanew(icalcomponent_kind kind,...)
Constructor.
Definition: icalcomponent.c:118
icalcomponent_set_method
void icalcomponent_set_method(icalcomponent *comp, icalproperty_method method)
Sets the METHOD property to the given method.
Definition: icalcomponent.c:1287
icalcomponent_new
icalcomponent * icalcomponent_new(icalcomponent_kind kind)
Constructor.
Definition: icalcomponent.c:111
icalcomponent_get_inner
icalcomponent * icalcomponent_get_inner(icalcomponent *comp)
Definition: icalcomponent.c:1278
icalproperty_set_parent
void icalproperty_set_parent(icalproperty *property, icalcomponent *component)
Sets the parent icalcomponent for the specified icalproperty property.
Definition: icalproperty.c:908
icalcomponent_get_first_real_component
icalcomponent * icalcomponent_get_first_real_component(icalcomponent *c)
Returns a reference to the first VEVENT, VTODO or VJOURNAL in the component.
Definition: icalcomponent.c:582
icalcomponent_get_relcalid
const char * icalcomponent_get_relcalid(icalcomponent *comp)
Gets the RELCALID property of a component.
Definition: icalcomponent.c:2287
icalcomponent_get_due
struct icaltimetype icalcomponent_get_due(icalcomponent *comp)
Returns the time a VTODO task is DUE.
Definition: icalcomponent.c:2309
icalcomponent_merge_component
void icalcomponent_merge_component(icalcomponent *comp, icalcomponent *comp_to_merge)
Definition: icalcomponent.c:1859
icalcomponent_count_errors
int icalcomponent_count_errors(icalcomponent *component)
Returns the number of errors encountered parsing the data.
Definition: icalcomponent.c:961
icalcomponent_get_duration
struct icaldurationtype icalcomponent_get_duration(icalcomponent *comp)
Gets the DURATION property as an icalduration.
Definition: icalcomponent.c:1423
icalproperty_recurrence_is_excluded
int icalproperty_recurrence_is_excluded(icalcomponent *comp, struct icaltimetype *dtstart, struct icaltimetype *recurtime)
Decides if a recurrence is acceptable.
Definition: icalcomponent.c:683
icalcomponent_get_timezone
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:2141
icalcomponent_set_dtend
void icalcomponent_set_dtend(icalcomponent *comp, struct icaltimetype v)
Sets the DTEND property to given icaltime.
Definition: icalcomponent.c:1381
icalcomponent_get_span
struct icaltime_span icalcomponent_get_span(icalcomponent *comp)
Gets the timespan covered by this component, in UTC.
Definition: icalcomponent.c:605
icalcomponent_new_x
icalcomponent * icalcomponent_new_x(const char *x_name)
Constructor.
Definition: icalcomponent.c:169
icalcomponent_set_duration
void icalcomponent_set_duration(icalcomponent *comp, struct icaldurationtype v)
Sets the DURATION property to given icalduration.
Definition: icalcomponent.c:1406
icalcomponent_foreach_tzid
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.
Definition: icalcomponent.c:2104
icalcomponent_set_due
void icalcomponent_set_due(icalcomponent *comp, struct icaltimetype v)
Sets the due date of a VTODO task.
Definition: icalcomponent.c:2331
icalcomponent_new_from_string
icalcomponent * icalcomponent_new_from_string(const char *str)
Constructor.
Definition: icalcomponent.c:136
icalenums.h
icalproperty.h
_icaltimezone
Definition: icaltimezoneimpl.h:23
icalcompiter
Definition: icalcomponent.h:36
icalcomponent_impl
Definition: icalcomponent.c:36
icaldurationtype
A struct representing a duration.
Definition: icalduration.h:37
icaltime_span
Definition: icaltime.h:96
icaltimetype
Definition: icaltime.h:105
pvl_elem_t
Definition: pvl.h:34