Namespace

ECal – 2.0

Client library for Evolution Data Server calendars

Version3.53.1
AuthorsEvolution Data Server Development Team
LicenseLGPL-2.0-only
Website
Sourcehttps://gitlab.gnome.org/GNOME/evolution-data-server/

Build

C headerslibecal/libecal.h
pkg-config fileslibecal-2.0

Dependencies

GObject—2.0 The base type system library
Browse documentation
EDataServer—1.2 Utility library for Evolution Data Server
Browse documentation

Additional documentation

Classes

Client

Contains only private data that should be read and manipulated using the functions below.

since: 3.2

ClientView

Contains only private data that should be read and manipulated using the functions below.

since: 3.2

Component

ReminderWatcher

Contains only private data that should be read and manipulated using the functions below.

since: 3.30

Interfaces

TimezoneCache

since: 3.8

Structs

ClientTzlookupICalCompData

Contains data used as lookup_data of e_cal_client_tzlookup_icalcomp_cb().

since: 3.34

ComponentAlarm

Opaque structure, which represents alarm subcomponents. Use the functions below to work with it.

ComponentAlarmInstance

Opaque structure, which represents an alarm occurrence, i.e. a instance instance. Use the functions below to work with it.

ComponentAlarmRepeat

A structure holding whether and how an alarm repeats. Use the functions below to work with it.

ComponentAlarms

Opaque structure, which represents alarm trigger instances for a particular component. Use the functions below to work with it.

ComponentAlarmTrigger

Opaque structure, which represents when an alarm is supposed to be triggered. Use the functions below to work with it.

ComponentAttendee

Describes an attendee. Use the functions below to work with it.

ComponentDateTime

An opaque structure containing an ICalTime describing the date/time value and also its TZID parameter. Use the functions below to work with it.

ComponentId

An opaque structure containing UID of a component and its recurrence ID (which can be NULL). Use the functions below to work with it.

ComponentOrganizer

Describes an organizer. Use the functions below to work with it.

ComponentParameterBag

Opaque structure, which represents a bad (list) of ICalParameter objects. Use the functions below to work with it.

ComponentPeriod

Period of time, can have explicit start/end times or start/duration instead. Use the functions below to work with it.

ComponentPropertyBag

Opaque structure, which represents a bad (list) of ICalProperty objects. Use the functions below to work with it.

ComponentRange

Describes a range. Use the functions below to work with it.

ComponentText

Contains description string and an alternate representation URI for text properties. Use the functions below to work with it.

ReminderData

Contains data related to single reminder occurrence.

since: 3.30

Enumerations

ClientError

since: 3.2

ClientSourceType

Indicates the type of calendar.

since: 3.2

ComponentAlarmAction

Alarm types.

ComponentAlarmTriggerKind

ComponentClassification

CLASSIFICATION property.

ComponentPeriodKind

Way in which a period of time is specified.

ComponentRangeKind

The kind of range.

ComponentTransparency

Time transparency.

ComponentVType

Types of calendar components to be stored by a ECalComponent, as per RFC 2445. We don’t put the alarm component type here since we store alarms as separate structures inside the other “real” components.

IntervalUnits

Declares interval units.

since: 3.52

Bitfields

ClientViewFlags

Flags that control the behaviour of an ECalClientView.

since: 3.6

ObjModType

Indicates the type of modification made to a calendar.

since: 3.8

OperationFlags

Calendar operation flags, to specify behavior in certain situations. The conflict resolution mode flags cannot be combined together, where the E_CAL_OPERATION_FLAG_CONFLICT_KEEP_LOCAL is the default behavior (and it is used when no other conflict resolution flag is set). The flags can be ignored when the operation or the backend don’t support it.

since: 3.34

RecurDescribeRecurrenceFlags

Influences behaviour of e_cal_recur_describe_recurrence().

since: 3.30

ReminderWatcherDescribeFlags

Flags modifying behaviour of e_reminder_watcher_describe_data().

since: 3.30

Callbacks

