src/libical/vcomponent.h

   1 /* -*- Mode: C++ -*- */
   2
   3 /**
   4  * @file    vcomponent.h
   5  * @author  fnguyen (12/10/01)
   6  * @brief   C++ classes for the icalcomponent wrapper (VToDo VEvent, etc..).
   7  *
   8  * (C) COPYRIGHT 2001, Critical Path
   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
  22 #ifndef VCOMPONENT_H
  23 #define VCOMPONENT_H
  24
  25 #include "ical.h"
  26 #include "icptrholder.h"
  27
  28 typedef char* string; // Will use the string library from STL
  29
  30 class ICalProperty;
  31
  32 /**
  33  * @class VComponent
  34  * @brief A class wrapping the libical icalcomponent functions
  35  *
  36  * @exception icalerrorenum   Any errors generated in libical are
  37  *                            propogated via this exception type.
  38  */
  39
  40 class VComponent {
  41 public:
  42         VComponent()                             throw (icalerrorenum);
  43         VComponent(const VComponent&)            throw (icalerrorenum);
  44         VComponent& operator=(const VComponent&) throw (icalerrorenum);
  45         virtual ~VComponent();
  46
  47         VComponent(icalcomponent* v)        throw (icalerrorenum);
  48         VComponent(string str)              throw (icalerrorenum);
  49         VComponent(icalcomponent_kind kind) throw (icalerrorenum);;
  50
  51         operator icalcomponent* () { return imp; }
  52
  53         void new_from_string(string str);
  54
  55         // detach imp to this object. use with caution. it would cause
  56         // memory leak if you are not careful.
  57         void detach() {
  58             imp = NULL;
  59         }
  60
  61 public:
  62         string as_ical_string() throw (icalerrorenum);
  63         bool is_valid();
  64         icalcomponent_kind isa();
  65         int isa_component(void* component);
  66
  67         /// Working with properties
  68         void add_property(ICalProperty* property);
  69         void remove_property(ICalProperty* property);
  70         int count_properties(icalproperty_kind kind);
  71
  72         // Iterate through the properties
  73         ICalProperty* get_current_property();
  74         ICalProperty* get_first_property(icalproperty_kind kind);
  75         ICalProperty* get_next_property(icalproperty_kind kind);
  76
  77         // Working with components
  78
  79         /**
  80          *  Return the first VEVENT, VTODO or VJOURNAL sub-component if
  81          *   it is one of those types
  82          */
  83
  84         VComponent* get_inner();
  85
  86         void add_component(VComponent* child);
  87         void remove_component(VComponent* child);
  88         int count_components(icalcomponent_kind kind);
  89
  90         /**
  91          * Iteration Routines. There are two forms of iterators,
  92          * internal and external. The internal ones came first, and
  93          * are almost completely sufficient, but they fail badly when
  94          * you want to construct a loop that removes components from
  95          * the container.
  96         */
  97
  98         /// Iterate through components
  99         VComponent* get_current_component();
 100         VComponent* get_first_component(icalcomponent_kind kind);
 101         VComponent* get_next_component(icalcomponent_kind kind);
 102
 103         /// Using external iterators
 104         icalcompiter begin_component(icalcomponent_kind kind);
 105         icalcompiter end_component(icalcomponent_kind kind);
 106         VComponent* next(icalcompiter* i);
 107         VComponent* prev(icalcompiter* i);
 108         VComponent* current(icalcompiter* i);
 109
 110         /// Working with embedded error properties
 111         int count_errors();
 112
 113         /// Remove all X-LIC-ERROR properties
 114         void strip_errors();
 115
 116         /// Convert some X-LIC-ERROR properties into RETURN-STATUS properties
 117         void convert_errors();
 118
 119         /// Kind conversion routines
 120         static icalcomponent_kind string_to_kind(string str);
 121         static string kind_to_string(icalcomponent_kind kind);
 122
 123 public:
 124         struct icaltimetype get_dtstart();
 125         void set_dtstart(struct icaltimetype v);
 126
 127         /** For the icalcomponent routines only, dtend and duration
 128          *  are tied together. If you call the set routine for one and
 129          *  the other exists, the routine will calculate the change to
 130          *  the other. That is, if there is a DTEND and you call
 131          *  set_duration, the routine will modify DTEND to be the sum
 132          *  of DTSTART and the duration. If you call a get routine for
 133          *  one and the other exists, the routine will calculate the
 134          *  return value. If you call a set routine and neither
 135          *  exists, the routine will create the apropriate property
 136         */
 137
 138         struct icaltimetype get_dtend();
 139         void set_dtend(struct icaltimetype v);
 140
 141         struct icaltimetype get_due();
 142         void set_due(struct icaltimetype v);
 143
 144         struct icaldurationtype get_duration();
 145         void set_duration(struct icaldurationtype v);
 146
 147         icalproperty_method get_method();
 148         void set_method(icalproperty_method method);
 149
 150         struct icaltimetype get_dtstamp();
 151         void set_dtstamp(struct icaltimetype v);
 152
 153         string get_summary();
 154         void set_summary(string v);
 155
 156         string get_location();
 157         void set_location(string v);
 158
 159         string get_description();
 160         void set_description(string v);
 161
 162         string get_comment();
 163         void set_comment(string v);
 164
 165         string get_uid();
 166         void set_uid(string v);
 167
 168         string get_relcalid();
 169         void set_relcalid(string v);
 170
 171         struct icaltimetype get_recurrenceid();
 172         void set_recurrenceid(struct icaltimetype v);
 173
 174         int get_sequence();
 175         void set_sequence(int v);
 176
 177         int get_status();
 178         void set_status(enum icalproperty_status v);
 179
 180
 181 public:
 182         /**
 183          * For VCOMPONENT: Return a reference to the first VEVENT,
 184          * VTODO, or VJOURNAL
 185         */
 186         VComponent* get_first_real_component();
 187
 188         /**
 189          * For VEVENT, VTODO, VJOURNAL and VTIMEZONE: report the
 190          * start and end times of an event in UTC
 191          */
 192         virtual struct icaltime_span get_span();
 193
 194         int recurrence_is_excluded(struct icaltimetype *dtstart,
 195                                    struct icaltimetype *recurtime);
 196
 197
 198 public:
 199         /**
 200            helper functions for adding/removing/updating property and
 201            sub-components */
 202
 203         /// Note: the VComponent kind have to be the same
 204
 205         bool remove(VComponent&, bool ignoreValue);
 206         bool update(VComponent&, bool removeMissing);
 207         bool add(VComponent&);
 208
 209 private:
 210         /* Internal operations. They are private, and you should not be using them. */
 211         VComponent* get_parent();
 212         void set_parent(VComponent *parent);
 213
 214         char* quote_ical_string(char* str);
 215
 216 private:
 217         icalcomponent* imp;
 218 };
 219
 220 class VCalendar : public VComponent {
 221 public:
 222         VCalendar();
 223         VCalendar(const VCalendar&);
 224         VCalendar& operator=(const VCalendar&);
 225         ~VCalendar();
 226
 227         VCalendar(icalcomponent* v);
 228         VCalendar(string str);
 229 };
 230
 231
 232 class VEvent : public VComponent {
 233 public:
 234         VEvent();
 235         VEvent(const VEvent&);
 236         VEvent& operator=(const VEvent&);
 237         ~VEvent();
 238
 239         VEvent(icalcomponent* v);
 240         VEvent(string str);
 241 };
 242
 243 class VToDo : public VComponent {
 244 public:
 245         VToDo();
 246         VToDo(const VToDo&);
 247         VToDo& operator=(const VToDo&);
 248         ~VToDo();
 249
 250         VToDo(icalcomponent* v);
 251         VToDo(string str);
 252 };
 253
 254 class VAgenda : public VComponent {
 255 public:
 256         VAgenda();
 257         VAgenda(const VAgenda&);
 258         VAgenda& operator=(const VAgenda&);
 259         ~VAgenda();
 260
 261         VAgenda(icalcomponent* v);
 262         VAgenda(string str);
 263 };
 264
 265 class VQuery : public VComponent {
 266 public:
 267         VQuery();
 268         VQuery(const VQuery&);
 269         VQuery& operator=(const VQuery&);
 270         ~VQuery();
 271
 272         VQuery(icalcomponent* v);
 273         VQuery(string str);
 274 };
 275
 276 class VJournal : public VComponent {
 277 public:
 278         VJournal();
 279         VJournal(const VJournal&);
 280         VJournal& operator=(const VJournal&);
 281         ~VJournal();
 282
 283         VJournal(icalcomponent* v);
 284         VJournal(string str);
 285 };
 286
 287 class VAlarm : public VComponent {
 288 public:
 289         VAlarm();
 290         VAlarm(const VAlarm&);
 291         VAlarm& operator=(const VAlarm&);
 292         ~VAlarm();
 293
 294         VAlarm(icalcomponent* v);
 295         VAlarm(string str);
 296
 297         /**
 298          *  compute the absolute trigger time for this alarm. trigger
 299          *  may be related to the containing component c.  the result
 300          *  is populated in tr->time
 301          */
 302         icalrequeststatus getTriggerTime(VComponent &c, struct icaltriggertype *tr);
 303 };
 304
 305 class VFreeBusy : public VComponent {
 306 public:
 307         VFreeBusy();
 308         VFreeBusy(const VFreeBusy&);
 309         VFreeBusy& operator=(const VFreeBusy&);
 310         ~VFreeBusy();
 311
 312         VFreeBusy(icalcomponent* v);
 313         VFreeBusy(string str);
 314 };
 315
 316 class VTimezone : public VComponent {
 317 public:
 318         VTimezone();
 319         VTimezone(const VTimezone&);
 320         VTimezone& operator=(const VTimezone&);
 321         ~VTimezone();
 322
 323         VTimezone(icalcomponent* v);
 324         VTimezone(string str);
 325 };
 326
 327 class XStandard : public VComponent {
 328 public:
 329         XStandard();
 330         XStandard(const XStandard&);
 331         XStandard& operator=(const XStandard&);
 332         ~XStandard();
 333
 334         XStandard(icalcomponent* v);
 335         XStandard(string str);
 336 };
 337
 338 class XDaylight : public VComponent {
 339 public:
 340         XDaylight();
 341         XDaylight(const XDaylight&);
 342         XDaylight& operator=(const XDaylight&);
 343         ~XDaylight();
 344
 345         XDaylight(icalcomponent* v);
 346         XDaylight(string str);
 347 };
 348
 349 typedef ICPointerHolder<VComponent> VComponentTmpPtr; /* see icptrholder.h for comments */
 350
 351 #endif /* VComponent_H */