Calendar utilities: Evolution-Data-Server Reference Manual

## Calendar utilities Calendar utilities |

## Functions

void | cal_obj_instance_list_free ()
void | cal_obj_uid_list_free ()
icalcomponent * | e_cal_util_new_top_level ()
icalcomponent * | e_cal_util_new_component ()
icalcomponent * | e_cal_util_parse_ics_string ()
icalcomponent * | e_cal_util_parse_ics_file ()
ECalComponentAlarms * | e_cal_util_generate_alarms_for_comp ()
gint | e_cal_util_generate_alarms_for_list ()
const gchar * | e_cal_util_priority_to_string ()
gint | e_cal_util_priority_from_string ()
void | e_cal_util_add_timezones_from_component ()
gboolean | e_cal_util_component_is_instance ()
gboolean | e_cal_util_component_has_alarms ()
gboolean | e_cal_util_component_has_organizer ()
gboolean | e_cal_util_component_has_recurrences ()
gboolean | e_cal_util_component_has_rdates ()
gboolean | e_cal_util_component_has_rrules ()
gboolean | e_cal_util_component_has_attendee ()
gboolean | e_cal_util_event_dates_match ()
gboolean | e_cal_util_is_first_instance ()
icalcomponent * | e_cal_util_split_at_instance ()
icalcomponent * | e_cal_util_construct_instance ()
void | e_cal_util_remove_instances ()
gchar * | e_cal_util_get_system_timezone_location ()
icaltimezone * | e_cal_util_get_system_timezone ()
void | e_cal_util_get_component_occur_times ()
#define | cal_mode_to_corba()

## Types and Values

| CalObjInstance
#define | CAL_STATIC_CAPABILITY_NO_ALARM_REPEAT
#define | CAL_STATIC_CAPABILITY_NO_AUDIO_ALARMS
#define | CAL_STATIC_CAPABILITY_NO_DISPLAY_ALARMS
#define | CAL_STATIC_CAPABILITY_NO_EMAIL_ALARMS
#define | CAL_STATIC_CAPABILITY_NO_PROCEDURE_ALARMS
#define | CAL_STATIC_CAPABILITY_NO_TASK_ASSIGNMENT
#define | CAL_STATIC_CAPABILITY_NO_THISANDFUTURE
#define | CAL_STATIC_CAPABILITY_NO_THISANDPRIOR
#define | CAL_STATIC_CAPABILITY_NO_TRANSPARENCY
#define | CAL_STATIC_CAPABILITY_NO_MEMO_START_DATE
#define | CAL_STATIC_CAPABILITY_ALARM_DESCRIPTION
#define | CAL_STATIC_CAPABILITY_NO_ALARM_AFTER_START
#define | CAL_STATIC_CAPABILITY_BULK_ADDS
#define | CAL_STATIC_CAPABILITY_BULK_MODIFIES
#define | CAL_STATIC_CAPABILITY_BULK_REMOVES
#define | CAL_STATIC_CAPABILITY_REMOVE_ONLY_THIS
#define | CAL_STATIC_CAPABILITY_ONE_ALARM_ONLY
#define | CAL_STATIC_CAPABILITY_ORGANIZER_MUST_ATTEND
#define | CAL_STATIC_CAPABILITY_ORGANIZER_NOT_EMAIL_ADDRESS
#define | CAL_STATIC_CAPABILITY_REMOVE_ALARMS
#define | CAL_STATIC_CAPABILITY_CREATE_MESSAGES
#define | CAL_STATIC_CAPABILITY_SAVE_SCHEDULES
#define | CAL_STATIC_CAPABILITY_NO_CONV_TO_ASSIGN_TASK
#define | CAL_STATIC_CAPABILITY_NO_CONV_TO_RECUR
#define | CAL_STATIC_CAPABILITY_NO_GEN_OPTIONS
#define | CAL_STATIC_CAPABILITY_REQ_SEND_OPTIONS
#define | CAL_STATIC_CAPABILITY_RECURRENCES_NO_MASTER
#define | CAL_STATIC_CAPABILITY_ORGANIZER_MUST_ACCEPT
#define | CAL_STATIC_CAPABILITY_DELEGATE_SUPPORTED
#define | CAL_STATIC_CAPABILITY_NO_ORGANIZER
#define | CAL_STATIC_CAPABILITY_DELEGATE_TO_MANY
#define | CAL_STATIC_CAPABILITY_HAS_UNACCEPTED_MEETING
#define | CAL_STATIC_CAPABILITY_REFRESH_SUPPORTED
enum | CalMode