ComponentParameterBagFilterFunc

A function used to filter which parameters should be added to the bag, when filling it with e_cal_component_parameter_bag_new_from_property() and e_cal_component_parameter_bag_set_from_property().

since: 3.34

ComponentPropertyBagFilterFunc

A function used to filter which properties should be added to the bag, when filling it with e_cal_component_property_bag_new_from_component() and e_cal_component_property_bag_set_from_component().

since: 3.34

RecurFormatDateTimeFunc

Format the date/time value from itt into buffer, whose size cannot exceed buffer_size letters.

since: 3.38

RecurInstanceCb

Callback used by e_cal_recur_generate_instances_sync(), called for each instance of a (recurring) component within given time range.

since: 3.34

RecurResolveTimezoneCb

Resolve timezone by its ID provided as tzid. The returned object, if not NULL, is owned by the callback implementation and should not be freed.

since: 3.34

UtilFilterPropertyFunc

Function used to determine whether the given property prop should be considered.

since: 3.52

UtilForeachCategoryFunc

Function called for each non-empty category from e_cal_util_foreach_category(). The func can assume owenrship of the inout_category content, in which case it should also set its content to NULL, to avoid free of it. The string itself, if taken, should be freed with g_free(), when no longer needed.

since: 3.48

Functions

isodate_from_time_t

Creates an ISO 8601 UTC representation from a time value.

match_tzid

Matches tzid against the system timezone definitions and returns the matching TZID, or NULL if none found.

since: 2.24

recur_describe_recurrence

Describes some simple types of recurrences in a human-readable and localized way. The flags influence the output format and what to do when the icalcomp contains more complicated recurrence, some which the function cannot describe.

since: 3.30

recur_describe_recurrence_ex

Describes some simple types of recurrences in a human-readable and localized way. The flags influence the output format and what to do when the icalcomp contains more complicated recurrence, some which the function cannot describe.

since: 3.38

recur_ensure_end_dates

This recalculates the end dates for recurrence & exception rules which use the COUNT property. If refresh is TRUE it will recalculate all enddates for rules which use COUNT. If refresh is FALSE, it will only calculate the enddate if it hasn’t already been set. It returns TRUE if the component was changed, i.e. if the component should be saved at some point. We store the enddate in the E_CAL_EVOLUTION_ENDDATE_PARAMETER parameter of the RRULE or EXRULE.

since: 2.32

recur_generate_instances_sync

Calls the given callback function for each occurrence of the event that intersects the range between the given start and end times (the end time is not included). Note that the occurrences may start before the given start time.

since: 3.20

recur_get_localized_nth

since: 3.28

recur_obtain_enddate

system_timezone_get_location

Fetches the system timezone location string.

since: 2.28

time_add_day

Adds a day onto the time, using local time. Note that if clocks go forward due to daylight savings time, there are some non-existent local times, so the hour may be changed to make it a valid time. This also means that it may not be wise to keep calling time_add_day() to step through a certain period - if the hour gets changed to make it valid time, any further calls to time_add_day() will also return this hour, which may not be what you want.

time_add_day_with_zone

Adds or subtracts a number of days to/from the given time_t value, using the given timezone. NOTE: this function is only here to make the transition to the timezone functions easier. New code should use ICalTime values and i_cal_time_adjust() to add or subtract days, hours, minutes & seconds.

time_add_month_with_zone

Adds or subtracts a number of months to/from the given time_t value, using the given timezone.

time_add_week

Adds the given number of weeks to a time value.

time_add_week_with_zone

Adds or subtracts a number of weeks to/from the given time_t value, using the given timezone. NOTE: this function is only here to make the transition to the timezone functions easier. New code should use ICalTime values and i_cal_time_adjust() to add or subtract days, hours, minutes & seconds.

time_day_begin

Returns the start of the day, according to the local time.

time_day_begin_with_zone

Returns the start of the day containing the given time_t, using the given timezone. NOTE: this function is only here to make the transition to the timezone functions easier. New code should use ICalTime values and i_cal_time_adjust() to add or subtract days, hours, minutes & seconds.

