## e-cal-util e-cal-util — Various utility functions. |

## Synopsis

                CalObjInstance;
    void        cal_obj_instance_list_free      (GList *list);
    enum        CalObjModType;
    enum        CalMode;
    #define     cal_mode_to_corba               (mode)
    void        cal_obj_uid_list_free           (GList *list);
    icalcomponent* e_cal_util_new_top_level     (void);
    icalcomponent* e_cal_util_new_component     (icalcomponent_kind kind);
    icalcomponent* e_cal_util_parse_ics_string  (const char *string);
    icalcomponent* e_cal_util_parse_ics_file    (const char *filename);
    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);
    int         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);
    icaltimezone* e_cal_util_resolve_tzid       (const char *tzid,
                                                 gpointer data);
    char*       e_cal_util_priority_to_string   (int priority);
    int         e_cal_util_priority_from_string (const char *string);
    void        e_cal_util_add_timezones_from_component
                                                (icalcomponent *vcal_comp,
                                                 icalcomponent *icalcomp);
    gboolean    e_cal_util_component_is_instance
                                                (icalcomponent *icalcomp);
    gboolean    e_cal_util_component_has_alarms (icalcomponent *icalcomp);
    gboolean    e_cal_util_component_has_organizer
                                                (icalcomponent *icalcomp);
    gboolean    e_cal_util_component_has_recurrences
                                                (icalcomponent *icalcomp);
    gboolean    e_cal_util_component_has_rdates (icalcomponent *icalcomp);
    gboolean    e_cal_util_component_has_rrules (icalcomponent *icalcomp);
    gboolean    e_cal_util_component_has_attendee
                                                (icalcomponent *icalcomp);
    gboolean    e_cal_util_event_dates_match    (icalcomponent *icalcomp1,
                                                 icalcomponent *icalcomp2);
    #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_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_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
    icalcomponent* e_cal_util_construct_instance
                                                (icalcomponent *icalcomp,
                                                 struct icaltimetype rid);
    void        e_cal_util_remove_instances     (icalcomponent *icalcomp,
                                                 struct icaltimetype rid,
                                                 CalObjModType mod);

## Description

## Details

### CalObjInstance

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

### cal_obj_instance_list_free ()

    void        cal_obj_instance_list_free      (GList *list);

Frees a list of CalObjInstance structures.

`list` : | List of CalObjInstance structures.

### enum CalObjModType

    typedef enum {
    	CALOBJ_MOD_THIS          = 1 << 0,
    	CALOBJ_MOD_THISANDPRIOR  = 1 << 1,
    	CALOBJ_MOD_THISANDFUTURE = 1 << 2,
    	CALOBJ_MOD_ALL           = 0x07
    } CalObjModType;

### enum CalMode

    typedef enum {
    	CAL_MODE_INVALID = -1,
    	CAL_MODE_LOCAL   = 1 << 0,
    	CAL_MODE_REMOTE  = 1 << 1,
    	CAL_MODE_ANY     = 0x07
    } CalMode;

### cal_mode_to_corba()

    #define     cal_mode_to_corba(mode)

`mode` : |

### cal_obj_uid_list_free ()

    void        cal_obj_uid_list_free           (GList *list);

Frees a list of unique identifiers for calendar objects.

`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.

`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 char *string);

Parses an iCalendar stirng and returns an 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.

`string` : | iCalendar string to be parsed.
Returns : | an icalcomponent.

### e_cal_util_parse_ics_file ()

    icalcomponent* e_cal_util_parse_ics_file    (const char *filename);

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

`filename` : | Name of the file to be parsed.
Returns : | an icalcomponent.

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

`comp` : | The ECalComponent to generate alarms from.
`start` : | Start time.
`end` : | End time.
`omit` : |
`resolve_tzid` : | Callback for resolving timezones
`user_data` : | Data to be passed to the resolve_tzid callback
`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 on the given time tange. The list of alarms should be freed by using the e_cal_component_free_alarm_list function.

### e_cal_util_generate_alarms_for_list ()

    int         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.

`comps` : | List of ECalComponent's.
`start` : | Start time.
`end` : | End time.
`omit` : |
`comp_alarms` : | List to be returned
`resolve_tzid` : | Callback for resolving timezones
`user_data` : | Data to be passed to the resolve_tzid callback
`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_resolve_tzid ()

    icaltimezone* e_cal_util_resolve_tzid       (const char *tzid,
                                                 gpointer data);

`tzid` : |
`data` : |
Returns : |

### e_cal_util_priority_to_string ()

    char*       e_cal_util_priority_to_string   (int priority);

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

`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 ()

    int         e_cal_util_priority_from_string (const char *string);

Converts a translated priority string to an iCalendar priority value.

`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`.

`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 or not.

`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.

`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 or not.

`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.

`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.

`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.

`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);

`icalcomp` : |
Returns : |

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

`icalcomp1` : | An icalcomponent.
`icalcomp2` : | An icalcomponent.
Returns : | TRUE if the dates of both components match, FALSE otherwise.

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

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

`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,
                                                 CalObjModType mod);

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

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

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