## Description

## Functions

### cal_obj_instance_list_free ()

    void
    cal_obj_instance_list_free (GList *list);

Frees a list of CalObjInstance structures.

#### Parameters

list | List of CalObjInstance structures. |

### cal_obj_uid_list_free ()

    void
    cal_obj_uid_list_free (GList *list);

Frees a list of unique identifiers for calendar objects.

#### Parameters

list | List of strings with unique identifiers. |

### e_cal_util_new_top_level ()

    icalcomponent *
    e_cal_util_new_top_level (void);

Creates a new VCALENDAR component.

#### Returns

the newly created top level component.

### e_cal_util_new_component ()

    icalcomponent *
    e_cal_util_new_component (icalcomponent_kind kind);

Creates a new icalcomponent of the specified kind.

#### Parameters

kind | Kind of the component to create. |

#### Returns

the newly created component.

### e_cal_util_parse_ics_string ()

    icalcomponent *
    e_cal_util_parse_ics_string (const gchar *string);

Parses an iCalendar string and returns a new icalcomponent representing that string. Note that this function deals with multiple VCALENDAR's in the string, something that Mozilla used to do and which libical does not support.

#### Parameters

string | iCalendar string to be parsed. |

#### Returns

a newly created icalcomponent or NULL if the string isn't a valid iCalendar string.

### e_cal_util_parse_ics_file ()

    icalcomponent *
    e_cal_util_parse_ics_file (const gchar *filename);

Parses the given file, and, if it contains a valid iCalendar object, parse it and return a new icalcomponent.

#### Parameters

filename | Name of the file to be parsed. |

#### Returns

a newly created icalcomponent or NULL if the file doesn't contain a valid iCalendar object.

### e_cal_util_generate_alarms_for_comp ()

    ECalComponentAlarms *
    e_cal_util_generate_alarms_for_comp (ECalComponent *comp,
                                         time_t start,
                                         time_t end,
                                         ECalComponentAlarmAction *omit,
                                         ECalRecurResolveTimezoneFn resolve_tzid,
                                         gpointer user_data,
                                         icaltimezone *default_timezone);

Generates alarm instances for a calendar component. Returns the instances structure, or `NULL` if no alarm instances occurred in the specified time range.

#### Parameters

comp | The ECalComponent to generate alarms from |
start | Start time |
end | End time |
omit | Alarm types to omit |
resolve_tzid | Callback for resolving timezones. | [closure user_data][scope call]
user_data | Data to be passed to the resolve_tzid callback. | [closure]
default_timezone | The timezone used to resolve DATE and floating DATE-TIME values. |

#### Returns

a list of all the alarms found for the given component in the given time range. The list of alarms should be freed by using `e_cal_component_free_alarm_list()`.

[allow-none][transfer full]

### e_cal_util_generate_alarms_for_list ()

    gint
    e_cal_util_generate_alarms_for_list (GList *comps,
                                         time_t start,
                                         time_t end,
                                         ECalComponentAlarmAction *omit,
                                         GSList **comp_alarms,
                                         ECalRecurResolveTimezoneFn resolve_tzid,
                                         gpointer user_data,
                                         icaltimezone *default_timezone);

Iterates through all the components in the `comps` list and generates alarm instances for them; putting them in the `comp_alarms` list.

#### Parameters

