EDataCal.CalCache¶

Subclasses:: None

Methods¶

Inherited:: EBackend.Cache (39), GObject.Object (37), ECal.TimezoneCache (3), EDataServer.Extensible (3)
Structs:: GObject.ObjectClass (5)

class	`new` (filename, cancellable)
class	`resolve_timezone_cb` (tzid, cal_cache, cancellable)
	`contains` (uid, rid, deleted_flag)
	`delete_attachments` (component, cancellable)
	`dup_component_revision` (icomp)
	`dup_timezone_as_string` (tzid, cancellable)
	`get_component` (uid, rid, cancellable)
	`get_component_as_string` (uid, rid, cancellable)
	`get_component_custom_flags` (uid, rid, cancellable)
	`get_component_extra` (uid, rid, cancellable)
	`get_components_by_uid` (uid, cancellable)
	`get_components_by_uid_as_string` (uid, cancellable)
	`get_components_in_range` (range_start, range_end, cancellable)
	`get_components_in_range_as_strings` (range_start, range_end, cancellable)
	`get_ids_with_extra` (extra, cancellable)
	`get_offline_changes` (cancellable)
	`get_offline_state` (uid, rid, cancellable)
	`get_timezone` (tzid, cancellable)
	`list_timezones` (cancellable)
	`put_component` (component, extra, custom_flags, offline_flag, cancellable)
	`put_components` (components, extras, custom_flags, offline_flag, cancellable)
	`put_timezone` (zone, inc_ref_counts, cancellable)
	`remove_component` (uid, rid, custom_flags, offline_flag, cancellable)
	`remove_components` (ids, custom_flags, offline_flag, cancellable)
	`remove_timezone` (tzid, dec_ref_counts, cancellable)
	`remove_timezones` (cancellable)
	`search` (sexp, cancellable)
	`search_components` (sexp, cancellable)
	`search_ids` (sexp, cancellable)
	`search_with_callback` (sexp, func, user_data, cancellable)
	`set_component_custom_flags` (uid, rid, custom_flags, cancellable)
	`set_component_extra` (uid, rid, extra, cancellable)

Virtual Methods¶

Inherited:: EBackend.Cache (7), GObject.Object (7), ECal.TimezoneCache (2)

do_dup_component_revision (icomp)

Properties¶

None

Signals¶

Inherited:: EBackend.Cache (3), GObject.Object (1), ECal.TimezoneCache (1)

Name	Short Description
`dup-component-revision`
`get-timezone`	A signal being called to get timezone when putting component into the cache.

Fields¶

Inherited:: EBackend.Cache (3), GObject.Object (1), ECal.TimezoneCache (1)

Name	Type	Access	Description
parent	`EBackend.Cache`	r

Class Details¶

class EDataCal.CalCache(**kwargs)¶

Bases:: EBackend.Cache, ECal.TimezoneCache, EDataServer.Extensible
Abstract:: No
Structure:: EDataCal.CalCacheClass

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

New in version 3.26.

classmethod new(filename, cancellable)¶

Parameters:

filename (str) – file name to load or create the new cache
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

A new EDataCal.CalCache or None on error

Return type:

EDataCal.CalCache or None

Creates a new EDataCal.CalCache.

New in version 3.26.

classmethod resolve_timezone_cb(tzid, cal_cache, cancellable)¶

Parameters:

tzid (str) – a timezone ID
cal_cache (object or None) – an EDataCal.CalCache
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

the resolved ICalGLib.Timezone, or None, if not found

Return type:

ICalGLib.Timezone or None

An ECal.RecurResolveTimezoneCb callback, which can be used with ECal.recur_generate_instances_sync(). The cal_cache is supposed to be an EDataCal.CalCache instance.

New in version 3.26.

contains(uid, rid, deleted_flag)¶

Parameters:

uid (str) – component UID
rid (str or None) – optional component Recurrence-ID or None
deleted_flag (EBackend.CacheDeletedFlag) – one of EBackend.CacheDeletedFlag enum

Returns:

Whether the object had been found.

Return type:

bool

Checkes whether the self contains an object with the given uid and rid. The rid can be an empty string or None to search for the master object, otherwise the check is done for a detached instance, not for a recurrence instance.

New in version 3.26.

delete_attachments(component, cancellable)¶

Parameters:

component (ICalGLib.Component) – an ICalGLib.Component
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Deletes all locally stored attachments beside the cache file from the disk. This doesn’t modify the component. It’s usually called before the component is being removed from the self.

