src/libical/icalcomponent.h

   1 /* -*- Mode: C -*- */
   2 /*======================================================================
   3  FILE: icalcomponent.h
   4  CREATOR: eric 20 March 1999
   5
   6
   7  (C) COPYRIGHT 2000, Eric Busboom <eric@softwarestudio.org>
   8      http://www.softwarestudio.org
   9
  10  This program is free software; you can redistribute it and/or modify
  11  it under the terms of either:
  12
  13     The LGPL as published by the Free Software Foundation, version
  14     2.1, available at: http://www.fsf.org/copyleft/lesser.html
  15
  16   Or:
  17
  18     The Mozilla Public License Version 1.0. You may obtain a copy of
  19     the License at http://www.mozilla.org/MPL/
  20
  21   The original code is icalcomponent.h
  22
  23 ======================================================================*/
  24
  25 #ifndef ICALCOMPONENT_H
  26 #define ICALCOMPONENT_H
  27
  28 #include "icalproperty.h"
  29 #include "icalvalue.h"
  30 #include "icalenums.h" /* defines icalcomponent_kind */
  31 #include "pvl.h"
  32
  33 typedef struct icalcomponent_impl icalcomponent;
  34
  35 #ifndef ICALTIMEZONE_DEFINED
  36 #define ICALTIMEZONE_DEFINED
  37 /** @brief An opaque struct representing a timezone.
  38  * We declare this here to avoid a circular dependancy.
  39  */
  40 typedef struct _icaltimezone            icaltimezone;
  41 #endif
  42
  43
  44 /* This is exposed so that callers will not have to allocate and
  45    deallocate iterators. Pretend that you can't see it. */
  46 typedef struct icalcompiter
  47 {
  48         icalcomponent_kind kind;
  49         pvl_elem iter;
  50
  51 } icalcompiter;
  52
  53 icalcomponent* icalcomponent_new(icalcomponent_kind kind);
  54 icalcomponent* icalcomponent_new_clone(icalcomponent* component);
  55 icalcomponent* icalcomponent_new_from_string(const char* str);
  56 icalcomponent* icalcomponent_vanew(icalcomponent_kind kind, ...);
  57 icalcomponent* icalcomponent_new_x(const char* x_name);
  58 void icalcomponent_free(icalcomponent* component);
  59
  60 char* icalcomponent_as_ical_string(icalcomponent* component);
  61 char* icalcomponent_as_ical_string_r(icalcomponent* component);
  62
  63 int icalcomponent_is_valid(icalcomponent* component);
  64
  65 icalcomponent_kind icalcomponent_isa(const icalcomponent* component);
  66
  67 int icalcomponent_isa_component (void* component);
  68
  69 /*
  70  * Working with properties
  71  */
  72
  73 void icalcomponent_add_property(icalcomponent* component,
  74                                 icalproperty* property);
  75
  76 void icalcomponent_remove_property(icalcomponent* component,
  77                                    icalproperty* property);
  78
  79 int icalcomponent_count_properties(icalcomponent* component,
  80                                    icalproperty_kind kind);
  81
  82 /* Iterate through the properties */
  83 icalproperty* icalcomponent_get_current_property(icalcomponent* component);
  84
  85 icalproperty* icalcomponent_get_first_property(icalcomponent* component,
  86                                               icalproperty_kind kind);
  87 icalproperty* icalcomponent_get_next_property(icalcomponent* component,
  88                                               icalproperty_kind kind);
  89
  90
  91 /*
  92  * Working with components
  93  */
  94
  95
  96 /* Return the first VEVENT, VTODO or VJOURNAL sub-component of cop, or
  97    comp if it is one of those types */
  98
  99 icalcomponent* icalcomponent_get_inner(icalcomponent* comp);
 100
 101
 102 void icalcomponent_add_component(icalcomponent* parent,
 103                                 icalcomponent* child);
 104
 105 void icalcomponent_remove_component(icalcomponent* parent,
 106                                 icalcomponent* child);
 107
 108 int icalcomponent_count_components(icalcomponent* component,
 109                                    icalcomponent_kind kind);
 110
 111 /**
 112    This takes 2 VCALENDAR components and merges the second one into the first,
 113    resolving any problems with conflicting TZIDs. comp_to_merge will no
 114    longer exist after calling this function. */
 115 void icalcomponent_merge_component(icalcomponent* comp,
 116                                    icalcomponent* comp_to_merge);
 117
 118
 119 /* Iteration Routines. There are two forms of iterators, internal and
 120 external. The internal ones came first, and are almost completely
 121 sufficient, but they fail badly when you want to construct a loop that
 122 removes components from the container.*/
 123
 124
 125 /* Iterate through components */
 126 icalcomponent* icalcomponent_get_current_component (icalcomponent* component);
 127
 128 icalcomponent* icalcomponent_get_first_component(icalcomponent* component,
 129                                               icalcomponent_kind kind);
 130 icalcomponent* icalcomponent_get_next_component(icalcomponent* component,
 131                                               icalcomponent_kind kind);
 132
 133 /* Using external iterators */
 134 icalcompiter icalcomponent_begin_component(icalcomponent* component,
 135                                            icalcomponent_kind kind);
 136 icalcompiter icalcomponent_end_component(icalcomponent* component,
 137                                          icalcomponent_kind kind);
 138 icalcomponent* icalcompiter_next(icalcompiter* i);
 139 icalcomponent* icalcompiter_prior(icalcompiter* i);
 140 icalcomponent* icalcompiter_deref(icalcompiter* i);
 141
 142
 143 /* Working with embedded error properties */
 144
 145
 146 /* Check the component against itip rules and insert error properties*/
 147 /* Working with embedded error properties */
 148 int icalcomponent_check_restrictions(icalcomponent* comp);
 149
 150 /** Count embedded errors. */
 151 int icalcomponent_count_errors(icalcomponent* component);
 152
 153 /** Remove all X-LIC-ERROR properties*/
 154 void icalcomponent_strip_errors(icalcomponent* component);
 155
 156 /** Convert some X-LIC-ERROR properties into RETURN-STATUS properties*/
 157 void icalcomponent_convert_errors(icalcomponent* component);
 158
 159 /* Internal operations. They are private, and you should not be using them. */
 160 icalcomponent* icalcomponent_get_parent(icalcomponent* component);
 161 void icalcomponent_set_parent(icalcomponent* component,
 162                               icalcomponent* parent);
 163
 164 /* Kind conversion routines */
 165
 166 int icalcomponent_kind_is_valid(const icalcomponent_kind kind);
 167
 168 icalcomponent_kind icalcomponent_string_to_kind(const char* string);
 169
 170 const char* icalcomponent_kind_to_string(icalcomponent_kind kind);
 171
 172
 173 /************* Derived class methods.  ****************************
 174
 175 If the code was in an OO language, the remaining routines would be
 176 members of classes derived from icalcomponent. Don't call them on the
 177 wrong component subtypes. */
 178
 179 /** For VCOMPONENT: Return a reference to the first VEVENT, VTODO or
 180    VJOURNAL */
 181 icalcomponent* icalcomponent_get_first_real_component(icalcomponent *c);
 182
 183 /** For VEVENT, VTODO, VJOURNAL and VTIMEZONE: report the start and end
 184    times of an event in UTC */
 185 struct icaltime_span icalcomponent_get_span(icalcomponent* comp);
 186
 187 /******************** Convienience routines **********************/
 188
 189 void icalcomponent_set_dtstart(icalcomponent* comp, struct icaltimetype v);
 190 struct icaltimetype icalcomponent_get_dtstart(icalcomponent* comp);
 191
 192 /* For the icalcomponent routines only, dtend and duration are tied
 193    together. If you call the set routine for one and the other exists,
 194    the routine will calculate the change to the other. That is, if
 195    there is a DTEND and you call set_duration, the routine will modify
 196    DTEND to be the sum of DTSTART and the duration. If you call a get
 197    routine for one and the other exists, the routine will calculate
 198    the return value. If you call a set routine and neither exists, the
 199    routine will create the apcompriate comperty */
 200
 201
 202 struct icaltimetype icalcomponent_get_dtend(icalcomponent* comp);
 203 void icalcomponent_set_dtend(icalcomponent* comp, struct icaltimetype v);
 204
 205 struct icaltimetype icalcomponent_get_due(icalcomponent* comp);
 206 void icalcomponent_set_due(icalcomponent* comp, struct icaltimetype v);
 207
 208 void icalcomponent_set_duration(icalcomponent* comp,
 209                                 struct icaldurationtype v);
 210 struct icaldurationtype icalcomponent_get_duration(icalcomponent* comp);
 211
 212 void icalcomponent_set_method(icalcomponent* comp, icalproperty_method method);
 213 icalproperty_method icalcomponent_get_method(icalcomponent* comp);
 214
 215 struct icaltimetype icalcomponent_get_dtstamp(icalcomponent* comp);
 216 void icalcomponent_set_dtstamp(icalcomponent* comp, struct icaltimetype v);
 217
 218 void icalcomponent_set_summary(icalcomponent* comp, const char* v);
 219 const char* icalcomponent_get_summary(icalcomponent* comp);
 220
 221 void icalcomponent_set_comment(icalcomponent* comp, const char* v);
 222 const char* icalcomponent_get_comment(icalcomponent* comp);
 223
 224 void icalcomponent_set_uid(icalcomponent* comp, const char* v);
 225 const char* icalcomponent_get_uid(icalcomponent* comp);
 226
 227 void icalcomponent_set_relcalid(icalcomponent* comp, const char* v);
 228 const char* icalcomponent_get_relcalid(icalcomponent* comp);
 229
 230 void icalcomponent_set_recurrenceid(icalcomponent* comp,
 231                                     struct icaltimetype v);
 232 struct icaltimetype icalcomponent_get_recurrenceid(icalcomponent* comp);
 233
 234 void icalcomponent_set_description(icalcomponent* comp, const char* v);
 235 const char* icalcomponent_get_description(icalcomponent* comp);
 236
 237 void icalcomponent_set_location(icalcomponent* comp, const char* v);
 238 const char* icalcomponent_get_location(icalcomponent* comp);
 239
 240 void icalcomponent_set_sequence(icalcomponent* comp, int v);
 241 int icalcomponent_get_sequence(icalcomponent* comp);
 242
 243 void icalcomponent_set_status(icalcomponent* comp, enum icalproperty_status v);
 244 enum icalproperty_status icalcomponent_get_status(icalcomponent* comp);
 245
 246
 247 /** Calls the given function for each TZID parameter found in the
 248     component, and any subcomponents. */
 249 void icalcomponent_foreach_tzid(icalcomponent* comp,
 250                                 void (*callback)(icalparameter *param, void *data),
 251                                 void *callback_data);
 252
 253 /** Returns the icaltimezone in the component corresponding to the
 254     TZID, or NULL if it can't be found. */
 255 icaltimezone* icalcomponent_get_timezone(icalcomponent* comp,
 256                                          const char *tzid);
 257
 258 int icalproperty_recurrence_is_excluded(icalcomponent *comp,
 259                                        struct icaltimetype *dtstart,
 260                                        struct icaltimetype *recurtime);
 261
 262 void icalcomponent_foreach_recurrence(icalcomponent* comp,
 263                                       struct icaltimetype start,
 264                                       struct icaltimetype end,
 265                         void (*callback)(icalcomponent *comp,
 266                                          struct icaltime_span *span,
 267                                          void *data),
 268                               void *callback_data);
 269
 270
 271 /*************** Type Specific routines ***************/
 272
 273 icalcomponent* icalcomponent_new_vcalendar(void);
 274 icalcomponent* icalcomponent_new_vevent(void);
 275 icalcomponent* icalcomponent_new_vtodo(void);
 276 icalcomponent* icalcomponent_new_vjournal(void);
 277 icalcomponent* icalcomponent_new_valarm(void);
 278 icalcomponent* icalcomponent_new_vfreebusy(void);
 279 icalcomponent* icalcomponent_new_vtimezone(void);
 280 icalcomponent* icalcomponent_new_xstandard(void);
 281 icalcomponent* icalcomponent_new_xdaylight(void);
 282 icalcomponent* icalcomponent_new_vagenda(void);
 283 icalcomponent* icalcomponent_new_vquery(void);
 284
 285 #endif /* !ICALCOMPONENT_H */