calendar/libecal/e-cal-component.h

   1 /* Evolution calendar - iCalendar component object
   2  *
   3  * Copyright (C) 2000 Ximian, Inc.
   4  * Copyright (C) 2000 Ximian, Inc.
   5  *
   6  * Author: Federico Mena-Quintero <federico@ximian.com>
   7  *
   8  * This program is free software; you can redistribute it and/or
   9  * modify it under the terms of version 2 of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20  */
  21
  22 #ifndef E_CAL_COMPONENT_H
  23 #define E_CAL_COMPONENT_H
  24
  25 #include <glib/gmacros.h>
  26 #include <time.h>
  27 #include <glib-object.h>
  28 #include <libical/ical.h>
  29
  30 G_BEGIN_DECLS
  31
  32 \f
  33
  34 #define E_TYPE_CAL_COMPONENT            (e_cal_component_get_type ())
  35 #define E_CAL_COMPONENT(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), E_TYPE_CAL_COMPONENT, ECalComponent))
  36 #define E_CAL_COMPONENT_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), E_TYPE_CAL_COMPONENT,        \
  37                                        ECalComponentClass))
  38 #define E_IS_CAL_COMPONENT(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), E_TYPE_CAL_COMPONENT))
  39 #define E_IS_CAL_COMPONENT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), E_TYPE_CAL_COMPONENT))
  40
  41 typedef struct {
  42         char *uid;
  43         char *rid;
  44 } ECalComponentId;
  45
  46 /* Types of calendar components to be stored by a ECalComponent, as per RFC 2445.
  47  * We don't put the alarm component type here since we store alarms as separate
  48  * structures inside the other "real" components.
  49  */
  50 typedef enum {
  51         E_CAL_COMPONENT_NO_TYPE,
  52         E_CAL_COMPONENT_EVENT,
  53         E_CAL_COMPONENT_TODO,
  54         E_CAL_COMPONENT_JOURNAL,
  55         E_CAL_COMPONENT_FREEBUSY,
  56         E_CAL_COMPONENT_TIMEZONE
  57 } ECalComponentVType;
  58
  59 /* Field identifiers for a calendar component; these are used by the data model
  60  * for ETable.
  61  *
  62  * NOTE: These are also used in the ETable specification, and the column
  63  *       numbers are saved in the user settings file. So don't reorder them!
  64  */
  65 typedef enum {
  66         E_CAL_COMPONENT_FIELD_CATEGORIES,               /* concatenation of the categories list */
  67         E_CAL_COMPONENT_FIELD_CLASSIFICATION,
  68         E_CAL_COMPONENT_FIELD_COMPLETED,
  69         E_CAL_COMPONENT_FIELD_DTEND,
  70         E_CAL_COMPONENT_FIELD_DTSTART,
  71         E_CAL_COMPONENT_FIELD_DUE,
  72         E_CAL_COMPONENT_FIELD_GEO,
  73         E_CAL_COMPONENT_FIELD_PERCENT,
  74         E_CAL_COMPONENT_FIELD_PRIORITY,
  75         E_CAL_COMPONENT_FIELD_SUMMARY,
  76         E_CAL_COMPONENT_FIELD_TRANSPARENCY,
  77         E_CAL_COMPONENT_FIELD_URL,
  78         E_CAL_COMPONENT_FIELD_HAS_ALARMS,               /* not a real field */
  79         E_CAL_COMPONENT_FIELD_ICON,             /* not a real field */
  80         E_CAL_COMPONENT_FIELD_COMPLETE,         /* not a real field */
  81         E_CAL_COMPONENT_FIELD_RECURRING,                /* not a real field */
  82         E_CAL_COMPONENT_FIELD_OVERDUE,          /* not a real field */
  83         E_CAL_COMPONENT_FIELD_COLOR,            /* not a real field */
  84         E_CAL_COMPONENT_FIELD_STATUS,
  85         E_CAL_COMPONENT_FIELD_COMPONENT,                /* not a real field */
  86         E_CAL_COMPONENT_FIELD_LOCATION,
  87         E_CAL_COMPONENT_FIELD_NUM_FIELDS
  88 } ECalComponentField;
  89
  90 /* Structures and enumerations to return properties and their parameters */
  91
  92 /* CLASSIFICATION property */
  93 typedef enum {
  94         E_CAL_COMPONENT_CLASS_NONE,
  95         E_CAL_COMPONENT_CLASS_PUBLIC,
  96         E_CAL_COMPONENT_CLASS_PRIVATE,
  97         E_CAL_COMPONENT_CLASS_CONFIDENTIAL,
  98         E_CAL_COMPONENT_CLASS_UNKNOWN
  99 } ECalComponentClassification;
 100
 101 /* Properties that have time and timezone information */
 102 typedef struct {
 103         /* Actual date/time value */
 104         struct icaltimetype *value;
 105
 106         /* Timezone ID */
 107         const char *tzid;
 108 } ECalComponentDateTime;
 109
 110 /* Way in which a period of time is specified */
 111 typedef enum {
 112         E_CAL_COMPONENT_PERIOD_DATETIME,
 113         E_CAL_COMPONENT_PERIOD_DURATION
 114 } ECalComponentPeriodType;
 115
 116 /* Period of time, can have explicit start/end times or start/duration instead */
 117 typedef struct {
 118         ECalComponentPeriodType type;
 119
 120         struct icaltimetype start;
 121
 122         union {
 123                 struct icaltimetype end;
 124                 struct icaldurationtype duration;
 125         } u;
 126 } ECalComponentPeriod;
 127
 128 /* The type of range */
 129 typedef enum {
 130         E_CAL_COMPONENT_RANGE_SINGLE,
 131         E_CAL_COMPONENT_RANGE_THISPRIOR,
 132         E_CAL_COMPONENT_RANGE_THISFUTURE
 133 } ECalComponentRangeType;
 134
 135 typedef struct {
 136         ECalComponentRangeType type;
 137
 138         ECalComponentDateTime datetime;
 139 } ECalComponentRange;
 140
 141 /* Text properties */
 142 typedef struct {
 143         /* Description string */
 144         const char *value;
 145
 146         /* Alternate representation URI */
 147         const char *altrep;
 148 } ECalComponentText;
 149
 150 /* Time transparency */
 151 typedef enum {
 152         E_CAL_COMPONENT_TRANSP_NONE,
 153         E_CAL_COMPONENT_TRANSP_TRANSPARENT,
 154         E_CAL_COMPONENT_TRANSP_OPAQUE,
 155         E_CAL_COMPONENT_TRANSP_UNKNOWN
 156 } ECalComponentTransparency;
 157
 158 /* Organizer & Attendee */
 159 typedef struct {
 160         const char *value;
 161
 162         const char *member;
 163         icalparameter_cutype cutype;
 164         icalparameter_role role;
 165         icalparameter_partstat status;
 166         gboolean rsvp;
 167
 168         const char *delto;
 169         const char *delfrom;
 170         const char *sentby;
 171         const char *cn;
 172         const char *language;
 173 } ECalComponentAttendee;
 174
 175 typedef struct {
 176         const char *value;
 177         const char *sentby;
 178         const char *cn;
 179         const char *language;
 180 } ECalComponentOrganizer;
 181
 182 /* Main calendar component object */
 183
 184 typedef struct _ECalComponent ECalComponent;
 185 typedef struct _ECalComponentClass ECalComponentClass;
 186
 187 typedef struct _ECalComponentPrivate ECalComponentPrivate;
 188
 189 struct _ECalComponent {
 190         GObject object;
 191
 192         /*< private >*/
 193         ECalComponentPrivate *priv;
 194 };
 195
 196 struct _ECalComponentClass {
 197         GObjectClass parent_class;
 198 };
 199
 200 /* Calendar component */
 201
 202 GType e_cal_component_get_type (void);
 203
 204 char *e_cal_component_gen_uid (void);
 205
 206 ECalComponent *e_cal_component_new (void);
 207
 208 ECalComponent *e_cal_component_new_from_string (const char *calobj);
 209
 210 ECalComponent *e_cal_component_clone (ECalComponent *comp);
 211
 212 void e_cal_component_set_new_vtype (ECalComponent *comp, ECalComponentVType type);
 213
 214 gboolean e_cal_component_set_icalcomponent (ECalComponent *comp, icalcomponent *icalcomp);
 215 icalcomponent *e_cal_component_get_icalcomponent (ECalComponent *comp);
 216 void e_cal_component_rescan (ECalComponent *comp);
 217 void e_cal_component_strip_errors (ECalComponent *comp);
 218
 219 ECalComponentVType e_cal_component_get_vtype (ECalComponent *comp);
 220
 221 char *e_cal_component_get_as_string (ECalComponent *comp);
 222
 223 void e_cal_component_commit_sequence (ECalComponent *comp);
 224 void e_cal_component_abort_sequence (ECalComponent *comp);
 225
 226 void e_cal_component_get_uid (ECalComponent *comp, const char **uid);
 227 void e_cal_component_set_uid (ECalComponent *comp, const char *uid);
 228
 229 ECalComponentId *e_cal_component_get_id (ECalComponent *comp);
 230 void e_cal_component_free_id (ECalComponentId *id);
 231
 232 void e_cal_component_get_categories (ECalComponent *comp, const char **categories);
 233 void e_cal_component_set_categories (ECalComponent *comp, const char *categories);
 234 void e_cal_component_get_categories_list (ECalComponent *comp, GSList **categ_list);
 235 void e_cal_component_set_categories_list (ECalComponent *comp, GSList *categ_list);
 236
 237 void e_cal_component_get_classification (ECalComponent *comp, ECalComponentClassification *classif);
 238 void e_cal_component_set_classification (ECalComponent *comp, ECalComponentClassification classif);
 239
 240 void e_cal_component_get_comment_list (ECalComponent *comp, GSList **text_list);
 241 void e_cal_component_set_comment_list (ECalComponent *comp, GSList *text_list);
 242
 243 void e_cal_component_get_completed (ECalComponent *comp, struct icaltimetype **t);
 244 void e_cal_component_set_completed (ECalComponent *comp, struct icaltimetype *t);
 245
 246 void e_cal_component_get_contact_list (ECalComponent *comp, GSList **text_list);
 247 void e_cal_component_set_contact_list (ECalComponent *comp, GSList *text_list);
 248
 249 void e_cal_component_get_created (ECalComponent *comp, struct icaltimetype **t);
 250 void e_cal_component_set_created (ECalComponent *comp, struct icaltimetype *t);
 251
 252 void e_cal_component_get_description_list (ECalComponent *comp, GSList **text_list);
 253 void e_cal_component_set_description_list (ECalComponent *comp, GSList *text_list);
 254
 255 void e_cal_component_get_dtend (ECalComponent *comp, ECalComponentDateTime *dt);
 256 void e_cal_component_set_dtend (ECalComponent *comp, ECalComponentDateTime *dt);
 257
 258 void e_cal_component_get_dtstamp (ECalComponent *comp, struct icaltimetype *t);
 259 void e_cal_component_set_dtstamp (ECalComponent *comp, struct icaltimetype *t);
 260
 261 void e_cal_component_get_dtstart (ECalComponent *comp, ECalComponentDateTime *dt);
 262 void e_cal_component_set_dtstart (ECalComponent *comp, ECalComponentDateTime *dt);
 263
 264 void e_cal_component_get_due (ECalComponent *comp, ECalComponentDateTime *dt);
 265 void e_cal_component_set_due (ECalComponent *comp, ECalComponentDateTime *dt);
 266
 267 void e_cal_component_get_exdate_list (ECalComponent *comp, GSList **exdate_list);
 268 void e_cal_component_set_exdate_list (ECalComponent *comp, GSList *exdate_list);
 269 gboolean e_cal_component_has_exdates (ECalComponent *comp);
 270
 271 void e_cal_component_get_exrule_list (ECalComponent *comp, GSList **recur_list);
 272 void e_cal_component_get_exrule_property_list (ECalComponent *comp, GSList **recur_list);
 273 void e_cal_component_set_exrule_list (ECalComponent *comp, GSList *recur_list);
 274 gboolean e_cal_component_has_exrules (ECalComponent *comp);
 275
 276 gboolean e_cal_component_has_exceptions (ECalComponent *comp);
 277
 278 void e_cal_component_get_geo (ECalComponent *comp, struct icalgeotype **geo);
 279 void e_cal_component_set_geo (ECalComponent *comp, struct icalgeotype *geo);
 280
 281 void e_cal_component_get_last_modified (ECalComponent *comp, struct icaltimetype **t);
 282 void e_cal_component_set_last_modified (ECalComponent *comp, struct icaltimetype *t);
 283
 284 void e_cal_component_get_organizer (ECalComponent *comp, ECalComponentOrganizer *organizer);
 285 void e_cal_component_set_organizer (ECalComponent *comp, ECalComponentOrganizer *organizer);
 286 gboolean e_cal_component_has_organizer (ECalComponent *comp);
 287
 288 void e_cal_component_get_percent (ECalComponent *comp, int **percent);
 289 void e_cal_component_set_percent (ECalComponent *comp, int *percent);
 290
 291 void e_cal_component_get_priority (ECalComponent *comp, int **priority);
 292 void e_cal_component_set_priority (ECalComponent *comp, int *priority);
 293
 294 void e_cal_component_get_recurid (ECalComponent *comp, ECalComponentRange *recur_id);
 295 const char *e_cal_component_get_recurid_as_string (ECalComponent *comp);
 296 void e_cal_component_set_recurid (ECalComponent *comp, ECalComponentRange *recur_id);
 297
 298 void e_cal_component_get_rdate_list (ECalComponent *comp, GSList **period_list);
 299 void e_cal_component_set_rdate_list (ECalComponent *comp, GSList *period_list);
 300 gboolean e_cal_component_has_rdates (ECalComponent *comp);
 301
 302 void e_cal_component_get_rrule_list (ECalComponent *comp, GSList **recur_list);
 303 void e_cal_component_get_rrule_property_list (ECalComponent *comp, GSList **recur_list);
 304 void e_cal_component_set_rrule_list (ECalComponent *comp, GSList *recur_list);
 305 gboolean e_cal_component_has_rrules (ECalComponent *comp);
 306
 307 gboolean e_cal_component_has_recurrences (ECalComponent *comp);
 308 gboolean e_cal_component_has_simple_recurrence (ECalComponent *comp);
 309 gboolean e_cal_component_is_instance (ECalComponent *comp);
 310
 311 void e_cal_component_get_sequence (ECalComponent *comp, int **sequence);
 312 void e_cal_component_set_sequence (ECalComponent *comp, int *sequence);
 313
 314 void e_cal_component_get_status (ECalComponent *comp, icalproperty_status *status);
 315 void e_cal_component_set_status (ECalComponent *comp, icalproperty_status status);
 316
 317 void e_cal_component_get_summary (ECalComponent *comp, ECalComponentText *summary);
 318 void e_cal_component_set_summary (ECalComponent *comp, ECalComponentText *summary);
 319
 320 void e_cal_component_get_transparency (ECalComponent *comp, ECalComponentTransparency *transp);
 321 void e_cal_component_set_transparency (ECalComponent *comp, ECalComponentTransparency transp);
 322
 323 void e_cal_component_get_url (ECalComponent *comp, const char **url);
 324 void e_cal_component_set_url (ECalComponent *comp, const char *url);
 325
 326 void e_cal_component_get_attendee_list (ECalComponent *comp, GSList **attendee_list);
 327 void e_cal_component_set_attendee_list (ECalComponent *comp, GSList *attendee_list);
 328 gboolean e_cal_component_has_attendees (ECalComponent *comp);
 329
 330 void e_cal_component_get_location (ECalComponent *comp, const char **location);
 331 void e_cal_component_set_location (ECalComponent *comp, const char *location);
 332
 333 /* Attachment handling */
 334 void e_cal_component_get_attachment_list (ECalComponent *comp, GSList **attachment_list);
 335 void e_cal_component_set_attachment_list (ECalComponent *comp, GSList *attachment_list);
 336 gboolean e_cal_component_has_attachments (ECalComponent *comp);
 337 int e_cal_component_get_num_attachments (ECalComponent *comp);
 338
 339
 340 gboolean e_cal_component_event_dates_match (ECalComponent *comp1, ECalComponent *comp2);
 341
 342
 343 /* Functions to free returned values */
 344
 345 void e_cal_component_free_categories_list (GSList *categ_list);
 346 void e_cal_component_free_datetime (ECalComponentDateTime *dt);
 347 void e_cal_component_free_range (ECalComponentRange *range);
 348 void e_cal_component_free_exdate_list (GSList *exdate_list);
 349 void e_cal_component_free_geo (struct icalgeotype *geo);
 350 void e_cal_component_free_icaltimetype (struct icaltimetype *t);
 351 void e_cal_component_free_percent (int *percent);
 352 void e_cal_component_free_priority (int *priority);
 353 void e_cal_component_free_period_list (GSList *period_list);
 354 void e_cal_component_free_recur_list (GSList *recur_list);
 355 void e_cal_component_free_sequence (int *sequence);
 356 void e_cal_component_free_text_list (GSList *text_list);
 357 void e_cal_component_free_attendee_list (GSList *attendee_list);
 358
 359 /* Alarms */
 360
 361 /* Opaque structure used to represent alarm subcomponents */
 362 typedef struct _ECalComponentAlarm ECalComponentAlarm;
 363
 364 /* An alarm occurrence, i.e. a trigger instance */
 365 typedef struct {
 366         /* UID of the alarm that triggered */
 367         const char *auid;
 368
 369         /* Trigger time, i.e. "5 minutes before the appointment" */
 370         time_t trigger;
 371
 372         /* Actual event occurrence to which this trigger corresponds */
 373         time_t occur_start;
 374         time_t occur_end;
 375 } ECalComponentAlarmInstance;
 376
 377 /* Alarm trigger instances for a particular component */
 378 typedef struct {
 379         /* The actual component */
 380         ECalComponent *comp;
 381
 382         /* List of ECalComponentAlarmInstance structures */
 383         GSList *alarms;
 384 } ECalComponentAlarms;
 385
 386 /* Alarm types */
 387 typedef enum {
 388         E_CAL_COMPONENT_ALARM_NONE,
 389         E_CAL_COMPONENT_ALARM_AUDIO,
 390         E_CAL_COMPONENT_ALARM_DISPLAY,
 391         E_CAL_COMPONENT_ALARM_EMAIL,
 392         E_CAL_COMPONENT_ALARM_PROCEDURE,
 393         E_CAL_COMPONENT_ALARM_UNKNOWN
 394 } ECalComponentAlarmAction;
 395
 396 /* Whether a trigger is relative to the start or end of an event occurrence, or
 397  * whether it is specified to occur at an absolute time.
 398  */
 399 typedef enum {
 400         E_CAL_COMPONENT_ALARM_TRIGGER_NONE,
 401         E_CAL_COMPONENT_ALARM_TRIGGER_RELATIVE_START,
 402         E_CAL_COMPONENT_ALARM_TRIGGER_RELATIVE_END,
 403         E_CAL_COMPONENT_ALARM_TRIGGER_ABSOLUTE
 404 } ECalComponentAlarmTriggerType;
 405
 406 typedef struct {
 407         ECalComponentAlarmTriggerType type;
 408
 409         union {
 410                 struct icaldurationtype rel_duration;
 411                 struct icaltimetype abs_time;
 412         } u;
 413 } ECalComponentAlarmTrigger;
 414
 415 typedef struct {
 416         /* Number of extra repetitions, zero for none */
 417         int repetitions;
 418
 419         /* Interval between repetitions */
 420         struct icaldurationtype duration;
 421 } ECalComponentAlarmRepeat;
 422
 423 gboolean e_cal_component_has_alarms (ECalComponent *comp);
 424 void e_cal_component_add_alarm (ECalComponent *comp, ECalComponentAlarm *alarm);
 425 void e_cal_component_remove_alarm (ECalComponent *comp, const char *auid);
 426 void e_cal_component_remove_all_alarms (ECalComponent *comp);
 427
 428 GList *e_cal_component_get_alarm_uids (ECalComponent *comp);
 429 ECalComponentAlarm *e_cal_component_get_alarm (ECalComponent *comp, const char *auid);
 430
 431 void e_cal_component_alarms_free (ECalComponentAlarms *alarms);
 432
 433 /* ECalComponentAlarms */
 434 ECalComponentAlarm *e_cal_component_alarm_new (void);
 435 ECalComponentAlarm *e_cal_component_alarm_clone (ECalComponentAlarm *alarm);
 436 void e_cal_component_alarm_free (ECalComponentAlarm *alarm);
 437
 438 const char *e_cal_component_alarm_get_uid (ECalComponentAlarm *alarm);
 439
 440 void e_cal_component_alarm_get_action (ECalComponentAlarm *alarm, ECalComponentAlarmAction *action);
 441 void e_cal_component_alarm_set_action (ECalComponentAlarm *alarm, ECalComponentAlarmAction action);
 442
 443 void e_cal_component_alarm_get_attach (ECalComponentAlarm *alarm, icalattach **attach);
 444 void e_cal_component_alarm_set_attach (ECalComponentAlarm *alarm, icalattach *attach);
 445
 446 void e_cal_component_alarm_get_description (ECalComponentAlarm *alarm, ECalComponentText *description);
 447 void e_cal_component_alarm_set_description (ECalComponentAlarm *alarm, ECalComponentText *description);
 448
 449 void e_cal_component_alarm_get_repeat (ECalComponentAlarm *alarm, ECalComponentAlarmRepeat *repeat);
 450 void e_cal_component_alarm_set_repeat (ECalComponentAlarm *alarm, ECalComponentAlarmRepeat repeat);
 451
 452 void e_cal_component_alarm_get_trigger (ECalComponentAlarm *alarm, ECalComponentAlarmTrigger *trigger);
 453 void e_cal_component_alarm_set_trigger (ECalComponentAlarm *alarm, ECalComponentAlarmTrigger trigger);
 454
 455 void e_cal_component_alarm_get_attendee_list (ECalComponentAlarm *alarm, GSList **attendee_list);
 456 void e_cal_component_alarm_set_attendee_list (ECalComponentAlarm *alarm, GSList *attendee_list);
 457 gboolean e_cal_component_alarm_has_attendees (ECalComponentAlarm *alarm);
 458
 459 icalcomponent *e_cal_component_alarm_get_icalcomponent (ECalComponentAlarm *alarm);
 460
 461 \f
 462
 463 G_END_DECLS
 464
 465 #endif