New in version 3.26.

dup_component_revision(icomp)¶

Parameters:: icomp (ICalGLib.Component) – an ICalGLib.Component
Returns:: A newly allocated string containing revision of the icomp.
Return type:: str

Returns the icomp revision, used to detect changes. The returned string should be freed with GLib.free(), when no longer needed.

New in version 3.26.

dup_timezone_as_string(tzid, cancellable)¶

Parameters:

tzid (str) – a timezone ID to get
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_zone_string:: return location for the ICalGLib.Timezone as iCal string

Return type:

(bool, out_zone_string: str)

Gets a timezone with given tzid, which had been previously put into the self with EDataCal.CalCache.put_timezone(). The returned string is an iCal string for that ICalGLib.Timezone and should be freed with GLib.free() when no longer needed.

New in version 3.26.

get_component(uid, rid, cancellable)¶

Parameters:

uid (str) – a UID of the component
rid (str or None) – an optional Recurrence-ID
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_component:: return location for an ECal.Component

Return type:

(bool, out_component: ECal.Component)

Gets a component identified by uid, and optionally by the rid, from the self. The returned out_component should be freed with GObject.Object.unref(), when no longer needed.

New in version 3.26.

get_component_as_string(uid, rid, cancellable)¶

Parameters:

uid (str) – a UID of the component
rid (str or None) – an optional Recurrence-ID
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_icalstring:: return location for an iCalendar string

Return type:

(bool, out_icalstring: str)

Gets a component identified by uid, and optionally by the rid, from the self. The returned out_icalstring should be freed with GLib.free(), when no longer needed.

New in version 3.26.

get_component_custom_flags(uid, rid, cancellable)¶

Parameters:

uid (str) – a UID of the component
rid (str or None) – an optional Recurrence-ID
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_custom_flags:: return location to store the custom flags

Return type:

(bool, out_custom_flags: int)

Gets the custom flags previously set for uid and rid, either with EDataCal.CalCache.set_component_custom_flags(), when adding components or when removing components in offline.

New in version 3.34.

get_component_extra(uid, rid, cancellable)¶

Parameters:

uid (str) – a UID of the component
rid (str or None) – an optional Recurrence-ID
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_extra:: return location to store the extra data

Return type:

(bool, out_extra: str)

Gets the extra data previously set for uid and rid, either with EDataCal.CalCache.set_component_extra() or when adding components.

New in version 3.26.

get_components_by_uid(uid, cancellable)¶

Parameters:

uid (str) – a UID of the component
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_components:: return location for the components

Return type:

(bool, out_components: [ECal.Component])

Gets the master object and all detached instances for a component identified by the uid. Free the returned GLib.SList with g_slist_free_full (components, GObject.Object.unref); when no longer needed.

New in version 3.26.

get_components_by_uid_as_string(uid, cancellable)¶

Parameters:

uid (str) – a UID of the component
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_icalstrings:: return location for the iCal strings

Return type:

(bool, out_icalstrings: [str])

Gets the master object and all detached instances as string for a component identified by the uid. Free the returned GLib.SList with g_slist_free_full (icalstrings, GLib.free); when no longer needed.

New in version 3.26.

get_components_in_range(range_start, range_end, cancellable)¶

Parameters:

range_start (int) – start of the range, as time_t, inclusive
range_end (int) – end of the range, as time_t, exclusive
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_components:: return location for the components

Return type:

(bool, out_components: [ECal.Component])

Gets a list of components which occur in the given time range. It’s not an error if none is found.

New in version 3.26.

get_components_in_range_as_strings(range_start, range_end, cancellable)¶

Parameters:

range_start (int) – start of the range, as time_t, inclusive
range_end (int) – end of the range, as time_t, exclusive
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_icalstrings:: return location for the iCal strings

Return type:

(bool, out_icalstrings: [str])

Gets a list of components, as iCal strings, which occur in the given time range.

New in version 3.26.

get_ids_with_extra(extra, cancellable)¶

Parameters:

extra (str) – an extra column value to search for
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_ids:: return location to store the ids to

Return type:

(bool, out_ids: [ECal.ComponentId])

Gets all the ID-s the extra data is set for.

The out_ids should be freed with g_slist_free_full (ids, (GLib.DestroyNotify) e_cal_component_id_free); when no longer needed.

New in version 3.26.

