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 19 #ifndef ICALCOMPONENT_H 20 #define ICALCOMPONENT_H 21 22 #include "libical_ical_export.h" 23 #include "icalenums.h" /* defines icalcomponent_kind */ 24 #include "icalproperty.h" 25 #include "pvl.h" 26 27 typedef struct icalcomponent_impl icalcomponent; 28 29 /* This is exposed so that callers will not have to allocate and 30 deallocate iterators. Pretend that you can't see it. */ 31 typedef struct icalcompiter 32 { 33 icalcomponent_kind kind; 34 pvl_elem iter; 35 36 } icalcompiter; 37 38 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new(icalcomponent_kind kind); 39 40 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_clone(icalcomponent *component); 41 42 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_from_string(const char *str); 43 44 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_vanew(icalcomponent_kind kind, ...); 45 46 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_x(const char *x_name); 47 48 LIBICAL_ICAL_EXPORT void icalcomponent_free(icalcomponent *component); 49 50 LIBICAL_ICAL_EXPORT char *icalcomponent_as_ical_string(icalcomponent *component); 51 52 LIBICAL_ICAL_EXPORT char *icalcomponent_as_ical_string_r(icalcomponent *component); 53 54 LIBICAL_ICAL_EXPORT int icalcomponent_is_valid(icalcomponent *component); 55 56 LIBICAL_ICAL_EXPORT icalcomponent_kind icalcomponent_isa(const icalcomponent *component); 57 58 LIBICAL_ICAL_EXPORT int icalcomponent_isa_component(void *component); 59 60 /* 61 * Working with properties 62 */ 63 64 LIBICAL_ICAL_EXPORT void icalcomponent_add_property(icalcomponent *component, 65 icalproperty *property); 66 67 LIBICAL_ICAL_EXPORT void icalcomponent_remove_property(icalcomponent *component, 68 icalproperty *property); 69 70 LIBICAL_ICAL_EXPORT int icalcomponent_count_properties(icalcomponent *component, 71 icalproperty_kind kind); 72 73 /** 74 * Sets the parent icalcomponent for the specified icalproperty @p property. 75 * @since 3.0 76 */ 77 LIBICAL_ICAL_EXPORT void icalproperty_set_parent(icalproperty *property, 78 icalcomponent *component); 79 80 /** 81 * Returns the parent @p icalcomponent for the specified @p icalproperty. 82 */ 83 LIBICAL_ICAL_EXPORT icalcomponent *icalproperty_get_parent(const icalproperty *property); 84 85 /* Iterate through the properties */ 86 LIBICAL_ICAL_EXPORT icalproperty *icalcomponent_get_current_property(icalcomponent *component); 87 88 LIBICAL_ICAL_EXPORT icalproperty *icalcomponent_get_first_property(icalcomponent *component, 89 icalproperty_kind kind); 90 LIBICAL_ICAL_EXPORT icalproperty *icalcomponent_get_next_property(icalcomponent *component, 91 icalproperty_kind kind); 92 93 /* 94 * Working with components 95 */ 96 97 /* Return the first VEVENT, VTODO or VJOURNAL sub-component of cop, or 98 comp if it is one of those types */ 99 100 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_inner(icalcomponent *comp); 101 102 LIBICAL_ICAL_EXPORT void icalcomponent_add_component(icalcomponent *parent, icalcomponent *child); 103 104 LIBICAL_ICAL_EXPORT void icalcomponent_remove_component(icalcomponent *parent, 105 icalcomponent *child); 106 107 LIBICAL_ICAL_EXPORT int icalcomponent_count_components(icalcomponent *component, 108 icalcomponent_kind kind); 109 110 /** 111 This takes 2 VCALENDAR components and merges the second one into the first, 112 resolving any problems with conflicting TZIDs. comp_to_merge will no 113 longer exist after calling this function. */ 114 LIBICAL_ICAL_EXPORT void icalcomponent_merge_component(icalcomponent *comp, 115 icalcomponent *comp_to_merge); 116 117 /* Iteration Routines. There are two forms of iterators, internal and 118 external. The internal ones came first, and are almost completely 119 sufficient, but they fail badly when you want to construct a loop that 120 removes components from the container.*/ 121 122 /* Iterate through components */ 123 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_current_component(icalcomponent *component); 124 125 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_first_component(icalcomponent *component, 126 icalcomponent_kind kind); 127 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_next_component(icalcomponent *component, 128 icalcomponent_kind kind); 129 130 /* Using external iterators */ 131 LIBICAL_ICAL_EXPORT icalcompiter icalcomponent_begin_component(icalcomponent *component, 132 icalcomponent_kind kind); 133 134 LIBICAL_ICAL_EXPORT icalcompiter icalcomponent_end_component(icalcomponent *component, 135 icalcomponent_kind kind); 136 137 LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_next(icalcompiter * i); 138 139 LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_prior(icalcompiter * i); 140 141 LIBICAL_ICAL_EXPORT icalcomponent *icalcompiter_deref(icalcompiter * i); 142 143 /* Working with embedded error properties */ 144 145 /* Check the component against itip rules and insert error properties*/ 146 /* Working with embedded error properties */ 147 LIBICAL_ICAL_EXPORT int icalcomponent_check_restrictions(icalcomponent *comp); 148 149 /** Count embedded errors. */ 150 LIBICAL_ICAL_EXPORT int icalcomponent_count_errors(icalcomponent *component); 151 152 /** Remove all X-LIC-ERROR properties*/ 153 LIBICAL_ICAL_EXPORT void icalcomponent_strip_errors(icalcomponent *component); 154 155 /** Convert some X-LIC-ERROR properties into RETURN-STATUS properties*/ 156 LIBICAL_ICAL_EXPORT void icalcomponent_convert_errors(icalcomponent *component); 157 158 /* Internal operations. They are private, and you should not be using them. */ 159 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_parent(icalcomponent *component); 160 161 LIBICAL_ICAL_EXPORT void icalcomponent_set_parent(icalcomponent *component, 162 icalcomponent *parent); 163 164 /* Kind conversion routines */ 165 166 LIBICAL_ICAL_EXPORT int icalcomponent_kind_is_valid(const icalcomponent_kind kind); 167 168 LIBICAL_ICAL_EXPORT icalcomponent_kind icalcomponent_string_to_kind(const char *string); 169 170 LIBICAL_ICAL_EXPORT const char *icalcomponent_kind_to_string(icalcomponent_kind kind); 171 172 /************* Derived class methods. **************************** 173 174 If the code was in an OO language, the remaining routines would be 175 members of classes derived from icalcomponent. Don't call them on the 176 wrong component subtypes. */ 177 178 /** For VCOMPONENT: Return a reference to the first VEVENT, VTODO or 179 VJOURNAL */ 180 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_get_first_real_component(icalcomponent *c); 181 182 /** For VEVENT, VTODO, VJOURNAL and VTIMEZONE: report the start and end 183 times of an event in UTC */ 184 LIBICAL_ICAL_EXPORT struct icaltime_span icalcomponent_get_span(icalcomponent *comp); 185 186 /******************** Convenience routines **********************/ 187 188 LIBICAL_ICAL_EXPORT void icalcomponent_set_dtstart(icalcomponent *comp, struct icaltimetype v); 189 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtstart(icalcomponent *comp); 190 191 /* For the icalcomponent routines only, dtend and duration are tied 192 together. If you call the get routine for one and the other exists, 193 the routine will calculate the return value. That is, if there is a 194 DTEND and you call get_duration, the routine will return the difference 195 between DTEND and DTSTART. However, if you call a set routine for 196 one and the other exists, no action will be taken and icalerrno will 197 be set to ICAL_MALFORMEDDATA_ERROR. If you call a set routine and 198 neither exists, the routine will create the appropriate property. */ 199 200 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtend(icalcomponent *comp); 201 202 LIBICAL_ICAL_EXPORT void icalcomponent_set_dtend(icalcomponent *comp, struct icaltimetype v); 203 204 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_due(icalcomponent *comp); 205 206 LIBICAL_ICAL_EXPORT void icalcomponent_set_due(icalcomponent *comp, struct icaltimetype v); 207 208 LIBICAL_ICAL_EXPORT void icalcomponent_set_duration(icalcomponent *comp, 209 struct icaldurationtype v); 210 211 LIBICAL_ICAL_EXPORT struct icaldurationtype icalcomponent_get_duration(icalcomponent *comp); 212 213 LIBICAL_ICAL_EXPORT void icalcomponent_set_method(icalcomponent *comp, icalproperty_method method); 214 215 LIBICAL_ICAL_EXPORT icalproperty_method icalcomponent_get_method(icalcomponent *comp); 216 217 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_dtstamp(icalcomponent *comp); 218 219 LIBICAL_ICAL_EXPORT void icalcomponent_set_dtstamp(icalcomponent *comp, struct icaltimetype v); 220 221 LIBICAL_ICAL_EXPORT void icalcomponent_set_summary(icalcomponent *comp, const char *v); 222 223 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_summary(icalcomponent *comp); 224 225 LIBICAL_ICAL_EXPORT void icalcomponent_set_comment(icalcomponent *comp, const char *v); 226 227 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_comment(icalcomponent *comp); 228 229 LIBICAL_ICAL_EXPORT void icalcomponent_set_uid(icalcomponent *comp, const char *v); 230 231 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_uid(icalcomponent *comp); 232 233 LIBICAL_ICAL_EXPORT void icalcomponent_set_relcalid(icalcomponent *comp, const char *v); 234 235 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_relcalid(icalcomponent *comp); 236 237 LIBICAL_ICAL_EXPORT void icalcomponent_set_recurrenceid(icalcomponent *comp, 238 struct icaltimetype v); 239 240 LIBICAL_ICAL_EXPORT struct icaltimetype icalcomponent_get_recurrenceid(icalcomponent *comp); 241 242 LIBICAL_ICAL_EXPORT void icalcomponent_set_description(icalcomponent *comp, const char *v); 243 244 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_description(icalcomponent *comp); 245 246 LIBICAL_ICAL_EXPORT void icalcomponent_set_location(icalcomponent *comp, const char *v); 247 248 LIBICAL_ICAL_EXPORT const char *icalcomponent_get_location(icalcomponent *comp); 249 250 LIBICAL_ICAL_EXPORT void icalcomponent_set_sequence(icalcomponent *comp, int v); 251 252 LIBICAL_ICAL_EXPORT int icalcomponent_get_sequence(icalcomponent *comp); 253 254 LIBICAL_ICAL_EXPORT void icalcomponent_set_status(icalcomponent *comp, enum icalproperty_status v); 255 256 LIBICAL_ICAL_EXPORT enum icalproperty_status icalcomponent_get_status(icalcomponent *comp); 257 258 /** Calls the given function for each TZID parameter found in the 259 component, and any subcomponents. */ 260 LIBICAL_ICAL_EXPORT void icalcomponent_foreach_tzid(icalcomponent *comp, 261 void (*callback) (icalparameter *param, 262 void *data), 263 void *callback_data); 264 265 /** Returns the icaltimezone in the component corresponding to the 266 TZID, or NULL if it can't be found. */ 267 LIBICAL_ICAL_EXPORT icaltimezone *icalcomponent_get_timezone(icalcomponent *comp, 268 const char *tzid); 269 270 LIBICAL_ICAL_EXPORT int icalproperty_recurrence_is_excluded(icalcomponent *comp, 271 struct icaltimetype *dtstart, 272 struct icaltimetype *recurtime); 273 274 LIBICAL_ICAL_EXPORT void icalcomponent_foreach_recurrence(icalcomponent *comp, 275 struct icaltimetype start, 276 struct icaltimetype end, 277 void (*callback) (icalcomponent *comp, 278 struct icaltime_span * 279 span, void *data), 280 void *callback_data); 281 282 /** 283 * Normalizes (reorders and sorts the properties) the specified icalcomponent @p comp. 284 * @since 3.0 285 */ 286 LIBICAL_ICAL_EXPORT void icalcomponent_normalize(icalcomponent *comp); 287 288 /* 289 * Computes the datetime corresponding to the specified @p icalproperty and @p icalcomponent. 290 * If the property is a DATE-TIME with a TZID parameter and a corresponding VTIMEZONE 291 * is present in the component, the returned component will already be in the correct 292 * timezone; otherwise the caller is responsible for converting it. 293 * 294 * Call icaltime_is_null_time() on the returned value to detect failures. 295 * 296 * @since 3.0.5 297 */ 298 LIBICAL_ICAL_EXPORT struct icaltimetype icalproperty_get_datetime_with_component( 299 icalproperty *prop, 300 icalcomponent *comp); 301 /*************** Type Specific routines ***************/ 302 303 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vcalendar(void); 304 305 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vevent(void); 306 307 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vtodo(void); 308 309 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vjournal(void); 310 311 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_valarm(void); 312 313 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vfreebusy(void); 314 315 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vtimezone(void); 316 317 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xstandard(void); 318 319 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xdaylight(void); 320 321 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vagenda(void); 322 323 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vquery(void); 324 325 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vavailability(void); 326 327 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xavailable(void); 328 329 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vpoll(void); 330 331 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vvoter(void); 332 333 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xvote(void); 334 335 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_vpatch(void); 336 337 LIBICAL_ICAL_EXPORT icalcomponent *icalcomponent_new_xpatch(void); 338 339 #endif /* !ICALCOMPONENT_H */ 340