Top | ![]() |
![]() |
![]() |
![]() |
ECalCacheECalCache — An ECache descendant for calendars |
GBoxed ├── ECalCacheOfflineChange ╰── ECalCacheSearchData GObject ╰── ECache ╰── ECalCache
The ECalCache is an API for storing and looking up calendar components in an ECache.
The API is thread safe, in the similar way as the ECache is.
Any operations which can take a lot of time to complete (depending on the size of your calendar) can be cancelled using a GCancellable.
ECalCacheOfflineChange * e_cal_cache_offline_change_new (const gchar *uid
,const gchar *rid
,const gchar *revision
,const gchar *object
,EOfflineState state
);
Creates a new ECalCacheOfflineChange with the offline state
information for the given uid
.
uid |
a unique component identifier |
|
rid |
a Recurrence-ID of the component. |
[nullable] |
revision |
a revision of the component. |
[nullable] |
object |
component itself. |
[nullable] |
state |
A new ECalCacheOfflineChange. Free it with
e_cal_cache_offline_change_free()
when no longer needed.
[transfer full]
Since: 3.26
ECalCacheOfflineChange *
e_cal_cache_offline_change_copy (const ECalCacheOfflineChange *change
);
Copy of the given change
. Free it with
e_cal_cache_offline_change_free()
when no longer needed.
If the change
is NULL
, then returns NULL
as well.
[transfer full]
Since: 3.26
void
e_cal_cache_offline_change_free (gpointer change
);
Frees the change
structure, previously allocated with e_cal_cache_offline_change_new()
or e_cal_cache_offline_change_copy()
.
Since: 3.26
ECalCacheSearchData * e_cal_cache_search_data_new (const gchar *uid
,const gchar *rid
,const gchar *object
,const gchar *extra
);
Creates a new ECalCacheSearchData prefilled with the given values.
A new ECalCacheSearchData. Free it with
e_cal_cache_search_data_free()
when no longer needed.
[transfer full]
Since: 3.26
ECalCacheSearchData *
e_cal_cache_search_data_copy (const ECalCacheSearchData *data
);
Copy of the given data
. Free it with
e_cal_cache_search_data_free()
when no longer needed.
If the data
is NULL
, then returns NULL
as well.
[transfer full]
Since: 3.26
void
e_cal_cache_search_data_free (gpointer ptr
);
Frees the ptr
structure, previously allocated with e_cal_cache_search_data_new()
or e_cal_cache_search_data_copy()
.
Since: 3.26
gboolean (*ECalCacheSearchFunc) (ECalCache *cal_cache
,const gchar *uid
,const gchar *rid
,const gchar *revision
,const gchar *object
,const gchar *extra
,guint32 custom_flags
,EOfflineState offline_state
,gpointer user_data
);
A callback called for each object row when using
e_cal_cache_search_with_callback()
function.
cal_cache |
an ECalCache |
|
uid |
a unique object identifier |
|
rid |
an optional Recurrence-ID of the object. |
[nullable] |
revision |
the object revision |
|
object |
the object itself |
|
extra |
extra data stored with the object |
|
custom_flags |
object's custom flags |
|
offline_state |
object's offline state, one of EOfflineState |
|
user_data |
user data, as used in |
Since: 3.26
ECalCache * e_cal_cache_new (const gchar *filename
,GCancellable *cancellable
,GError **error
);
Creates a new ECalCache.
filename |
file name to load or create the new cache |
|
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gchar * e_cal_cache_dup_component_revision (ECalCache *cal_cache
,ICalComponent *icomp
);
Returns the icomp
revision, used to detect changes.
The returned string should be freed with g_free()
, when
no longer needed.
Since: 3.26
gboolean e_cal_cache_contains (ECalCache *cal_cache
,const gchar *uid
,const gchar *rid
,ECacheDeletedFlag deleted_flag
);
Checkes whether the cal_cache
contains an object with
the given uid
and rid
. The rid
can be an empty string
or NULL
to search for the master object, otherwise the check
is done for a detached instance, not for a recurrence instance.
cal_cache |
an ECalCache |
|
uid |
component UID |
|
rid |
optional component Recurrence-ID or |
[nullable] |
deleted_flag |
one of ECacheDeletedFlag enum |
Since: 3.26
gboolean e_cal_cache_put_component (ECalCache *cal_cache
,ECalComponent *component
,const gchar *extra
,guint32 custom_flags
,ECacheOfflineFlag offline_flag
,GCancellable *cancellable
,GError **error
);
Adds a component
into the cal_cache
. Any existing with the same UID
and RID is replaced.
cal_cache |
an ECalCache |
|
component |
an ECalComponent to put into the |
|
extra |
an extra data to store in association with the |
[nullable] |
custom_flags |
custom flags for the |
|
offline_flag |
one of ECacheOfflineFlag, whether putting this component in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_put_components (ECalCache *cal_cache
,const GSList *components
,const GSList *extras
,const GSList *custom_flags
,ECacheOfflineFlag offline_flag
,GCancellable *cancellable
,GError **error
);
Adds a list of components
into the cal_cache
. Any existing with the same UID
and RID are replaced.
If extras
is not NULL
, its length should be the same as the length
of the components
. Similarly the non-NULL custom_flags
length
should be the same as the length of the components
.
cal_cache |
an ECalCache |
|
components |
a GSList of ECalComponent to put into the |
[element-type ECalComponent] |
extras |
optional extra data to store in association with the |
[nullable][element-type utf8] |
custom_flags |
optional custom flags to use for the |
[nullable][element-type guint32] |
offline_flag |
one of ECacheOfflineFlag, whether putting these components in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_remove_component (ECalCache *cal_cache
,const gchar *uid
,const gchar *rid
,guint32 custom_flags
,ECacheOfflineFlag offline_flag
,GCancellable *cancellable
,GError **error
);
Removes a component identified by uid
and rid
from the cal_cache
.
When the rid
is NULL
, or an empty string, then removes the master
object only, without any detached instance.
cal_cache |
an ECalCache |
|
uid |
a UID of the component to remove |
|
rid |
an optional Recurrence-ID to remove. |
[nullable] |
custom_flags |
custom flags for the component, not interpreted by the |
|
offline_flag |
one of ECacheOfflineFlag, whether removing this component in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_remove_components (ECalCache *cal_cache
,const GSList *ids
,const GSList *custom_flags
,ECacheOfflineFlag offline_flag
,GCancellable *cancellable
,GError **error
);
Removes components identified by uid
and rid
from the cal_cache
in the ids
list. When the rid
is NULL
, or an empty string, then
removes the master object only, without any detached instance.
The custom_flags
is used, if not NULL
, only if the offline_flag
is E_CACHE_IS_OFFLINE
. Otherwise it's ignored. The length of
the custom_flags
should match the length of ids
, when not NULL
.
cal_cache |
an ECalCache |
|
ids |
a GSList of components to remove. |
[element-type ECalComponentId] |
custom_flags |
an optional GSList of custom flags for the |
[element-type guint32][nullable] |
offline_flag |
one of ECacheOfflineFlag, whether removing these comonents in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_get_component (ECalCache *cal_cache
,const gchar *uid
,const gchar *rid
,ECalComponent **out_component
,GCancellable *cancellable
,GError **error
);
Gets a component identified by uid
, and optionally by the rid
,
from the cal_cache
. The returned out_component
should be freed with
g_object_unref()
, when no longer needed.
cal_cache |
an ECalCache |
|
uid |
a UID of the component |
|
rid |
an optional Recurrence-ID. |
[nullable] |
out_component |
return location for an ECalComponent. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_get_component_as_string (ECalCache *cal_cache
,const gchar *uid
,const gchar *rid
,gchar **out_icalstring
,GCancellable *cancellable
,GError **error
);
Gets a component identified by uid
, and optionally by the rid
,
from the cal_cache
. The returned out_icalstring
should be freed with
g_free()
, when no longer needed.
cal_cache |
an ECalCache |
|
uid |
a UID of the component |
|
rid |
an optional Recurrence-ID. |
[nullable] |
out_icalstring |
return location for an iCalendar string. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_set_component_custom_flags (ECalCache *cal_cache
,const gchar *uid
,const gchar *rid
,guint32 custom_flags
,GCancellable *cancellable
,GError **error
);
Sets or replaces the custom flags associated with a component
identified by uid
and optionally rid
.
cal_cache |
an ECalCache |
|
uid |
a UID of the component |
|
rid |
an optional Recurrence-ID. |
[nullable] |
custom_flags |
the custom flags to set for the component |
|
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.34
gboolean e_cal_cache_get_component_custom_flags (ECalCache *cal_cache
,const gchar *uid
,const gchar *rid
,guint32 *out_custom_flags
,GCancellable *cancellable
,GError **error
);
Gets the custom flags previously set for uid
and rid
, either with
e_cal_cache_set_component_custom_flags()
, when adding components or
when removing components in offline.
cal_cache |
an ECalCache |
|
uid |
a UID of the component |
|
rid |
an optional Recurrence-ID. |
[nullable] |
out_custom_flags |
return location to store the custom flags. |
[out] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.34
gboolean e_cal_cache_set_component_extra (ECalCache *cal_cache
,const gchar *uid
,const gchar *rid
,const gchar *extra
,GCancellable *cancellable
,GError **error
);
Sets or replaces the extra data associated with a component
identified by uid
and optionally rid
.
cal_cache |
an ECalCache |
|
uid |
a UID of the component |
|
rid |
an optional Recurrence-ID. |
[nullable] |
extra |
extra data to set for the component. |
[nullable] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_get_component_extra (ECalCache *cal_cache
,const gchar *uid
,const gchar *rid
,gchar **out_extra
,GCancellable *cancellable
,GError **error
);
Gets the extra data previously set for uid
and rid
, either with
e_cal_cache_set_component_extra()
or when adding components.
cal_cache |
an ECalCache |
|
uid |
a UID of the component |
|
rid |
an optional Recurrence-ID. |
[nullable] |
out_extra |
return location to store the extra data. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_get_ids_with_extra (ECalCache *cal_cache
,const gchar *extra
,GSList **out_ids
,GCancellable *cancellable
,GError **error
);
Gets all the ID-s the extra
data is set for.
The out_ids
should be freed with
g_slist_free_full (ids, (GDestroyNotify) e_cal_component_id_free);
when no longer needed.
cal_cache |
an ECalCache |
|
extra |
an extra column value to search for |
|
out_ids |
return location to store the ids to. |
[out][transfer full][element-type ECalComponentId] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_get_components_by_uid (ECalCache *cal_cache
,const gchar *uid
,GSList **out_components
,GCancellable *cancellable
,GError **error
);
Gets the master object and all detached instances for a component
identified by the uid
. Free the returned GSList with
g_slist_free_full (components, g_object_unref); when
no longer needed.
cal_cache |
an ECalCache |
|
uid |
a UID of the component |
|
out_components |
return location for the components. |
[out][transfer full][element-type ECalComponent] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_get_components_by_uid_as_string (ECalCache *cal_cache
,const gchar *uid
,GSList **out_icalstrings
,GCancellable *cancellable
,GError **error
);
Gets the master object and all detached instances as string
for a component identified by the uid
. Free the returned GSList
with g_slist_free_full (icalstrings, g_free); when no longer needed.
cal_cache |
an ECalCache |
|
uid |
a UID of the component |
|
out_icalstrings |
return location for the iCal strings. |
[out][transfer full][element-type utf8] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_get_components_in_range (ECalCache *cal_cache
,time_t range_start
,time_t range_end
,GSList **out_components
,GCancellable *cancellable
,GError **error
);
Gets a list of components which occur in the given time range. It's not an error if none is found.
cal_cache |
an ECalCache |
|
range_start |
start of the range, as time_t, inclusive |
|
range_end |
end of the range, as time_t, exclusive |
|
out_components |
return location for the components. |
[out][transfer full][element-type ECalComponent] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_get_components_in_range_as_strings (ECalCache *cal_cache
,time_t range_start
,time_t range_end
,GSList **out_icalstrings
,GCancellable *cancellable
,GError **error
);
Gets a list of components, as iCal strings, which occur in the given time range.
cal_cache |
an ECalCache |
|
range_start |
start of the range, as time_t, inclusive |
|
range_end |
end of the range, as time_t, exclusive |
|
out_icalstrings |
return location for the iCal strings. |
[out][transfer full][element-type utf8] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_search (ECalCache *cal_cache
,const gchar *sexp
,GSList **out_data
,GCancellable *cancellable
,GError **error
);
Searches the cal_cache
with the given sexp
and
returns those components which satisfy the search
expression as a GSList of ECalCacheSearchData.
The out_data
should be freed with
g_slist_free_full (data, e_cal_cache_search_data_free);
when no longer needed.
cal_cache |
an ECalCache |
|
sexp |
search expression; use |
[nullable] |
out_data |
stored components, as search data, satisfied by |
[out][transfer full][element-type ECalCacheSearchData] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_search_components (ECalCache *cal_cache
,const gchar *sexp
,GSList **out_components
,GCancellable *cancellable
,GError **error
);
Searches the cal_cache
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, g_object_unref); when
no longer needed.
cal_cache |
an ECalCache |
|
sexp |
search expression; use |
[nullable] |
out_components |
stored components satisfied by |
[out][transfer full][element-type ECalComponent] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_search_ids (ECalCache *cal_cache
,const gchar *sexp
,GSList **out_ids
,GCancellable *cancellable
,GError **error
);
Searches the cal_cache
with the given sexp
and returns ECalComponentId
for those components which satisfy the search expression.
The out_ids
should be freed with
g_slist_free_full (ids, (GDestroyNotify) e_cal_component_id_free);
when no longer needed.
cal_cache |
an ECalCache |
|
sexp |
search expression; use |
[nullable] |
out_ids |
IDs of stored components satisfied by |
[out][transfer full][element-type ECalComponentId] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_search_with_callback (ECalCache *cal_cache
,const gchar *sexp
,ECalCacheSearchFunc func
,gpointer user_data
,GCancellable *cancellable
,GError **error
);
Searches the cal_cache
with the given sexp
and calls func
for each
row which satisfy the search expression.
cal_cache |
an ECalCache |
|
sexp |
search expression; use |
[nullable] |
func |
an ECalCacheSearchFunc callback to call for each row which satisfies |
[scope call] |
user_data |
user data for |
[closure func] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
EOfflineState e_cal_cache_get_offline_state (ECalCache *cal_cache
,const gchar *uid
,const gchar *rid
,GCancellable *cancellable
,GError **error
);
This is a wrapper of e_cache_get_offline_state()
, ensuring that
a correct ECache UID will be used.
cal_cache |
an ECalCache |
|
uid |
a UID of the component |
|
rid |
an optional Recurrence-ID. |
[nullable] |
cancellable |
optional GCancellable object, or |
|
error |
Current offline state EOfflineState for the given component.
It returns E_OFFLINE_STATE_UNKNOWN
when the component could not be
found or other error happened.
Since: 3.34
GSList * e_cal_cache_get_offline_changes (ECalCache *cal_cache
,GCancellable *cancellable
,GError **error
);
The same as e_cache_get_offline_changes()
, only splits the saved UID
into UID and RID and saved the data into ECalCacheOfflineChange structure.
A newly allocated list of all offline changes. Free it with g_slist_free_full (slist, e_cal_cache_offline_change_free); when no longer needed.
[transfer full][element-type ECalCacheOfflineChange]
Since: 3.26
gboolean e_cal_cache_delete_attachments (ECalCache *cal_cache
,ICalComponent *component
,GCancellable *cancellable
,GError **error
);
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 cal_cache
.
Since: 3.26
gboolean e_cal_cache_put_timezone (ECalCache *cal_cache
,const ICalTimezone *zone
,guint inc_ref_counts
,GCancellable *cancellable
,GError **error
);
Puts the zone
into the cal_cache
using its timezone ID as
an identificator. The function adds a new or replaces existing,
if any such already exists in the cal_cache
. The function does
nothing and returns TRUE
, when the passed-in zone
is libical
builtin timezone.
cal_cache |
an ECalCache |
|
zone |
an ICalTimezone to put |
|
inc_ref_counts |
how many refs to add, or 0 to have it stored forever |
|
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_get_timezone (ECalCache *cal_cache
,const gchar *tzid
,ICalTimezone **out_zone
,GCancellable *cancellable
,GError **error
);
Gets a timezone with given tzid
, which had been previously put
into the cal_cache
with e_cal_cache_put_timezone()
.
The returned ICalTimezone is owned by the cal_cache
and should
not be freed.
cal_cache |
an ECalCache |
|
tzid |
a timezone ID to get |
|
out_zone |
return location for the ICalTimezone. |
[out][transfer none] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_dup_timezone_as_string (ECalCache *cal_cache
,const gchar *tzid
,gchar **out_zone_string
,GCancellable *cancellable
,GError **error
);
Gets a timezone with given tzid
, which had been previously put
into the cal_cache
with e_cal_cache_put_timezone()
.
The returned string is an iCal string for that ICalTimezone and
should be freed with g_free()
when no longer needed.
cal_cache |
an ECalCache |
|
tzid |
a timezone ID to get |
|
out_zone_string |
return location for the ICalTimezone as iCal string. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_list_timezones (ECalCache *cal_cache
,GList **out_timezones
,GCancellable *cancellable
,GError **error
);
Gets a list of all stored timezones by the cal_cache
.
Only the returned list should be freed with g_list_free()
when no longer needed; the ICalTimezone-s are owned
by the cal_cache
.
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 cal_cache
is freed.
cal_cache |
an ECalCache |
|
out_timezones |
return location for the list of stored timezones. |
[out][transfer container][element-type ICalTimezone] |
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
gboolean e_cal_cache_remove_timezone (ECalCache *cal_cache
,const gchar *tzid
,guint dec_ref_counts
,GCancellable *cancellable
,GError **error
);
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.
cal_cache |
an ECalCache |
|
tzid |
timezone ID to remove/dereference |
|
dec_ref_counts |
reference counts to drop, 0 to remove it regardless of the current reference count |
|
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.30
gboolean e_cal_cache_remove_timezones (ECalCache *cal_cache
,GCancellable *cancellable
,GError **error
);
Removes all stored timezones from the cal_cache
.
Since: 3.26
ICalTimezone * e_cal_cache_resolve_timezone_cb (const gchar *tzid
,gpointer cal_cache
,GCancellable *cancellable
,GError **error
);
An ECalRecurResolveTimezoneCb callback, which can be used
with e_cal_recur_generate_instances_sync()
. The cal_cache
is supposed to be an ECalCache instance.
tzid |
a timezone ID |
|
cal_cache |
an ECalCache |
|
cancellable |
optional GCancellable object, or |
|
error |
Since: 3.26
typedef struct { gchar *uid; gchar *rid; gchar *revision; gchar *object; EOfflineState state; } ECalCacheOfflineChange;
Holds the information about offline change for one component.
gchar * |
UID of the component |
|
gchar * |
Recurrence-ID of the component |
|
gchar * |
stored revision of the component |
|
gchar * |
the component itself, as an iCalendar string |
|
EOfflineState |
an EOfflineState of the component |
Since: 3.26
typedef struct { gchar *uid; gchar *rid; gchar *object; gchar *extra; } ECalCacheSearchData;
This structure is used to represent components returned
by the ECalCache from various functions
such as e_cal_cache_search()
.
The extra
parameter will contain any data which was
previously passed for this component in e_cal_cache_put_component()
or set with e_cal_cache_set_component_extra()
.
These should be freed with e_cal_cache_search_data_free()
.
Since: 3.26
struct ECalCache;
Contains only private data that should be read and manipulated using the functions below.
Since: 3.26