get_offline_changes(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:: GLib.Error
Returns:: A newly allocated list of all offline changes. Free it with g_slist_free_full (slist, EDataCal.CalCacheOfflineChange.free); when no longer needed.
Return type:: [EDataCal.CalCacheOfflineChange]

The same as EBackend.Cache.get_offline_changes(), only splits the saved UID into UID and RID and saved the data into EDataCal.CalCacheOfflineChange structure.

New in version 3.26.

get_offline_state(uid, rid, cancellable)¶

Parameters:

uid (str) – a UID of the component
rid (str or None) – an optional Recurrence-ID
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Current offline state EBackend.OfflineState for the given component. It returns EBackend.OfflineState.UNKNOWN when the component could not be found or other error happened.

Return type:

EBackend.OfflineState

This is a wrapper of EBackend.Cache.get_offline_state(), ensuring that a correct EBackend.Cache UID will be used.

New in version 3.34.

get_timezone(tzid, cancellable)¶

Parameters:

tzid (str) – a timezone ID to get
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_zone:: return location for the ICalGLib.Timezone

Return type:

(bool, out_zone: ICalGLib.Timezone)

Gets a timezone with given tzid, which had been previously put into the self with EDataCal.CalCache.put_timezone(). The returned ICalGLib.Timezone is owned by the self and should not be freed.

New in version 3.26.

list_timezones(cancellable)¶

Parameters:

cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_timezones:: return location for the list of stored timezones

Return type:

(bool, out_timezones: [ICalGLib.Timezone])

Gets a list of all stored timezones by the self. Only the returned list should be freed with g_list_free() when no longer needed; the ICalGLib.Timezone-s are owned by the self.

Note: The list can contain timezones previously stored in the cache, but removed from it since they were loaded, because these are freed only when also the self is freed.

New in version 3.26.

put_component(component, extra, custom_flags, offline_flag, cancellable)¶

Parameters:

component (ECal.Component) – an ECal.Component to put into the self
extra (str or None) – an extra data to store in association with the component
custom_flags (int) – custom flags for the component, not interpreted by the self
offline_flag (EBackend.CacheOfflineFlag) – one of EBackend.CacheOfflineFlag, whether putting this component in offline
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Adds a component into the self. Any existing with the same UID and RID is replaced.

New in version 3.26.

put_components(components, extras, custom_flags, offline_flag, cancellable)¶

Parameters:

components ([ECal.Component]) – a GLib.SList of ECal.Component to put into the self
extras ([str] or None) – optional extra data to store in association with the components
custom_flags ([int] or None) – optional custom flags to use for the components
offline_flag (EBackend.CacheOfflineFlag) – one of EBackend.CacheOfflineFlag, whether putting these components in offline
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Adds a list of components into the self. Any existing with the same UID and RID are replaced.

If extras is not None, its length should be the same as the length of the components. Similarly the non-None custom_flags length should be the same as the length of the components.

New in version 3.26.

put_timezone(zone, inc_ref_counts, cancellable)¶

Parameters:

zone (ICalGLib.Timezone) – an ICalGLib.Timezone to put
inc_ref_counts (int) – how many refs to add, or 0 to have it stored forever
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Puts the zone into the self using its timezone ID as an identificator. The function adds a new or replaces existing, if any such already exists in the self. The function does nothing and returns True, when the passed-in zone is libical builtin timezone.

New in version 3.26.

remove_component(uid, rid, custom_flags, offline_flag, cancellable)¶

Parameters:

uid (str) – a UID of the component to remove
rid (str or None) – an optional Recurrence-ID to remove
custom_flags (int) – custom flags for the component, not interpreted by the self
offline_flag (EBackend.CacheOfflineFlag) – one of EBackend.CacheOfflineFlag, whether removing this component in offline
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Removes a component identified by uid and rid from the self. When the rid is None, or an empty string, then removes the master object only, without any detached instance.

New in version 3.26.

remove_components(ids, custom_flags, offline_flag, cancellable)¶

Parameters:

ids ([ECal.ComponentId]) – a GLib.SList of components to remove
custom_flags ([int] or None) – an optional GLib.SList of custom flags for the ids
offline_flag (EBackend.CacheOfflineFlag) – one of EBackend.CacheOfflineFlag, whether removing these comonents in offline
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Removes components identified by uid and rid from the self in the ids list. When the rid is None, or an empty string, then removes the master object only, without any detached instance. The custom_flags is used, if not None, only if the offline_flag is EBackend.CacheOfflineFlag.IS_OFFLINE. Otherwise it’s ignored. The length of the custom_flags should match the length of ids, when not None.

New in version 3.26.

remove_timezone(tzid, dec_ref_counts, cancellable)¶

Parameters:

tzid (str) – timezone ID to remove/dereference
dec_ref_counts (int) – reference counts to drop, 0 to remove it regardless of the current reference count
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Dereferences use count of the time zone with ID tzid by dec_ref_counts and removes the timezone from the cache when the reference count reaches zero. Special case is with dec_ref_counts being zero, in which case the corresponding timezone is removed regardless of the current reference count.

It’s not an error when the timezone doesn’t exist in the cache.

New in version 3.30.

remove_timezones(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:: GLib.Error
Returns:: Whether succeeded.
Return type:: bool

Removes all stored timezones from the self.

New in version 3.26.

search(sexp, cancellable)¶

Parameters:

sexp (str or None) – search expression; use None or an empty string to list all stored components
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_data:: stored components, as search data, satisfied by sexp

Return type:

(bool, out_data: [EDataCal.CalCacheSearchData])

Searches the self with the given sexp and returns those components which satisfy the search expression as a GLib.SList of EDataCal.CalCacheSearchData. The out_data should be freed with g_slist_free_full (data, EDataCal.CalCacheSearchData.free); when no longer needed.

New in version 3.26.

search_components(sexp, cancellable)¶

Parameters:

sexp (str or None) – search expression; use None or an empty string to list all stored components
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_components:: stored components satisfied by sexp

Return type:

(bool, out_components: [ECal.Component])

Searches the self with the given sexp and returns those components which satisfy the search expression. The out_components should be freed with g_slist_free_full (components, GObject.Object.unref); when no longer needed.

New in version 3.26.

search_ids(sexp, cancellable)¶

Parameters:

sexp (str or None) – search expression; use None or an empty string to list all stored components
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_ids:: IDs of stored components satisfied by sexp

Return type:

(bool, out_ids: [ECal.ComponentId])

Searches the self with the given sexp and returns ECal.ComponentId for those components which satisfy the search expression. The out_ids should be freed with g_slist_free_full (ids, (GLib.DestroyNotify) e_cal_component_id_free); when no longer needed.

New in version 3.26.

search_with_callback(sexp, func, user_data, cancellable)¶

Parameters:

sexp (str or None) – search expression; use None or an empty string to list all stored components
func (EDataCal.CalCacheSearchFunc) – an EDataCal.CalCacheSearchFunc callback to call for each row which satisfies sexp
user_data (object or None) – user data for func
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Searches the self with the given sexp and calls func for each row which satisfy the search expression.

New in version 3.26.

set_component_custom_flags(uid, rid, custom_flags, cancellable)¶

Parameters:

uid (str) – a UID of the component
rid (str or None) – an optional Recurrence-ID
custom_flags (int) – the custom flags to set for the component
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Sets or replaces the custom flags associated with a component identified by uid and optionally rid.

New in version 3.34.

set_component_extra(uid, rid, extra, cancellable)¶

Parameters:

uid (str) – a UID of the component
rid (str or None) – an optional Recurrence-ID
extra (str or None) – extra data to set for the component
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Sets or replaces the extra data associated with a component identified by uid and optionally rid.

New in version 3.26.

do_dup_component_revision(icomp) virtual¶

Parameters:: icomp (ICalGLib.Component) – an ICalGLib.Component
Returns:: A newly allocated string containing revision of the icomp.
Return type:: str

Returns the icomp revision, used to detect changes. The returned string should be freed with GLib.free(), when no longer needed.

New in version 3.26.

Signal Details¶

EDataCal.CalCache.signals.dup_component_revision(cal_cache, object)¶

Signal Name:

dup-component-revision

Flags:

RUN_LAST, ACTION

Parameters:

cal_cache (EDataCal.CalCache) – The object which received the signal
object (ICalGLib.Component) –

Return type:

str

EDataCal.CalCache.signals.get_timezone(cal_cache, tzid)¶

Signal Name:

get-timezone

Flags:

RUN_LAST, ACTION

Parameters:

cal_cache (EDataCal.CalCache) – The object which received the signal
tzid (str) – timezone ID

Returns:

an ICalGLib.Timezone

Return type:

ICalGLib.Timezone

A signal being called to get timezone when putting component into the cache. It’s used to make sure the cache contains all timezones which are needed by the component. The returned ICalGLib.Timezone will not be freed.

New in version 3.30.