## e-cal-util e-cal-util |

## 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 ()
icalcomponent * | e_cal_util_construct_instance ()
void | e_cal_util_remove_instances ()
icalcomponent * | e_cal_util_split_at_instance ()
gboolean | e_cal_util_is_first_instance ()
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
#define | CAL_STATIC_CAPABILITY_ALL_DAY_EVENT_AS_TIME
#define | CAL_STATIC_CAPABILITY_TASK_DATE_ONLY
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. | [element-type CalObjInstance]

### 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. | [element-type utf8]

### 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_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_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_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_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

### CAL_STATIC_CAPABILITY_ALL_DAY_EVENT_AS_TIME

    #define CAL_STATIC_CAPABILITY_ALL_DAY_EVENT_AS_TIME "all-day-event-as-time"

Let the client know that it should store All Day event times as time with a time zone, rather than as a date.

Since: 3.18

### CAL_STATIC_CAPABILITY_TASK_DATE_ONLY

    #define CAL_STATIC_CAPABILITY_TASK_DATE_ONLY		"task-date-only"

Let the client know that the Task Start date, Due date and Completed date can be entered only as dates. When the capability is not set, then these can be date and time.

Since: 3.24

### 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 |  |