## 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);
    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` : | Alarm types to 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` : | Alarm types to 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_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);

Checks if an icalcomponent has any attendees.

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

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