time_day_end

Returns the end of the day, according to the local time.

time_day_end_with_zone

Returns the end of the day containing the given time_t, using the given timezone. (The end of the day is the start of the next day.) NOTE: this function is only here to make the transition to the timezone functions easier. New code should use ICalTime values and i_cal_time_adjust() to add or subtract days, hours, minutes & seconds.

time_day_of_week

Returns the day of the week for the specified date, 0 (Sun) to 6 (Sat). For the days that were removed on the Gregorian reformation, it returns Thursday. Year is the normal year, e.g. 2001. Month is 0 to 11.

time_day_of_year

Returns the 1-based day number within the year of the specified date. Year is the normal year, e.g. 2001. Month is 0 to 11.

time_days_in_month

Returns the number of days in the month. Year is the normal year, e.g. 2001. Month is 0 (Jan) to 11 (Dec).

time_from_isodate

Converts an ISO 8601 UTC time string into a time_t value.

time_is_leap_year

Returns whether the specified year is a leap year. Year is the normal year, e.g. 2001.

time_leap_years_up_to

Returns the number of leap years since year 1 up to (but not including) the specified year. Year is the normal year, e.g. 2001.

time_month_begin_with_zone

Returns the start of the month containing the given time_t, using the given timezone. NOTE: this function is only here to make the transition to the timezone functions easier. New code should use ICalTime values and i_cal_time_adjust() to add or subtract days, hours, minutes & seconds.

time_to_gdate_with_zone

Converts a time_t value to a GDate structure using the specified timezone. This is analogous to g_date_set_time() but takes the timezone into account.

time_week_begin_with_zone

Returns the start of the week containing the given time_t, using the given timezone. week_start_day should use the same values as mktime(), i.e. 0 (Sun) to 6 (Sat). NOTE: this function is only here to make the transition to the timezone functions easier. New code should use ICalTime values and i_cal_time_adjust() to add or subtract days, hours, minutes & seconds.

time_year_begin_with_zone

Returns the start of the year containing the given time_t, using the given timezone. NOTE: this function is only here to make the transition to the timezone functions easier. New code should use ICalTime values and i_cal_time_adjust() to add or subtract days, hours, minutes & seconds.

util_add_timezones_from_component

Adds VTIMEZONE components to a VCALENDAR for all tzid’s in the given icalcomp.

util_clamp_vtimezone

Modifies the vtimezone to include only subcomponents influencing the passed-in time interval between from and to.

since: 3.40

util_clamp_vtimezone_by_component

Similar to e_cal_util_clamp_vtimezone(), only reads the clamp times from the component.

since: 3.40

util_component_dup_x_property

Searches for an X property named x_name within X properties of icalcomp and returns its value as a newly allocated string. Free it with g_free(), when no longer needed.

since: 3.34

util_component_find_property_for_locale

Searches properties of kind prop_kind in the icalcomp and returns one, which is usable for the locale. When locale is NULL, the current locale is assumed. If no such property for the locale exists either the one with no language parameter or the first found is returned.

since: 3.46

util_component_find_property_for_locale_filtered

Searches properties of kind prop_kind in the icalcomp, which can be filtered by the func, and returns one, which is usable for the locale. When locale is NULL, the current locale is assumed. If no such property for the locale exists either the one with no language parameter or the first found is returned.

since: 3.52

util_component_find_x_property

Searches for an X property named x_name within X properties of icalcomp and returns it. Free the non-NULL object with g_object_unref(), when no longer needed.

since: 3.34

util_component_get_recurid_as_string

since: 3.34

util_component_has_alarms

Checks whether an ICalComponent has any alarm.

util_component_has_attendee

Checks if an ICalComponent has any attendees.

util_component_has_organizer

Checks whether an ICalComponent has an organizer.

util_component_has_property

Returns, whether the icalcomp has a property of prop_kind. To check for a specific X property use e_cal_util_component_has_x_property().

