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 gchar *string);
icalcomponent *     e_cal_util_parse_ics_file           (const gchar *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);
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);
const gchar *       e_cal_util_priority_to_string       (gint priority);
gint                e_cal_util_priority_from_string     (const gchar *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_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
icalcomponent *     e_cal_util_construct_instance       (icalcomponent *icalcomp,
                                                         struct icaltimetype rid);
void                e_cal_util_remove_instances         (icalcomponent *icalcomp,
                                                         struct icaltimetype rid,
                                                         CalObjModType mod);
gchar *             e_cal_util_get_system_timezone_location
                                                        (void);
icaltimezone *      e_cal_util_get_system_timezone      (void);

Description

Details

CalObjInstance

typedef struct {
	gchar *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 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.

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.

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.

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

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.

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

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

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.

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_CREATE_MESSAGES

#define CAL_STATIC_CAPABILITY_CREATE_MESSAGES             "create-messages"

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

e_cal_util_get_system_timezone_location ()

gchar *             e_cal_util_get_system_timezone_location
                                                        (void);

Returns :

 system timezone location string, NULL on an error. Returned pointer should be freed with g_free().

e_cal_util_get_system_timezone ()

icaltimezone *      e_cal_util_get_system_timezone      (void);

Returns :

 icaltimezone object of the system timezone. NULL on an error. Returned pointer is part of the built-in timezones, thus do not free it.