Top | ![]() |
![]() |
![]() |
![]() |
ECalCacheECalCache — An ECache descendant for calendars |
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.
uid |
a component UID; cannot be |
|
rid |
a component Recurrence-ID; can be |
[nullable] |
object |
the component as an iCal string; cannot be |
|
extra |
any extra data stored with the component, or |
[nullable] |
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
,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 |
|
offline_state |
objects 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 |
return location for a GError, or |
Since: 3.26
gchar * e_cal_cache_dup_component_revision (ECalCache *cal_cache
,icalcomponent *icalcomp
);
Returns the icalcomp
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
,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] |
offline_flag |
one of ECacheOfflineFlag, whether putting this component in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_cache_put_components (ECalCache *cal_cache
,const GSList *components
,const GSList *extras
,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
, it's 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 |
an extra data to store in association with the |
[nullable][element-type utf8] |
offline_flag |
one of ECacheOfflineFlag, whether putting these components in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_cache_remove_component (ECalCache *cal_cache
,const gchar *uid
,const gchar *rid
,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] |
offline_flag |
one of ECacheOfflineFlag, whether removing this component in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_cache_remove_components (ECalCache *cal_cache
,const GSList *ids
,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.
cal_cache |
an ECalCache |
|
ids |
a GSList of components to remove. |
[element-type ECalComponentId] |
offline_flag |
one of ECacheOfflineFlag, whether removing these comonents in offline |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
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 |
return location for a GError, or |
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 |
return location for a GError, or |
Since: 3.26
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 |
return location for a GError, or |
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 |
return location for a GError, or |
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_free_id);
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 |
return location for a GError, or |
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 |
return location for a GError, or |
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 |
return location for a GError, or |
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 |
return location for a GError, or |
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 |
return location for a GError, or |
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 |
return location for a GError, or |
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 |
return location for a GError, or |
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_free_id);
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 |
return location for a GError, or |
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 |
|
user_data |
user data for |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
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.
cal_cache |
an ECalCache |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
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
.
cal_cache |
an ECalCache |
|
component |
an icalcomponent |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_cache_put_timezone (ECalCache *cal_cache
,const icaltimezone *zone
,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
.
cal_cache |
an ECalCache |
|
zone |
an icaltimezone to put |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
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 |
return location for a GError, or |
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 |
return location for a GError, or |
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 |
return location for a GError, or |
Since: 3.26
gboolean e_cal_cache_remove_timezones (ECalCache *cal_cache
,GCancellable *cancellable
,GError **error
);
Removes all stored timezones from the cal_cache
.
cal_cache |
an ECalCache |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
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. See also
e_cal_cache_resolve_timezone_simple_cb()
.
tzid |
a timezone ID |
|
cal_cache |
an ECalCache |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
icaltimezone * e_cal_cache_resolve_timezone_simple_cb (const gchar *tzid
,gpointer cal_cache
);
An ECalRecurResolveTimezoneFn callback, which can be used
with e_cal_recur_ensure_end_dates()
and simialr functions.
The cal_cache
is supposed to be an ECalCache instance. See
also e_cal_cache_resolve_timezone_cb()
.
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.
UID of the component |
||
Recurrence-ID of the component |
||
stored revision of the component |
||
the component itself, as iCalalendar 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_add_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