since: 3.34

util_component_has_rdates

Checks if an ICalComponent has recurrence dates.

util_component_has_recurrences

Checks if an ICalComponent has recurrence dates or rules.

util_component_has_rrules

Checks if an ICalComponent has recurrence rules.

util_component_has_x_property

Returns, whether the icalcomp contains X property named x_name. To check for standard property use e_cal_util_component_has_property().

since: 3.34

util_component_is_instance

Checks whether an ICalComponent is an instance of a recurring appointment.

util_component_remove_property_by_kind

Removes all or only the first property of kind kind in icalcomp.

since: 3.30

util_component_remove_x_property

Removes the first X property named x_name in icalcomp.

since: 3.34

util_component_set_x_property

Sets a value of the first X property named x_name in icalcomp, if any such already exists, or adds a new property with this name and value. As a special case, if value is NULL, then removes the first X property named x_name from icalcomp instead.

since: 3.34

util_conflict_resolution_to_operation_flags

Encodes the EConflictResolution into the bit-or of ECalOperationFlags. The returned value can be bit-or-ed with other ECalOperationFlags values.

since: 3.34

util_construct_instance

This checks that rid indicates a valid recurrence of icalcomp, and if so, generates a copy of icalcomp containing a RECURRENCE-ID of rid.

util_copy_timezone

Copies the zone together with its inner component and returns it as a new ICalTimezone object. Free it with g_object_unref(), when no longer needed.

since: 3.34

util_diff_categories

Compares list of categories on the old_comp with the list of categories on the new_comp and fills out_added categories and out_removed categories accordingly, as if the old_comp is replaced with the new_comp. When either of the components is NULL, it’s considered as having no categories set. Rather than returning empty GHashTable, the return argument is set to NULL when there are no added/removed categories.

since: 3.48

util_email_addresses_equal

Compares two email addresses and returns whether they are equal. Each address can contain a “mailto:” prefix. The two addresses match only if they are non-NULL and non-empty. The address itself is compared case insensitively.

since: 3.50

util_foreach_category

Calls func for each category stored in the comp.

since: 3.48

util_generate_alarms_for_comp

Generates alarm instances for a calendar component. Returns the instances structure, or NULL if no alarm instances occurred in the specified time range. Free the returned structure with e_cal_component_alarms_free(), when no longer needed.

util_generate_alarms_for_list

Iterates through all the components in the comps list and generates alarm instances for them; putting them in the comp_alarms list. Free the comp_alarms with g_slist_free_full (comp_alarms, e_cal_component_alarms_free);, when no longer neeed.

util_generate_alarms_for_uid_sync

Generates alarm instances for a calendar component with UID uid, which is stored within the client. In contrast to e_cal_util_generate_alarms_for_comp(), this function handles detached instances of recurring events properly.

since: 3.48

util_get_attendee_email

Returns an attendee email, without the “mailto:” prefix, if the attendee has it set. The email can be read from an “EMAIL” parameter, if present.

since: 3.50

util_get_component_occur_times

Find out when the component starts and stops, being careful about recurrences.

since: 2.32

util_get_default_name_and_address

Returns the real name and email address of the default mail identity, if available. If no default mail identity is available, out_name and out_address are set to NULL and the function returns FALSE.

since: 3.50

util_get_organizer_email

Returns an organizer email, without the “mailto:” prefix, if the organizer has it set. The email can be read from an “EMAIL” parameter, if present.

since: 3.50

util_get_property_email

Returns an prop email, without the “mailto:” prefix, if the prop has it set. The email can be read from an “EMAIL” parameter, if present. Otherwise the prop can be only of type I_CAL_ORGANIZER_PROPERTY or I_CAL_ATTENDEE_PROPERTY.

since: 3.50

util_get_system_timezone

Fetches system timezone ICalTimezone object.

since: 2.28

util_get_system_timezone_location

Fetches system timezone localtion string.

since: 2.28

util_has_alarms_in_range

Checks whether the comp has any alarms in the given time interval.

