Functions

isodate_from_time_t (t)

match_tzid (tzid)

recur_describe_recurrence (icalcomp, week_start_day, flags)

recur_describe_recurrence_ex (icalcomp, week_start_day, flags, datetime_fmt_func)

recur_ensure_end_dates (comp, refresh, tz_cb, tz_cb_data, cancellable)

recur_generate_instances_sync (icalcomp, interval_start, interval_end, callback, callback_user_data, get_tz_callback, get_tz_callback_user_data, default_timezone, cancellable)

recur_get_localized_nth (nth)

recur_obtain_enddate (ir, prop, zone, convert_end_date)

system_timezone_get_location ()

time_add_day (time, days)

time_add_day_with_zone (time, days, zone)

time_add_month_with_zone (time, months, zone)

time_add_week (time, weeks)

time_add_week_with_zone (time, weeks, zone)

time_day_begin (t)

time_day_begin_with_zone (time, zone)

time_day_end (t)

time_day_end_with_zone (time, zone)

time_day_of_week (day, month, year)

time_day_of_year (day, month, year)

time_days_in_month (year, month)

time_from_isodate (str)

time_is_leap_year (year)

time_leap_years_up_to (year)

time_month_begin_with_zone (time, zone)

time_to_gdate_with_zone (date, time, zone)

time_week_begin_with_zone (time, week_start_day, zone)

time_year_begin_with_zone (time, zone)

util_add_timezones_from_component (vcal_comp, icalcomp)

util_clamp_vtimezone (vtimezone, from_, to)

util_clamp_vtimezone_by_component (vtimezone, component)

util_component_dup_x_property (icalcomp, x_name)

util_component_find_property_for_locale (icalcomp, prop_kind, locale)

util_component_find_property_for_locale_filtered (icalcomp, prop_kind, locale, func, *user_data)

util_component_find_x_property (icalcomp, x_name)

util_component_get_recurid_as_string (icalcomp)

util_component_has_alarms (icalcomp)

util_component_has_attendee (icalcomp)

util_component_has_organizer (icalcomp)

util_component_has_property (icalcomp, prop_kind)

util_component_has_rdates (icalcomp)

util_component_has_recurrences (icalcomp)

util_component_has_rrules (icalcomp)

util_component_has_x_property (icalcomp, x_name)

util_component_is_instance (icalcomp)

util_component_remove_property_by_kind (icalcomp, kind, all)

util_component_remove_x_property (icalcomp, x_name)

util_component_set_x_property (icalcomp, x_name, value)

util_conflict_resolution_to_operation_flags (conflict_resolution)

util_construct_instance (icalcomp, rid)

util_copy_timezone (zone)

util_diff_categories (old_comp, new_comp)

util_email_addresses_equal (email1, email2)

util_foreach_category (comp, func, *user_data)

util_generate_alarms_for_comp (comp, start, end, omit, resolve_tzid, user_data, default_timezone)

util_generate_alarms_for_list (comps, start, end, omit, resolve_tzid, user_data, default_timezone)

util_generate_alarms_for_uid_sync (client, uid, start, end, omit, resolve_tzid, user_data, default_timezone, def_reminder_before_start_seconds, cancellable)

util_get_attendee_email (attendee)

util_get_component_occur_times (comp, tz_cb, tz_cb_data, default_timezone, kind)

util_get_default_name_and_address (registry)

util_get_organizer_email (organizer)

util_get_property_email (prop)

util_get_system_timezone ()

util_get_system_timezone_location ()

util_has_alarms_in_range (comp, start, end, omit, resolve_tzid, user_data, default_timezone)

util_icaltime_to_tm (itt)

util_icaltime_to_tm_with_zone (itt, from_zone, to_zone)

util_init_recur_task_sync (vtodo, cal_client, cancellable)

util_inline_local_attachments_sync (component, cancellable)

util_is_first_instance (comp, rid, tz_cb, *tz_cb_data)

util_mark_task_complete_sync (vtodo, completed_time, cal_client, cancellable)

util_new_component (kind)

util_new_top_level ()

util_normalize_rrule_until_value (icalcomp, ttuntil, tz_cb, *tz_cb_data)

util_operation_flags_to_conflict_resolution (flags)

util_parse_ics_file (filename)

util_parse_ics_string (string)

util_priority_from_string (string)

util_priority_to_string (priority)

util_property_has_parameter (prop, param_kind)

util_remove_instances (icalcomp, rid, mod)