comps | List of ECalComponents. | [element-type ECalComponent]
start | Start time |
end | End time |
omit | Alarm types to omit |
comp_alarms | List to be returned. | [out][transfer full][element-type ECalComponentAlarms]
resolve_tzid | Callback for resolving timezones. | [closure user_data][scope call]
user_data | Data to be passed to the resolve_tzid callback. | [closure]
default_timezone | The timezone used to resolve DATE and floating DATE-TIME values. |

#### Returns

the number of elements it added to the list

### e_cal_util_priority_to_string ()

    const gchar *
    e_cal_util_priority_to_string (gint priority);

Converts an iCalendar PRIORITY value to a translated string. Any unknown priority value (i.e. not 0-9) will be returned as "" (undefined).

#### Parameters

priority | Priority value. |

#### Returns

a string representing the PRIORITY value. This value is a constant, so it should never be freed.

### e_cal_util_priority_from_string ()

    gint
    e_cal_util_priority_from_string (const gchar *string);

Converts a translated priority string to an iCalendar priority value.

#### Parameters

string | A string representing the PRIORITY value. |

#### Returns

the priority (0-9) or -1 if the priority string is not valid.

### e_cal_util_add_timezones_from_component ()

    void
    e_cal_util_add_timezones_from_component
                                   (icalcomponent *vcal_comp,
                                    icalcomponent *icalcomp);

Adds VTIMEZONE components to a VCALENDAR for all tzid's in the given `icalcomp` .

#### Parameters

vcal_comp | A VCALENDAR component. |
icalcomp | An iCalendar component, of any type. |

### e_cal_util_component_is_instance ()

    gboolean
    e_cal_util_component_is_instance (icalcomponent *icalcomp);

Checks whether an icalcomponent is an instance of a recurring appointment.

#### Parameters

icalcomp | An icalcomponent. |

#### Returns

TRUE if it is an instance, FALSE if not.

### e_cal_util_component_has_alarms ()

    gboolean
    e_cal_util_component_has_alarms (icalcomponent *icalcomp);

Checks whether an icalcomponent has any alarm.

#### Parameters

icalcomp | An icalcomponent. |

#### Returns

TRUE if it has alarms, FALSE otherwise.

### e_cal_util_component_has_organizer ()

    gboolean
    e_cal_util_component_has_organizer (icalcomponent *icalcomp);

Checks whether an icalcomponent has an organizer.

#### Parameters

icalcomp | An icalcomponent. |

#### Returns

TRUE if there is an organizer, FALSE if not.

### e_cal_util_component_has_recurrences ()

    gboolean
    e_cal_util_component_has_recurrences (icalcomponent *icalcomp);

Checks if an icalcomponent has recurrence dates or rules.

#### Parameters

icalcomp | An icalcomponent. |

#### Returns

TRUE if there are recurrence dates/rules, FALSE if not.

### e_cal_util_component_has_rdates ()

    gboolean
    e_cal_util_component_has_rdates (icalcomponent *icalcomp);

Checks if an icalcomponent has recurrence dates.

#### Parameters

icalcomp | An icalcomponent. |

#### Returns

TRUE if there are recurrence dates, FALSE if not.

### e_cal_util_component_has_rrules ()

    gboolean
    e_cal_util_component_has_rrules (icalcomponent *icalcomp);

Checks if an icalcomponent has recurrence rules.

#### Parameters

icalcomp | An icalcomponent. |

#### Returns

TRUE if there are recurrence rules, FALSE if not.

### e_cal_util_component_has_attendee ()

    gboolean
    e_cal_util_component_has_attendee (icalcomponent *icalcomp);

Checks if an icalcomponent has any attendees.

#### Parameters

icalcomp | An icalcomponent. |

#### Returns

TRUE if there are attendees, FALSE if not.

### e_cal_util_event_dates_match ()

    gboolean
    e_cal_util_event_dates_match (icalcomponent *icalcomp1,
                                  icalcomponent *icalcomp2);

Compare the dates of two icalcomponent's to check if they match.

#### Parameters