since: 3.48

util_icaltime_to_tm

Converts an ICalTime into a GLibc’s struct tm.

since: 2.22

util_icaltime_to_tm_with_zone

Converts a time value from one timezone to another, and returns a struct tm representation of the time.

since: 2.22

util_init_recur_task_sync

Initializes properties of a recurring vtodo, like normalizing the Due date and eventually the Start date. The function does nothing when the vtodo is not recurring.

since: 3.30

util_inline_local_attachments_sync

Changes all URL attachments which point to a local file in component to inline attachments, aka adds the file content into the component. It also populates FILENAME parameter on the attachment.

since: 3.40

util_is_first_instance

Returns whether the given rid is the first instance of the recurrence defined in the comp.

since: 3.16

util_mark_task_complete_sync

Marks the vtodo as complete with eventual update of other properties. This is useful also for recurring tasks, for which it moves the vtodo into the next occurrence according to the recurrence rule.

since: 3.30

util_new_component

Creates a new ICalComponent of the specified kind. Free it with g_object_unref(), when no longer needed.

util_new_top_level

Creates a new VCALENDAR component. Free it with g_object_unref(), when no longer needed.

util_normalize_rrule_until_value

Makes sure the ttuntil value matches the value type with the DTSTART value, as required by RFC 5545 section 3.3.10. Uses tz_cb with tz_cb_data to resolve time zones when needed.

since: 3.38

util_operation_flags_to_conflict_resolution

Decodes the EConflictResolution from the bit-or of ECalOperationFlags.

since: 3.34

util_parse_ics_file

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

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

util_priority_from_string

Converts a translated priority string to an iCalendar priority value.

util_priority_to_string

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

util_property_has_parameter

Returns, whether the prop has a parameter of param_kind.

since: 3.34

util_remove_instances

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

deprecated: 3.38 

util_remove_instances_ex

Removes one or more instances from icalcomp according to rid and mod. Uses tz_cb with tz_cb_data to resolve time zones when needed.

since: 3.38

util_seconds_to_string

Converts time, in seconds, into a string representation readable by humans and localized into the current locale. This can be used to convert event duration to string or similar use cases.

since: 3.30

util_set_alarm_acknowledged

Sets the ACKNOWLEDGED property on the components alarm with UID auid to the time when (in UTC), or to the current time, when the when is 0.

since: 3.40

util_split_at_instance

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.

deprecated: 3.38 since: 3.16

util_split_at_instance_ex

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.

since: 3.38

util_strip_mailto

Strips “mailto:” prefix from the address, if present. The returned pointer is either the address or a shifted position within the address.

since: 3.50

util_tm_to_icaltime

Converts a struct tm into an ICalTime. Free the returned object with g_object_unref(), when no longer needed.

since: 2.22

Constants

BACKEND_PROPERTY_ALARM_EMAIL_ADDRESS

An email address preferred for e-mail reminders by the calendar.

BACKEND_PROPERTY_CAL_EMAIL_ADDRESS

An email address associated with the calendar.

BACKEND_PROPERTY_DEFAULT_OBJECT

A default object for the calendar. Calendars use VEVENT, memo lists VJOURNAL and task lists VTODO, which can have prefilled values by the backend.

BACKEND_PROPERTY_REVISION

The current overall revision string, this can be used as a quick check to see if data has changed at all since the last time the calendar revision was observed.

EVOLUTION_ALARM_UID_PROPERTY

Extension property for alarm components so that we can reference them by UID.

EVOLUTION_ENDDATE_PARAMETER

The X parameter name being used to store the enddate in RRULE and EXRULE properties.

LIBICAL_GLIB_UNSTABLE_API

STATIC_CAPABILITY_ALARM_DESCRIPTION

Flag indicating that the backend supports alarm description.

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

STATIC_CAPABILITY_BULK_ADDS

Flag indicating that the backend supports bulk additions.

STATIC_CAPABILITY_BULK_MODIFIES