util_remove_instances_ex (icalcomp, rid, mod, tz_cb, *tz_cb_data)

util_seconds_to_string (seconds)

util_set_alarm_acknowledged (component, auid, when)

util_split_at_instance (icalcomp, rid, master_dtstart)

util_split_at_instance_ex (icalcomp, rid, master_dtstart, tz_cb, *tz_cb_data)

util_strip_mailto (address)

util_tm_to_icaltime (tm, is_date)

Details

ECal.isodate_from_time_t(t)
Parameters:

t (int) – A time value.

Returns:

String with the ISO 8601 representation of the UTC time.

Return type:

str

Creates an ISO 8601 UTC representation from a time value.

ECal.match_tzid(tzid)
Parameters:

tzid (str) – a timezone ID

Returns:

The matching TZID, or None if none found or for UTC

Return type:

str or None

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

New in version 2.24.

ECal.recur_describe_recurrence(icalcomp, week_start_day, flags)
Parameters:
Returns:

a newly allocated string, which describes the recurrence of the icalcomp, or None, when the icalcomp doesn’t recur or the recurrence is too complicated to describe, also according to given flags.

Return type:

str or None

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.

The week_start_day is used for weekly recurrences, to start the list of selected days at that day.

Uses EDataServer.time_format_date_and_time() to format the date/time value in the string. Call ECal.recur_describe_recurrence_ex() with a custom formatting function.

Free the returned string with GLib.free(), when no longer needed.

New in version 3.30.

ECal.recur_describe_recurrence_ex(icalcomp, week_start_day, flags, datetime_fmt_func)
Parameters:
Returns:

a newly allocated string, which describes the recurrence of the icalcomp, or None, when the icalcomp doesn’t recur or the recurrence is too complicated to describe, also according to given flags.

Return type:

str or None

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.

The week_start_day is used for weekly recurrences, to start the list of selected days at that day.

If datetime_fmt_func is None, the EDataServer.time_format_date_and_time() is used to format data/time value.

Free the returned string with GLib.free(), when no longer needed.

New in version 3.38.