icalcomp1 | An icalcomponent. |
icalcomp2 | An icalcomponent. |

#### Returns

TRUE if the dates of both components match, FALSE otherwise.

### e_cal_util_is_first_instance ()

    gboolean
    e_cal_util_is_first_instance (ECalComponent *comp,
                                  struct icaltimetype rid,
                                  ECalRecurResolveTimezoneFn tz_cb,
                                  gpointer tz_cb_data);

Returns whether the given `rid` is the first instance of the recurrence defined in the `comp` .

Return: Whether the `rid` identifies the first instance of `comp` .

#### Parameters

comp | an ECalComponent instance |
rid | a recurrence ID |
tz_cb | The ECalRecurResolveTimezoneFn to call. | [closure tz_cb_data][scope call]
tz_cb_data | User data to be passed to the `tz_cb` callback. | [closure]

Since: 3.16

### e_cal_util_split_at_instance ()

    icalcomponent *
    e_cal_util_split_at_instance (icalcomponent *icalcomp,
                                  struct icaltimetype rid,
                                  struct icaltimetype master_dtstart);

Splits a recurring `icalcomp` into two at time `rid` . The returned icalcomponent is modified `icalcomp` which contains recurrences beginning at `rid` , inclusive. The instance identified by `rid` should exist. The `master_dtstart` can be a null time, then it is read from the `icalcomp` .

Use `e_cal_util_remove_instances()` with E_CAL_OBJ_MOD_THIS_AND_FUTURE mode on the `icalcomp` to remove the overlapping interval from it, if needed.

#### Parameters

icalcomp | A (recurring) icalcomponent |
rid | The base RECURRENCE-ID to remove |
master_dtstart | The DTSTART of the master object |

#### Returns

the split icalcomponent, or `NULL`.

Since: 3.16

### e_cal_util_construct_instance ()

    icalcomponent *
    e_cal_util_construct_instance (icalcomponent *icalcomp,
                                   struct icaltimetype rid);

This checks that `rid` indicates a valid recurrence of `icalcomp` , and if so, generates a copy of `comp` containing a RECURRENCE-ID of `rid` .

#### Parameters

icalcomp | A recurring icalcomponent |
rid | The RECURRENCE-ID to construct a component for |

#### Returns

the instance, or `NULL`.

### e_cal_util_remove_instances ()

    void
    e_cal_util_remove_instances (icalcomponent *icalcomp,
                                 struct icaltimetype rid,
                                 ECalObjModType mod);

Removes one or more instances from `comp` according to `rid` and `mod` .

FIXME: should probably have a return value indicating whether `icalcomp` still has any instances

#### Parameters

icalcomp | A (recurring) icalcomponent |
rid | The base RECURRENCE-ID to remove |
mod | How to interpret `rid` |

### e_cal_util_get_system_timezone_location ()

    gchar *
    e_cal_util_get_system_timezone_location
                                   (void);

Fetches system timezone localtion string.

#### Returns

system timezone location string, `NULL` on an error.

[transfer full]

Since: 2.28

### e_cal_util_get_system_timezone ()

    icaltimezone *
    e_cal_util_get_system_timezone (void);

Fetches system timezone icaltimezone object.

The returned pointer is part of the built-in timezones and should not be freed.

#### Returns

The icaltimezone object of the system timezone, or `NULL` on an error.

[transfer none]

Since: 2.28

### e_cal_util_get_component_occur_times ()

    void
    e_cal_util_get_component_occur_times (ECalComponent *comp,
                                          time_t *start,
                                          time_t *end,
                                          ECalRecurResolveTimezoneFn tz_cb,
                                          gpointer tz_cb_data,
                                          const icaltimezone *default_timezone,
                                          icalcomponent_kind kind);

Find out when the component starts and stops, being careful about recurrences.

#### Parameters

comp | an ECalComponent |
start | Location to store the start time. | [out]
end | Location to store the end time. | [out]
tz_cb | The ECalRecurResolveTimezoneFn to call. | [closure tz_cb_data][scope call]
tz_cb_data | User data to be passed to the `tz_cb` callback. | [closure]
default_timezone | The default timezone |
kind | the type of component, indicated with an icalcomponent_kind |