Flag indicating that the backend supports bulk modifications.

STATIC_CAPABILITY_BULK_REMOVES

Flag indicating that the backend supports bulk removals.

STATIC_CAPABILITY_COMPONENT_COLOR

When the capability is set, the client supports storing color for individual components.

STATIC_CAPABILITY_CREATE_MESSAGES

STATIC_CAPABILITY_DELEGATE_SUPPORTED

STATIC_CAPABILITY_DELEGATE_TO_MANY

STATIC_CAPABILITY_HAS_UNACCEPTED_MEETING

STATIC_CAPABILITY_ITIP_SUPPRESS_ON_REMOVE_SUPPORTED

Set, when the backend supports E_CAL_STATIC_CAPABILITY_SAVE_SCHEDULES and it can suppress iTip message on component removal. The capability should be ignored when the E_CAL_STATIC_CAPABILITY_SAVE_SCHEDULES is not present.

STATIC_CAPABILITY_NO_ALARM_AFTER_START

Flag indicating that the backend does not support alarm after start the event.

STATIC_CAPABILITY_NO_ALARM_REPEAT

STATIC_CAPABILITY_NO_AUDIO_ALARMS

STATIC_CAPABILITY_NO_CONV_TO_ASSIGN_TASK

STATIC_CAPABILITY_NO_CONV_TO_RECUR

STATIC_CAPABILITY_NO_DISPLAY_ALARMS

STATIC_CAPABILITY_NO_EMAIL_ALARMS

STATIC_CAPABILITY_NO_GEN_OPTIONS

STATIC_CAPABILITY_NO_MEMO_START_DATE

STATIC_CAPABILITY_NO_ORGANIZER

STATIC_CAPABILITY_NO_PROCEDURE_ALARMS

STATIC_CAPABILITY_NO_TASK_ASSIGNMENT

STATIC_CAPABILITY_NO_THISANDFUTURE

STATIC_CAPABILITY_NO_THISANDPRIOR

STATIC_CAPABILITY_NO_TRANSPARENCY

STATIC_CAPABILITY_ONE_ALARM_ONLY

STATIC_CAPABILITY_ORGANIZER_MUST_ACCEPT

STATIC_CAPABILITY_ORGANIZER_MUST_ATTEND

STATIC_CAPABILITY_ORGANIZER_NOT_EMAIL_ADDRESS

STATIC_CAPABILITY_RECURRENCES_NO_MASTER

STATIC_CAPABILITY_REFRESH_SUPPORTED

STATIC_CAPABILITY_REMOVE_ALARMS

STATIC_CAPABILITY_REMOVE_ONLY_THIS

STATIC_CAPABILITY_REQ_SEND_OPTIONS

STATIC_CAPABILITY_RETRACT_SUPPORTED

Set, when the backend supports retract. That’s a way to ask for a meeting deletion with a comment, which is stored in a component as the COMMENT property.

STATIC_CAPABILITY_SAVE_SCHEDULES

STATIC_CAPABILITY_SIMPLE_MEMO

When the capability is set, the backend handles only simple memos, which means it stores only memo description. The summary can be changed by the backend, if needed.

STATIC_CAPABILITY_SIMPLE_MEMO_WITH_SUMMARY

Similar to the E_CAL_STATIC_CAPABILITY_SIMPLE_MEMO, except the backend stores the description and the summary separately.

STATIC_CAPABILITY_TASK_CAN_RECUR

When the capability is set, the client can store and provide recurring tasks, otherwise it cannot.

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

STATIC_CAPABILITY_TASK_ESTIMATED_DURATION

Set, when the backend supports ESTIMATED-DURATION property for tasks.

STATIC_CAPABILITY_TASK_HANDLE_RECUR

When the capability is set, the backend handles task recurrence completion on its own. This does not imply E_CAL_STATIC_CAPABILITY_TASK_CAN_RECUR.

STATIC_CAPABILITY_TASK_NO_ALARM

When the capability is set, the client cannot store reminders on tasks, otherwise it can.