ECal.recur_ensure_end_dates(comp, refresh, tz_cb, tz_cb_data, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if the component was changed, False otherwise

Return type:

bool

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 ECal.EVOLUTION_ENDDATE_PARAMETER parameter of the RRULE or EXRULE.

New in version 2.32.

ECal.recur_generate_instances_sync(icalcomp, interval_start, interval_end, callback, callback_user_data, get_tz_callback, get_tz_callback_user_data, default_timezone, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful (when all instances had been returned), False otherwise.

Return type:

bool

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.

If the callback routine returns False the occurrence generation stops.

The start and end times are required valid times, start before end time.

The get_tz_callback is used to resolve references to timezones. It is passed a TZID and should return the ICalGLib.Timezone * corresponding to that TZID. We need to do this as we access timezones in different ways on the client & server.

The default_timezone argument is used for DTSTART or DTEND properties that are DATE values or do not have a TZID (i.e. floating times).

New in version 3.20.

ECal.recur_get_localized_nth(nth)
Parameters:

nth (int) – the nth index, counting from zero

Returns:

Localized text for the nth position, counting from zero, which means for ‘0’ it’ll return “1st”, for ‘1’ it’ll return “2nd” and so on, up to 30, when it’ll return “31st”.

Return type:

str

New in version 3.28.

ECal.recur_obtain_enddate(ir, prop, zone, convert_end_date)
Parameters:
Return type:

int

ECal.system_timezone_get_location()
Returns:

system timezone location string, or None on an error.

Return type:

str or None

Fetches the system timezone location string.

Note: Since 3.4 the returned timezone location is either None or an equivalent within known libical timezones.

The returned string should be freed with GLib.free().

New in version 2.28.

ECal.time_add_day(time, days)
Parameters:

  • time (int) – A time_t value.

  • days (int) – Number of days to add.

Returns:

a time_t value containing time plus the days added.

Return type:

int

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 ECal.time_add_day() to step through a certain period - if the hour gets changed to make it valid time, any further calls to ECal.time_add_day() will also return this hour, which may not be what you want.

ECal.time_add_day_with_zone(time, days, zone)
Parameters:

  • time (int) – A time_t value.

  • days (int) – Number of days to add.

  • zone (ICalGLib.Timezone) – Timezone to use.

Returns:

a time_t value containing time plus the days added.

Return type:

int

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 ICalGLib.Time values and ICalGLib.Time.adjust() to add or subtract days, hours, minutes & seconds.

ECal.time_add_month_with_zone(time, months, zone)
Parameters:

  • time (int) – A time_t value.

  • months (int) – Number of months to add.

  • zone (ICalGLib.Timezone) – Timezone to use.

Returns:

a time_t value containing time plus the months added.

Return type:

int

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

If the day would be off the end of the month (e.g. adding 1 month to 30th January, would lead to an invalid day, 30th February), it moves it down to the last day in the month, e.g. 28th Feb (or 29th in a leap year.)

NOTE: this function is only here to make the transition to the timezone functions easier. New code should use ICalGLib.Time values and ICalGLib.Time.adjust() to add or subtract days, hours, minutes & seconds.

ECal.time_add_week(time, weeks)
Parameters:

  • time (int) – A time_t value.

  • weeks (int) – Number of weeks to add.

Returns:

a time_t value containing time plus the weeks added.

Return type:

int

Adds the given number of weeks to a time value.

ECal.time_add_week_with_zone(time, weeks, zone)
Parameters:

  • time (int) – A time_t value.

  • weeks (int) – Number of weeks to add.

  • zone (ICalGLib.Timezone) – Timezone to use.

Returns:

a time_t value containing time plus the weeks added.

Return type:

int

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 ICalGLib.Time values and ICalGLib.Time.adjust() to add or subtract days, hours, minutes & seconds.

ECal.time_day_begin(t)
Parameters:

t (int) – A time_t value.

Returns:

the time corresponding to the beginning of the day.

Return type:

int

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

ECal.time_day_begin_with_zone(time, zone)
Parameters:
Returns:

the beginning of the day.

Return type:

int

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 ICalGLib.Time values and ICalGLib.Time.adjust() to add or subtract days, hours, minutes & seconds.

ECal.time_day_end(t)
Parameters:

t (int) – A time_t value.

Returns:

the time corresponding to the end of the day.

Return type:

int

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

ECal.time_day_end_with_zone(time, zone)
Parameters:
Returns:

the end of the day.

Return type:

int

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 ICalGLib.Time values and ICalGLib.Time.adjust() to add or subtract days, hours, minutes & seconds.

ECal.time_day_of_week(day, month, year)
Parameters:

  • day (int) – The day.

  • month (int) – The month.

  • year (int) – The year.

Returns:

the day of the week for the given date.

Return type:

int

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.

ECal.time_day_of_year(day, month, year)
Parameters:

  • day (int) – The day.

  • month (int) – The month.

  • year (int) – The year.

Returns:

the day of the year.

Return type:

int

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.

ECal.time_days_in_month(year, month)
Parameters:

  • year (int) – The year.

  • month (int) – The month.

Returns:

number of days in the given month/year.

Return type:

int

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

ECal.time_from_isodate(str)
Parameters:

str (str) – Date/time value in ISO 8601 format.

Returns:

Time_t corresponding to the specified ISO string. Note that we only allow UTC times at present.

Return type:

int

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

ECal.time_is_leap_year(year)
Parameters:

year (int) – The year.

Returns:

True if the year is leap, False if not.

Return type:

bool

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

ECal.time_leap_years_up_to(year)
Parameters:

year (int) – The year.

Returns:

number of leap years.

Return type:

int

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.

ECal.time_month_begin_with_zone(time, zone)
Parameters:
Returns:

the beginning of the month.

Return type:

int

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 ICalGLib.Time values and ICalGLib.Time.adjust() to add or subtract days, hours, minutes & seconds.

ECal.time_to_gdate_with_zone(date, time, zone)
Parameters:

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

ECal.time_week_begin_with_zone(time, week_start_day, zone)
Parameters:

  • time (int) – A time_t value.

  • week_start_day (int) – Day to use as the starting of the week.

  • zone (ICalGLib.Timezone) – Timezone to use.

Returns:

the beginning of the week.

Return type:

int

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 ICalGLib.Time values and ICalGLib.Time.adjust() to add or subtract days, hours, minutes & seconds.

ECal.time_year_begin_with_zone(time, zone)
Parameters:
Returns:

the beginning of the year.

Return type:

int

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 ICalGLib.Time values and ICalGLib.Time.adjust() to add or subtract days, hours, minutes & seconds.

ECal.util_add_timezones_from_component(vcal_comp, icalcomp)
Parameters:

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

ECal.util_clamp_vtimezone(vtimezone, from_, to)
Parameters:
Returns:

a VTIMEZONE component to modify

Return type:

vtimezone: ICalGLib.Component

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

New in version 3.40.

ECal.util_clamp_vtimezone_by_component(vtimezone, component)
Parameters:
Returns:

a VTIMEZONE component to modify

Return type:

vtimezone: ICalGLib.Component

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

New in version 3.40.

ECal.util_component_dup_x_property(icalcomp, x_name)
Parameters:
Returns:

Newly allocated value of the first x_name X property in icalcomp, or None, if not found.

Return type:

str or None

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 GLib.free(), when no longer needed.

New in version 3.34.

ECal.util_component_find_property_for_locale(icalcomp, prop_kind, locale)
Parameters:
Returns:

a property of kind prop_kind for the locale, None if no such property is set on the comp.

Return type:

ICalGLib.Property or None

Searches properties of kind prop_kind in the icalcomp and returns one, which is usable for the locale. When locale is None, 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.

Free the returned non-None ICalGLib.Property with GObject.Object.unref(), when no longer needed.

New in version 3.46.

ECal.util_component_find_property_for_locale_filtered(icalcomp, prop_kind, locale, func, *user_data)
Parameters:
Returns:

a property of kind prop_kind for the locale, None if no such property is set on the comp.

Return type:

ICalGLib.Property or None

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 None, 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.

The func is called before checking of the applicability for the locale. When the func is None, all the properties of the prop_kind are considered.

Free the returned non-None ICalGLib.Property with GObject.Object.unref(), when no longer needed.

New in version 3.52.

ECal.util_component_find_x_property(icalcomp, x_name)
Parameters:
Returns:

the first X ICalGLib.Property named x_name, or None, when none found.

Return type:

ICalGLib.Property or None

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

New in version 3.34.

ECal.util_component_get_recurid_as_string(icalcomp)
Parameters:

icalcomp (ICalGLib.Component) – an ICalGLib.Component

Returns:

a RECURRENCEID property as string, or None, when the icalcomp is not an instance. Free the returned string with GLib.free(), when no longer needed.

Return type:

str or None

New in version 3.34.

ECal.util_component_has_alarms(icalcomp)
Parameters:

icalcomp (ICalGLib.Component) – An ICalGLib.Component.

Returns:

True if it has alarms, False otherwise.

Return type:

bool

Checks whether an ICalGLib.Component has any alarm.

ECal.util_component_has_attendee(icalcomp)
Parameters:

icalcomp (ICalGLib.Component) – An ICalGLib.Component.

Returns:

True if there are attendees, False if not.

Return type:

bool

Checks if an ICalGLib.Component has any attendees.

ECal.util_component_has_organizer(icalcomp)
Parameters:

icalcomp (ICalGLib.Component) – An ICalGLib.Component.

Returns:

True if there is an organizer, False if not.

Return type:

bool

Checks whether an ICalGLib.Component has an organizer.

ECal.util_component_has_property(icalcomp, prop_kind)
Parameters:
Returns:

whether the icalcomp has a property of prop_kind

Return type:

bool

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

New in version 3.34.

ECal.util_component_has_rdates(icalcomp)
Parameters:

icalcomp (ICalGLib.Component) – An ICalGLib.Component.

Returns:

True if there are recurrence dates, False if not.

Return type:

bool

Checks if an ICalGLib.Component has recurrence dates.

ECal.util_component_has_recurrences(icalcomp)
Parameters:

icalcomp (ICalGLib.Component) – An ICalGLib.Component.

Returns:

True if there are recurrence dates/rules, False if not.

Return type:

bool

Checks if an ICalGLib.Component has recurrence dates or rules.

ECal.util_component_has_rrules(icalcomp)
Parameters:

icalcomp (ICalGLib.Component) – An ICalGLib.Component.

Returns:

True if there are recurrence rules, False if not.

Return type:

bool

Checks if an ICalGLib.Component has recurrence rules.

ECal.util_component_has_x_property(icalcomp, x_name)
Parameters:
Returns:

whether the icalcomp contains X property named x_name

Return type:

bool

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

New in version 3.34.

ECal.util_component_is_instance(icalcomp)
Parameters:

icalcomp (ICalGLib.Component) – An ICalGLib.Component.

Returns:

True if it is an instance, False if not.

Return type:

bool

Checks whether an ICalGLib.Component is an instance of a recurring appointment.

ECal.util_component_remove_property_by_kind(icalcomp, kind, all)
Parameters:
Returns:

How many properties had been removed.

Return type:

int

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

New in version 3.30.

ECal.util_component_remove_x_property(icalcomp, x_name)
Parameters:
Returns:

True, when any such had been found and removed, False otherwise.

Return type:

bool

Removes the first X property named x_name in icalcomp.

New in version 3.34.

ECal.util_component_set_x_property(icalcomp, x_name, value)
Parameters:

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 None, then removes the first X property named x_name from icalcomp instead.

New in version 3.34.

ECal.util_conflict_resolution_to_operation_flags(conflict_resolution)
Parameters:

conflict_resolution (EDataServer.ConflictResolution) – an EDataServer.ConflictResolution

Returns:

a bit-or of ECal.OperationFlags, corresponding to the conflict_resolution

Return type:

int

Encodes the EDataServer.ConflictResolution into the bit-or of ECal.OperationFlags. The returned value can be bit-or-ed with other ECal.OperationFlags values.

New in version 3.34.

ECal.util_construct_instance(icalcomp, rid)
Parameters:
Returns:

the instance as a new ICalGLib.Component, or None.

Return type:

ICalGLib.Component or None

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

Free the returned non-None component with GObject.Object.unref(), when no longer needed.

ECal.util_copy_timezone(zone)
Parameters:

zone (ICalGLib.Timezone) – an ICalGLib.Timezone

Returns:

a copy of the zone

Return type:

ICalGLib.Timezone

Copies the zone together with its inner component and returns it as a new ICalGLib.Timezone object. Free it with GObject.Object.unref(), when no longer needed.

New in version 3.34.

ECal.util_diff_categories(old_comp, new_comp)
Parameters:
Returns:

out_added:

a GLib.HashTable with added categories

out_removed:

a GLib.HashTable with removed categories

Return type:

(out_added: {str: int}, out_removed: {str: int})

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 None, it’s considered as having no categories set. Rather than returning empty GLib.HashTable, the return argument is set to None when there are no added/removed categories.

The key of the hash table is the category string, the value is an integer (1). There is used the hash table only for speed.

The returned GLib.HashTable-s should be freed with GLib.HashTable.unref(), when no longer needed.

New in version 3.48.

ECal.util_email_addresses_equal(email1, email2)
Parameters:

  • email1 (str or None) – the first email

  • email2 (str or None) – the second email

Returns:

True, when the email1 equals to email2

Return type:

bool

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-None and non-empty. The address itself is compared case insensitively.

New in version 3.50.

ECal.util_foreach_category(comp, func, *user_data)
Parameters:

Calls func for each category stored in the comp.

New in version 3.48.

ECal.util_generate_alarms_for_comp(comp, start, end, omit, resolve_tzid, user_data, default_timezone)
Parameters:
Returns:

a list of all the alarms found for the given component in the given time range.

Return type:

ECal.ComponentAlarms or None

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

See ECal.util_generate_alarms_for_uid_sync()

ECal.util_generate_alarms_for_list(comps, start, end, omit, resolve_tzid, user_data, default_timezone)
Parameters:
Returns:

the number of elements it added to the list

comp_alarms:

List to be returned

Return type:

(int, comp_alarms: [ECal.ComponentAlarms])

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.

See ECal.util_generate_alarms_for_uid_sync()

ECal.util_generate_alarms_for_uid_sync(client, uid, start, end, omit, resolve_tzid, user_data, default_timezone, def_reminder_before_start_seconds, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

a list of all the alarms found for the given component in the given time range.

Return type:

ECal.ComponentAlarms or None

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

The def_reminder_before_start_seconds, if not negative, causes addition of an alarm, which will trigger a “display” alarm these seconds before start of the event.

Returns the instances structure, or None if no alarm instances occurred in the specified time range. Free the returned structure with e_cal_component_alarms_free(), when no longer needed.

New in version 3.48.

ECal.util_get_attendee_email(attendee)
Parameters:

attendee (ECal.ComponentAttendee or None) – an ECal.ComponentAttendee

Returns:

email of the attendee, or None

Return type:

str or None

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.

New in version 3.50.

ECal.util_get_component_occur_times(comp, tz_cb, tz_cb_data, default_timezone, kind)
Parameters:
Returns:

out_start:

Location to store the start time

out_end:

Location to store the end time

Return type:

(out_start: int, out_end: int)

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

New in version 2.32.

ECal.util_get_default_name_and_address(registry)
Parameters:

registry (EDataServer.SourceRegistry) – an EDataServer.SourceRegistry

Returns:

True if out_name and/or out_address were set

out_name:

return location for the user’s real name, or None

out_address:

return location for the user’s email address, or None

Return type:

(bool, out_name: str, out_address: str)

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 None and the function returns False.

New in version 3.50.

ECal.util_get_organizer_email(organizer)
Parameters:

organizer (ECal.ComponentOrganizer or None) – an ECal.ComponentOrganizer

Returns:

email of the organizer, or None

Return type:

str or None

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.

New in version 3.50.

ECal.util_get_property_email(prop)
Parameters:

prop (ICalGLib.Property) – an ICalGLib.Property

Returns:

email of the prop, or None

Return type:

str or None

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 ICalGLib.PropertyKind.ORGANIZER_PROPERTY or ICalGLib.PropertyKind.ATTENDEE_PROPERTY.

See also: ECal.util_get_organizer_email(), ECal.util_get_attendee_email()

New in version 3.50.

ECal.util_get_system_timezone()
Returns:

The ICalGLib.Timezone object of the system timezone, or None on an error.

Return type:

ICalGLib.Timezone or None

Fetches system timezone ICalGLib.Timezone object.

The returned pointer is Camel.part of the built-in timezones and should not be freed.

New in version 2.28.

ECal.util_get_system_timezone_location()
Returns:

system timezone location string, None on an error.

Return type:

str or None

Fetches system timezone localtion string.

New in version 2.28.

ECal.util_has_alarms_in_range(comp, start, end, omit, resolve_tzid, user_data, default_timezone)
Parameters:
Returns:

True, when the #comp has any alarms in the given time interval

Return type:

bool

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

New in version 3.48.

ECal.util_icaltime_to_tm(itt)
Parameters:

itt (ICalGLib.Time) – An ICalGLib.Time

Returns:

The converted time as a struct tm. All fields will be set properly except for tm.tm_yday.

Return type:

object or None

Converts an ICalGLib.Time into a GLibc’s struct tm.

New in version 2.22.

ECal.util_icaltime_to_tm_with_zone(itt, from_zone, to_zone)
Parameters:
Returns:

The converted time as a struct tm. All fields will be set properly except for tm.tm_yday.

Return type:

object or None

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

New in version 2.22.

ECal.util_init_recur_task_sync(vtodo, cal_client, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

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.

The function doesn’t change LAST-MODIFIED neither the SEQUENCE property, it’s up to the caller to do it.

Note the cal_client, cancellable and error is used only for timezone resolution. The function doesn’t store the vtodo to the cal_client, it only updates the vtodo component.

New in version 3.30.

ECal.util_inline_local_attachments_sync(component, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

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.

New in version 3.40.

ECal.util_is_first_instance(comp, rid, tz_cb, *tz_cb_data)
Parameters:
Returns:

Whether the rid identifies the first instance of comp.

Return type:

bool

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

New in version 3.16.

ECal.util_mark_task_complete_sync(vtodo, completed_time, cal_client, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

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.

When the vtodo is marked as completed, then the existing COMPLETED date-time is preserved if exists, otherwise it’s set either to completed_time, or to the current time, when the completed_time is (time_t) -1.

The function doesn’t change LAST-MODIFIED neither the SEQUENCE property, it’s up to the caller to do it.

Note the cal_client, cancellable and error is used only for timezone resolution. The function doesn’t store the vtodo to the cal_client, it only updates the vtodo component.

New in version 3.30.

ECal.util_new_component(kind)
Parameters:

kind (ICalGLib.ComponentKind) – Kind of the component to create, as ICalGLib.ComponentKind.

Returns:

the newly created component.

Return type:

ICalGLib.Component

Creates a new ICalGLib.Component of the specified kind. Free it with GObject.Object.unref(), when no longer needed.

ECal.util_new_top_level()
Returns:

the newly created top level component.

Return type:

ICalGLib.Component

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

ECal.util_normalize_rrule_until_value(icalcomp, ttuntil, tz_cb, *tz_cb_data)
Parameters:

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.

New in version 3.38.

ECal.util_operation_flags_to_conflict_resolution(flags)
Parameters:

flags (int) – bit-or of ECal.OperationFlags

Returns:

an EDataServer.ConflictResolution as stored in the flags

Return type:

EDataServer.ConflictResolution

Decodes the EDataServer.ConflictResolution from the bit-or of ECal.OperationFlags.

New in version 3.34.

ECal.util_parse_ics_file(filename)
Parameters:

filename (str) – Name of the file to be parsed.

Returns:

a newly created ICalGLib.Component, or None, if the file doesn’t contain a valid iCalendar object.

Return type:

ICalGLib.Component or None

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

Free the returned non-None component with GObject.Object.unref(), when no longer needed.

ECal.util_parse_ics_string(string)
Parameters:

string (str) – iCalendar string to be parsed.

Returns:

a newly created ICalGLib.Component, or None, if the string isn’t a valid iCalendar string.

Return type:

ICalGLib.Component or None

Parses an iCalendar string and returns a new ICalGLib.Component 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.

Free the returned non-None component with GObject.Object.unref(), when no longer needed.

ECal.util_priority_from_string(string)
Parameters:

string (str) – A string representing the PRIORITY value.

Returns:

the priority (0-9) or -1 if the priority string is not valid.

Return type:

int

Converts a translated priority string to an iCalendar priority value.

ECal.util_priority_to_string(priority)
Parameters:

priority (int) – Priority value.

Returns:

a string representing the PRIORITY value. This value is a constant, so it should never be freed.

Return type:

str

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

ECal.util_property_has_parameter(prop, param_kind)
Parameters:
Returns:

whether the prop has a parameter of prop_kind

Return type:

bool

Returns, whether the prop has a parameter of param_kind.

New in version 3.34.

ECal.util_remove_instances(icalcomp, rid, mod)
Parameters:

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

Deprecated since version 3.38: Use ECal.util_remove_instances_ex() instead, with provided timezone resolve function.

ECal.util_remove_instances_ex(icalcomp, rid, mod, tz_cb, *tz_cb_data)
Parameters:

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.

New in version 3.38.

ECal.util_seconds_to_string(seconds)
Parameters:

seconds (int) – actual time, in seconds

Returns:

a newly allocated string with localized description of the given time in seconds.

Return type:

str

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.

Free the returned string with GLib.free(), when no longer needed.

New in version 3.30.

ECal.util_set_alarm_acknowledged(component, auid, when)
Parameters:

  • component (ECal.Component) – an ECal.Component

  • auid (str) – an alarm UID to modify

  • when (int) – a time, in UTC, when to set the acknowledged property, or 0 for the current time

Returns:

Whether succeeded.

Return type:

bool

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

New in version 3.40.

ECal.util_split_at_instance(icalcomp, rid, master_dtstart)
Parameters:
Returns:

the split icalcomp, or None.

Return type:

ICalGLib.Component or None

Splits a recurring icalcomp into two at time rid. The returned ICalGLib.Component 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.

Use ECal.util_remove_instances_ex() with ECal.ObjModType.THIS_AND_FUTURE mode on the icalcomp to remove the overlapping interval from it, if needed.

Free the returned non-None component with GObject.Object.unref(), when done with it.

New in version 3.16.

Deprecated since version 3.38: Use ECal.util_split_at_instance_ex() instead, with provided timezone resolve function.

ECal.util_split_at_instance_ex(icalcomp, rid, master_dtstart, tz_cb, *tz_cb_data)
Parameters:
Returns:

the split icalcomp, or None.

Return type:

ICalGLib.Component or None

Splits a recurring icalcomp into two at time rid. The returned ICalGLib.Component 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.

Uses tz_cb with tz_cb_data to resolve time zones when needed.

Use ECal.util_remove_instances_ex() with ECal.ObjModType.THIS_AND_FUTURE mode on the icalcomp to remove the overlapping interval from it, if needed.

Free the returned non-None component with GObject.Object.unref(), when done with it.

New in version 3.38.

ECal.util_strip_mailto(address)
Parameters:

address (str or None) – an address with or without “mailto:” prefix

Returns:

the address without the “mailto:” prefix

Return type:

str

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

New in version 3.50.

ECal.util_tm_to_icaltime(tm, is_date)
Parameters:

  • tm (object or None) – A struct tm.

  • is_date (bool) – Whether the given time is a date only or not.

Returns:

The converted time as an ICalGLib.Time.

Return type:

ICalGLib.Time

Converts a struct tm into an ICalGLib.Time. Free the returned object with GObject.Object.unref(), when no longer needed.

New in version 2.22.