Since: 2.32

### cal_mode_to_corba()

    #define             cal_mode_to_corba(mode)

`cal_mode_to_corba` is deprecated and should not be used in newly-written code.

## Types and Values

### CalObjInstance

    typedef struct {
    	gchar *uid;			/* UID of the object */
    	time_t start;			/* Start time of instance */
    	time_t end;			/* End time of instance */
    } CalObjInstance;

Instance of a calendar object. This can be an actual occurrence, a recurrence, or an alarm trigger of a `real' calendar object.

#### Members

gchar *`uid`; | UID of the object |
time_t `start`; | Start time of instance |
time_t `end`; | End time of instance |

### CAL_STATIC_CAPABILITY_NO_ALARM_REPEAT

    #define CAL_STATIC_CAPABILITY_NO_ALARM_REPEAT		"no-alarm-repeat"

### CAL_STATIC_CAPABILITY_NO_AUDIO_ALARMS

    #define CAL_STATIC_CAPABILITY_NO_AUDIO_ALARMS		"no-audio-alarms"

### CAL_STATIC_CAPABILITY_NO_DISPLAY_ALARMS

    #define CAL_STATIC_CAPABILITY_NO_DISPLAY_ALARMS		"no-display-alarms"

### CAL_STATIC_CAPABILITY_NO_EMAIL_ALARMS

    #define CAL_STATIC_CAPABILITY_NO_EMAIL_ALARMS		"no-email-alarms"

### CAL_STATIC_CAPABILITY_NO_PROCEDURE_ALARMS

    #define CAL_STATIC_CAPABILITY_NO_PROCEDURE_ALARMS "no-procedure-alarms"

### CAL_STATIC_CAPABILITY_NO_TASK_ASSIGNMENT

    #define CAL_STATIC_CAPABILITY_NO_TASK_ASSIGNMENT "no-task-assignment"

### CAL_STATIC_CAPABILITY_NO_THISANDFUTURE

    #define CAL_STATIC_CAPABILITY_NO_THISANDFUTURE		"no-thisandfuture"

### CAL_STATIC_CAPABILITY_NO_THISANDPRIOR

    #define CAL_STATIC_CAPABILITY_NO_THISANDPRIOR		"no-thisandprior"

### CAL_STATIC_CAPABILITY_NO_TRANSPARENCY

    #define CAL_STATIC_CAPABILITY_NO_TRANSPARENCY		"no-transparency"

### CAL_STATIC_CAPABILITY_NO_MEMO_START_DATE

    #define CAL_STATIC_CAPABILITY_NO_MEMO_START_DATE "no-memo-start-date"

### CAL_STATIC_CAPABILITY_ALARM_DESCRIPTION

    #define CAL_STATIC_CAPABILITY_ALARM_DESCRIPTION		"alarm-description"

Flag indicating that the backend supports alarm description

Since: 3.8

### CAL_STATIC_CAPABILITY_NO_ALARM_AFTER_START

    #define CAL_STATIC_CAPABILITY_NO_ALARM_AFTER_START "no-alarm-after-start"

Flag indicating that the backend does not support alarm after start the event

Since: 3.8

### CAL_STATIC_CAPABILITY_BULK_ADDS

    #define CAL_STATIC_CAPABILITY_BULK_ADDS			"bulk-adds"

Flag indicating that the backend supports bulk additions.

Since: 3.6

### CAL_STATIC_CAPABILITY_BULK_MODIFIES

    #define CAL_STATIC_CAPABILITY_BULK_MODIFIES		"bulk-modifies"

Flag indicating that the backend supports bulk modifications.

Since: 3.6

### CAL_STATIC_CAPABILITY_BULK_REMOVES

    #define CAL_STATIC_CAPABILITY_BULK_REMOVES		"bulk-removes"

Flag indicating that the backend supports bulk removals.

Since: 3.6

### CAL_STATIC_CAPABILITY_REMOVE_ONLY_THIS

    #define CAL_STATIC_CAPABILITY_REMOVE_ONLY_THIS		"remove-only-this"

FIXME: Document me.

Since: 3.2

### CAL_STATIC_CAPABILITY_ONE_ALARM_ONLY

    #define CAL_STATIC_CAPABILITY_ONE_ALARM_ONLY		"one-alarm-only"

### CAL_STATIC_CAPABILITY_ORGANIZER_MUST_ATTEND

    #define CAL_STATIC_CAPABILITY_ORGANIZER_MUST_ATTEND "organizer-must-attend"

### CAL_STATIC_CAPABILITY_ORGANIZER_NOT_EMAIL_ADDRESS

    #define CAL_STATIC_CAPABILITY_ORGANIZER_NOT_EMAIL_ADDRESS "organizer-not-email-address"

### CAL_STATIC_CAPABILITY_REMOVE_ALARMS

    #define CAL_STATIC_CAPABILITY_REMOVE_ALARMS		"remove-alarms"

### CAL_STATIC_CAPABILITY_CREATE_MESSAGES

    #define CAL_STATIC_CAPABILITY_CREATE_MESSAGES		"create-messages"

Since: 2.26

### CAL_STATIC_CAPABILITY_SAVE_SCHEDULES

    #define CAL_STATIC_CAPABILITY_SAVE_SCHEDULES		"save-schedules"

### CAL_STATIC_CAPABILITY_NO_CONV_TO_ASSIGN_TASK

    #define CAL_STATIC_CAPABILITY_NO_CONV_TO_ASSIGN_TASK "no-conv-to-assign-task"

### CAL_STATIC_CAPABILITY_NO_CONV_TO_RECUR

    #define CAL_STATIC_CAPABILITY_NO_CONV_TO_RECUR		"no-conv-to-recur"

### CAL_STATIC_CAPABILITY_NO_GEN_OPTIONS

    #define CAL_STATIC_CAPABILITY_NO_GEN_OPTIONS		"no-general-options"

### CAL_STATIC_CAPABILITY_REQ_SEND_OPTIONS

    #define CAL_STATIC_CAPABILITY_REQ_SEND_OPTIONS		"require-send-options"

### CAL_STATIC_CAPABILITY_RECURRENCES_NO_MASTER

    #define CAL_STATIC_CAPABILITY_RECURRENCES_NO_MASTER "recurrences-no-master-object"

### CAL_STATIC_CAPABILITY_ORGANIZER_MUST_ACCEPT

    #define CAL_STATIC_CAPABILITY_ORGANIZER_MUST_ACCEPT "organizer-must-accept"

### CAL_STATIC_CAPABILITY_DELEGATE_SUPPORTED

    #define CAL_STATIC_CAPABILITY_DELEGATE_SUPPORTED "delegate-support"

### CAL_STATIC_CAPABILITY_NO_ORGANIZER

    #define CAL_STATIC_CAPABILITY_NO_ORGANIZER		"no-organizer"

### CAL_STATIC_CAPABILITY_DELEGATE_TO_MANY

    #define CAL_STATIC_CAPABILITY_DELEGATE_TO_MANY		"delegate-to-many"

### CAL_STATIC_CAPABILITY_HAS_UNACCEPTED_MEETING

    #define CAL_STATIC_CAPABILITY_HAS_UNACCEPTED_MEETING "has-unaccepted-meeting"

### CAL_STATIC_CAPABILITY_REFRESH_SUPPORTED

    #define CAL_STATIC_CAPABILITY_REFRESH_SUPPORTED		"refresh-supported"

Since: 2.30

### enum CalMode

`CalMode` is deprecated and should not be used in newly-written code.

#### Members

CAL_MODE_INVALID |  |
CAL_MODE_LOCAL |  |
CAL_MODE_REMOTE |  |
CAL_MODE_ANY |  |