## e-cal-util

e-cal-util —

## Synopsis

                CalObjInstance;
    void        cal_obj_instance_list_free      (GList *list);
    enum        CalObjModType;
    enum        CalMode;
    void        cal_obj_uid_list_free           (GList *list);
    icalcomponent* e_cal_util_new_top_level     (void);
    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);
    char*       e_cal_util_expand_uri           (char *uri,
                                                 gboolean tasks);
    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_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
    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_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);

Returns : |

### e_cal_util_parse_ics_file ()

    icalcomponent* e_cal_util_parse_ics_file    (const char *filename);

`filename` : |
Returns : |

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

### 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 that 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);

`priority` : |
Returns : |

### e_cal_util_priority_from_string ()

    int         e_cal_util_priority_from_string (const char *string);

`string` : |
Returns : |

### e_cal_util_expand_uri ()

    char*       e_cal_util_expand_uri           (char *uri,
                                                 gboolean tasks);

`uri` : |
`tasks` : |
Returns : |

### e_cal_util_add_timezones_from_component ()

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

`vcal_comp` : |
`icalcomp` : |

### e_cal_util_component_is_instance ()

    gboolean    e_cal_util_component_is_instance
                                                (icalcomponent *icalcomp);

`icalcomp` : |
Returns : |

### e_cal_util_component_has_alarms ()

    gboolean    e_cal_util_component_has_alarms (icalcomponent *icalcomp);

`icalcomp` : |
Returns : |

### e_cal_util_component_has_organizer ()

    gboolean    e_cal_util_component_has_organizer
                                                (icalcomponent *icalcomp);

`icalcomp` : |
Returns : |

### e_cal_util_component_has_recurrences ()

    gboolean    e_cal_util_component_has_recurrences
                                                (icalcomponent *icalcomp);

`icalcomp` : |
Returns : |

### e_cal_util_component_has_rdates ()

    gboolean    e_cal_util_component_has_rdates (icalcomponent *icalcomp);

`icalcomp` : |
Returns : |

### e_cal_util_component_has_rrules ()

    gboolean    e_cal_util_component_has_rrules (icalcomponent *icalcomp);

`icalcomp` : |
Returns : |

### e_cal_util_event_dates_match ()

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

`icalcomp1` : |
`icalcomp2` : |
Returns : |

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

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