Top | ![]() |
![]() |
![]() |
![]() |
ECalMetaBackendECalMetaBackend — An ECalBackend descendant for calendar backends |
GBoxed ╰── ECalMetaBackendInfo GObject ╰── EBackend ╰── ECalBackend ╰── ECalBackendSync ╰── ECalMetaBackend
The ECalMetaBackend is an abstract ECalBackend descendant which aims to implement all evolution-data-server internals for the backend itself and lefts the backend do as minimum work as possible, like loading and saving components, listing available components and so on, thus the backend implementation can focus on things like converting (possibly) remote data into iCalendar objects and back.
As the ECalMetaBackend uses an ECalCache, the offline support is provided by default.
The structure is thread safe.
ECalMetaBackendInfo * e_cal_meta_backend_info_new (const gchar *uid
,const gchar *revision
,const gchar *object
,const gchar *extra
);
Creates a new ECalMetaBackendInfo prefilled with the given values.
uid |
a component UID; cannot be |
|
revision |
the component revision; can be |
[nullable] |
object |
the component object as an iCalendar string; can be |
[nullable] |
extra |
extra backend-specific data; can be |
[nullable] |
A new ECalMetaBackendInfo. Free it with
e_cal_meta_backend_info_free()
, when no longer needed.
[transfer full]
Since: 3.26
ECalMetaBackendInfo *
e_cal_meta_backend_info_copy (const ECalMetaBackendInfo *src
);
Copy of the given src
. Free it with
e_cal_meta_backend_info_free()
when no longer needed.
If the src
is NULL
, then returns NULL
as well.
[transfer full]
Since: 3.26
void
e_cal_meta_backend_info_free (gpointer ptr
);
Frees the ptr
structure, previously allocated with e_cal_meta_backend_info_new()
or e_cal_meta_backend_info_copy()
.
Since: 3.26
const gchar *
e_cal_meta_backend_get_capabilities (ECalMetaBackend *meta_backend
);
an “capabilities” property to be used by
the descendant in conjunction to the descendant's capabilities
in the result of e_cal_backend_get_backend_property()
with
CLIENT_BACKEND_PROPERTY_CAPABILITIES.
Since: 3.26
void e_cal_meta_backend_set_ever_connected (ECalMetaBackend *meta_backend
,gboolean value
);
Sets whether the meta_backend
ever made a successful connection
to its destination.
This is used by the meta_backend
itself, during the opening phase,
when it had not been connected yet, then it does so immediately, to
eventually report settings error easily.
Since: 3.26
gboolean
e_cal_meta_backend_get_ever_connected (ECalMetaBackend *meta_backend
);
Since: 3.26
void e_cal_meta_backend_set_connected_writable (ECalMetaBackend *meta_backend
,gboolean value
);
Sets whether the meta_backend
connected to a writable destination.
This value has meaning only if e_cal_meta_backend_get_ever_connected()
is TRUE
.
This is used by the meta_backend
itself, during the opening phase,
to set the backend writable or not also in the offline mode.
Since: 3.26
gboolean
e_cal_meta_backend_get_connected_writable
(ECalMetaBackend *meta_backend
);
This value has meaning only if e_cal_meta_backend_get_ever_connected()
is TRUE
.
Since: 3.26
gchar *
e_cal_meta_backend_dup_sync_tag (ECalMetaBackend *meta_backend
);
Returns the last known synchronization tag, the same as used to
call e_cal_meta_backend_get_changes_sync()
.
Free the returned string with g_free()
, when no longer needed.
Since: 3.28
void e_cal_meta_backend_set_cache (ECalMetaBackend *meta_backend
,ECalCache *cache
);
Sets the cache
as the cache to be used by the meta_backend
.
By default, a cache.db in ECalBackend::cache-dir is created
in the constructed method. This function can be used to override
the default.
Note the meta_backend
adds its own reference to the cache
.
Since: 3.26
ECalCache *
e_cal_meta_backend_ref_cache (ECalMetaBackend *meta_backend
);
Referenced ECalCache, which is used by meta_backend
.
Unref it with g_object_unref()
when no longer needed.
[transfer full]
Since: 3.26
ICalComponent * e_cal_meta_backend_merge_instances (ECalMetaBackend *meta_backend
,const GSList *instances
,gboolean replace_tzid_with_location
);
Merges all the instances provided in instances
list into one VCALENDAR
object, which would eventually contain also all the used timezones.
The instances
list should contain the master object and eventually all
the detached instances for one component (they all have the same UID).
Any TZID property parameters can be replaced with corresponding timezone location, which will not influence the timezone itself.
meta_backend |
||
instances |
component instances to merge. |
[element-type ECalComponent] |
replace_tzid_with_location |
whether to replace TZID-s with locations |
an ICalComponent containing a VCALENDAR
component which consists of all the given instances. Free
the returned pointer with g_object_unref()
, when no longer needed.
See: e_cal_meta_backend_save_component_sync()
.
[transfer full]
Since: 3.26
gboolean e_cal_meta_backend_inline_local_attachments_sync (ECalMetaBackend *meta_backend
,ICalComponent *component
,GCancellable *cancellable
,GError **error
);
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.
This is called automatically before e_cal_meta_backend_save_component_sync()
.
The reverse operation is e_cal_meta_backend_store_inline_attachments_sync()
.
meta_backend |
||
component |
an ICalComponent to work with |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_store_inline_attachments_sync (ECalMetaBackend *meta_backend
,ICalComponent *component
,GCancellable *cancellable
,GError **error
);
Changes all inline attachments to URL attachments in component
, which
will point to a local file instead. The function expects FILENAME parameter
to be set on the attachment as the file name of it.
This is called automatically after e_cal_meta_backend_load_component_sync()
.
The reverse operation is e_cal_meta_backend_inline_local_attachments_sync()
.
meta_backend |
||
component |
an ICalComponent to work with |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_gather_timezones_sync (ECalMetaBackend *meta_backend
,ICalComponent *vcalendar
,gboolean remove_existing
,GCancellable *cancellable
,GError **error
);
Extracts all VTIMEZONE components from the vcalendar
and adds them
to the memory cache, thus they are available when needed. The function does
nothing when the vcalendar
doesn't hold a VCALENDAR component.
Set the remove_existing
argument to TRUE
to remove all cached timezones
first and then add the existing in the vcalendar
, or set it to FALSE
to preserver existing timezones and merge them with those in vcalendar
.
meta_backend |
||
vcalendar |
a VCALENDAR ICalComponent |
|
remove_existing |
whether to remove any existing first |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_empty_cache_sync (ECalMetaBackend *meta_backend
,GCancellable *cancellable
,GError **error
);
Empties the local cache by removing all known components from it and notifies about such removal any opened views. It removes also all known time zones.
meta_backend |
||
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
void
e_cal_meta_backend_schedule_refresh (ECalMetaBackend *meta_backend
);
Schedules refresh of the content of the meta_backend
. If there's any
already scheduled, then the function does nothing.
Use e_cal_meta_backend_refresh_sync()
to refresh the meta_backend
immediately.
Since: 3.26
gboolean e_cal_meta_backend_refresh_sync (ECalMetaBackend *meta_backend
,GCancellable *cancellable
,GError **error
);
Refreshes the meta_backend
immediately. To just schedule refresh
operation call e_cal_meta_backend_schedule_refresh()
.
meta_backend |
||
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_ensure_connected_sync (ECalMetaBackend *meta_backend
,GCancellable *cancellable
,GError **error
);
Ensures that the meta_backend
is connected to its destination.
meta_backend |
||
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_split_changes_sync (ECalMetaBackend *meta_backend
,GSList *objects
,GSList **out_created_objects
,GSList **out_modified_objects
,GSList **out_removed_objects
,GCancellable *cancellable
,GError **error
);
Splits objects
into created/modified/removed lists according to current local
cache content. Only the out_removed_objects
can be NULL
, others cannot.
The function modifies objects
by moving its 'data' to corresponding out
lists and sets the objects
'data' to NULL
.
Each output GSList should be freed with g_slist_free_full (objects, e_cal_meta_backend_info_free); when no longer needed.
The caller is still responsible to free objects
as well.
meta_backend |
||
objects |
a GSList of ECalMetaBackendInfo object infos to split. |
[inout][element-type ECalMetaBackendInfo] |
out_created_objects |
a GSList of ECalMetaBackendInfo object infos which had been created. |
[out][element-type ECalMetaBackendInfo][transfer full] |
out_modified_objects |
a GSList of ECalMetaBackendInfo object infos which had been modified. |
[out][element-type ECalMetaBackendInfo][transfer full] |
out_removed_objects |
a GSList of ECalMetaBackendInfo object infos which had been removed;
it can be |
[out][element-type ECalMetaBackendInfo][transfer full][nullable] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_process_changes_sync (ECalMetaBackend *meta_backend
,const GSList *created_objects
,const GSList *modified_objects
,const GSList *removed_objects
,GCancellable *cancellable
,GError **error
);
Processes given changes by updating local cache content accordingly.
The meta_backend
processes the changes like being online and particularly
requires to be online to load created and modified objects when needed.
meta_backend |
||
created_objects |
a GSList of ECalMetaBackendInfo object infos which had been created. |
[element-type ECalMetaBackendInfo][nullable] |
modified_objects |
a GSList of ECalMetaBackendInfo object infos which had been modified. |
[element-type ECalMetaBackendInfo][nullable] |
removed_objects |
a GSList of ECalMetaBackendInfo object infos which had been removed. |
[element-type ECalMetaBackendInfo][nullable] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_connect_sync (ECalMetaBackend *meta_backend
,const ENamedParameters *credentials
,ESourceAuthenticationResult *out_auth_result
,gchar **out_certificate_pem
,GTlsCertificateFlags *out_certificate_errors
,GCancellable *cancellable
,GError **error
);
This is called always before any operation which requires a connection to the remote side. It can fail with an E_CLIENT_ERROR_REPOSITORY_OFFLINE error to indicate that the remote side cannot be currently reached. Other errors are propagated to the caller/client side. This method is not called when the backend is offline.
The descendant should also call e_cal_backend_set_writable()
after successful
connect to the remote side. This value is stored for later use, when being
opened offline.
The credentials
parameter consists of the previously used credentials.
It's always NULL
with the first connection attempt. To get the credentials,
just set the out_auth_result
to E_SOURCE_AUTHENTICATION_REQUIRED
for
the first time and the function will be called again once the credentials
are available. See the documentation of ESourceAuthenticationResult for
other available results.
The out parameters are passed to e_backend_schedule_credentials_required()
and are ignored when the descendant returns TRUE
, aka they are used
only if the connection fails. The out_certificate_pem
and out_certificate_errors
should be used together and they can be left untouched if the failure reason was
not related to certificate. Use out_auth_result
E_SOURCE_AUTHENTICATION_UNKNOWN
to indicate other error than credentials
error, otherwise the error
is used
according to out_auth_result
value.
It is mandatory to implement this virtual method by the descendant.
meta_backend |
||
credentials |
an ENamedParameters with previously used credentials, or |
[nullable] |
out_auth_result |
an ESourceAuthenticationResult with an authentication result. |
[out] |
out_certificate_pem |
a PEM encoded certificate on failure, or |
[out][transfer full] |
out_certificate_errors |
a GTlsCertificateFlags on failure, or 0. |
[out] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_disconnect_sync (ECalMetaBackend *meta_backend
,GCancellable *cancellable
,GError **error
);
This is called when the backend goes into offline mode or
when the disconnect is required. The implementation should
not report any error when it is called and the meta_backend
is not connected.
It is mandatory to implement this virtual method by the descendant.
meta_backend |
||
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_get_changes_sync (ECalMetaBackend *meta_backend
,const gchar *last_sync_tag
,gboolean is_repeat
,gchar **out_new_sync_tag
,gboolean *out_repeat
,GSList **out_created_objects
,GSList **out_modified_objects
,GSList **out_removed_objects
,GCancellable *cancellable
,GError **error
);
Gathers the changes since the last check which had been done on the remote side.
The last_sync_tag
can be used as a tag of the last check. This can be NULL
,
when there was no previous call or when the descendant doesn't store any
such tags. The out_new_sync_tag
can be populated with a value to be stored
and used the next time.
The out_repeat
can be set to TRUE
when the descendant didn't finish
read of all the changes. In that case the meta_backend
calls this
function again with the out_new_sync_tag
as the last_sync_tag
, but also
notifies about the found changes immediately. The is_repeat
is set
to TRUE
as well in this case, otherwise it's FALSE
.
The descendant can populate also ECalMetaBackendInfo::object of
the out_created_objects
and out_modified_objects
, if known, in which
case this will be used instead of loading it with e_cal_meta_backend_load_component_sync()
.
It is optional to implement this virtual method by the descendant.
The default implementation calls e_cal_meta_backend_list_existing_sync()
and then compares the list with the current content of the local cache
and populates the respective lists appropriately.
Each output GSList should be freed with g_slist_free_full (objects, e_cal_meta_backend_info_free); when no longer needed.
meta_backend |
||
last_sync_tag |
optional sync tag from the last check. |
[nullable] |
is_repeat |
set to |
|
out_new_sync_tag |
new sync tag to store on success. |
[out][transfer full] |
out_repeat |
whether to repeat this call again; default is |
[out] |
out_created_objects |
a GSList of ECalMetaBackendInfo object infos which had been created since the last check. |
[out][element-type ECalMetaBackendInfo][transfer full] |
out_modified_objects |
a GSList of ECalMetaBackendInfo object infos which had been modified since the last check. |
[out][element-type ECalMetaBackendInfo][transfer full] |
out_removed_objects |
a GSList of ECalMetaBackendInfo object infos which had been removed since the last check. |
[out][element-type ECalMetaBackendInfo][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_list_existing_sync (ECalMetaBackend *meta_backend
,gchar **out_new_sync_tag
,GSList **out_existing_objects
,GCancellable *cancellable
,GError **error
);
Used to get list of all existing objects on the remote side. The descendant
can optionally provide out_new_sync_tag
, which will be stored on success, if
not NULL
. The descendant can populate also ECalMetaBackendInfo::object of
the out_existing_objects
, if known, in which case this will be used instead
of loading it with e_cal_meta_backend_load_component_sync()
.
It is mandatory to implement this virtual method by the descendant, unless
it implements its own ECalMetaBackendClass.get_changes_sync()
.
The out_existing_objects
GSList should be freed with
g_slist_free_full (objects, e_cal_meta_backend_info_free);
when no longer needed.
meta_backend |
||
out_new_sync_tag |
optional return location for a new sync tag. |
[out][transfer full] |
out_existing_objects |
a GSList of ECalMetaBackendInfo object infos which are stored on the remote side. |
[out][element-type ECalMetaBackendInfo][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_load_component_sync (ECalMetaBackend *meta_backend
,const gchar *uid
,const gchar *extra
,ICalComponent **out_component
,gchar **out_extra
,GCancellable *cancellable
,GError **error
);
Loads a component from the remote side. Any detached instances should be
returned together with the master object. The out_component
can be either
a VCALENDAR component, which would contain the master object and all of
its detached instances, eventually also used time zones, or the requested
component of type VEVENT, VJOURNAL or VTODO.
It is mandatory to implement this virtual method by the descendant.
The returned out_component
should be freed with g_object_unref()
,
when no longer needed.
The returned out_extra
should be freed with g_free()
, when no longer
needed.
meta_backend |
||
uid |
a component UID |
|
extra |
optional extra data stored with the component, or |
[nullable] |
out_component |
a loaded component, as ICalComponent. |
[out][transfer full] |
out_extra |
an extra data to store to ECalCache with this component. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_save_component_sync (ECalMetaBackend *meta_backend
,gboolean overwrite_existing
,EConflictResolution conflict_resolution
,const GSList *instances
,const gchar *extra
,guint32 opflags
,gchar **out_new_uid
,gchar **out_new_extra
,GCancellable *cancellable
,GError **error
);
Saves one component into the remote side. The instances
contain the master
object and all the detached instances of the same component (all have the same UID).
When the overwrite_existing
is TRUE
, then the descendant can overwrite an object
with the same UID on the remote side (usually used for modify). The conflict_resolution
defines what to do when the remote side had made any changes to the object since
the last update.
The descendant can use e_cal_meta_backend_merge_instances()
to merge
the instances into one VCALENDAR component, which will contain also
used time zones.
The components in instances
have already converted locally stored attachments
into inline attachments, thus it's not needed to call
e_cal_meta_backend_inline_local_attachments_sync()
by the descendant.
The out_new_uid
can be populated with a UID of the saved component as the server
assigned it to it. This UID, if set, is loaded from the remote side afterwards,
also to see whether any changes had been made to the component by the remote side.
The out_new_extra
can be populated with a new extra data to save with the component.
Left it NULL
, to keep the same value as the extra
.
The descendant can use an E_CLIENT_ERROR_OUT_OF_SYNC error to indicate that
the save failed due to made changes on the remote side, and let the meta_backend
to resolve this conflict based on the conflict_resolution
on its own.
The E_CLIENT_ERROR_OUT_OF_SYNC error should not be used when the descendant
is able to resolve the conflicts itself.
It is mandatory to implement this virtual method by the writable descendant.
meta_backend |
||
overwrite_existing |
|
|
conflict_resolution |
one of EConflictResolution, what to do on conflicts |
|
instances |
instances of the component to save. |
[element-type ECalComponent] |
extra |
extra data saved with the components in an ECalCache. |
[nullable] |
opflags |
bit-or of ECalOperationFlags |
|
out_new_uid |
return location for the UID of the saved component. |
[out][transfer full] |
out_new_extra |
return location for the extra data to store with the component. |
[out][transfer full] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_remove_component_sync (ECalMetaBackend *meta_backend
,EConflictResolution conflict_resolution
,const gchar *uid
,const gchar *extra
,const gchar *object
,guint32 opflags
,GCancellable *cancellable
,GError **error
);
Removes a component from the remote side, with all its detached instances.
The object
is not NULL
when it's removing locally deleted object
in offline mode. Being it NULL
, the descendant can obtain the object
from the ECalCache.
It is mandatory to implement this virtual method by the writable descendant.
meta_backend |
||
conflict_resolution |
an EConflictResolution to use |
|
uid |
a component UID |
|
extra |
extra data being saved with the component in the local cache, or |
[nullable] |
object |
corresponding iCalendar object, as stored in the local cache, or |
[nullable] |
opflags |
bit-or of ECalOperationFlags |
|
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean e_cal_meta_backend_search_sync (ECalMetaBackend *meta_backend
,const gchar *expr
,GSList **out_icalstrings
,GCancellable *cancellable
,GError **error
);
Searches meta_backend
with given expression expr
and returns
found components as a GSList of iCal strings out_icalstrings
.
Free the returned out_icalstrings
with g_slist_free_full (icalstrings, g_free);
when no longer needed.
When the expr
is NULL
, all objects are returned. To get
ECalComponent-s instead, call e_cal_meta_backend_search_components_sync()
.
It is optional to implement this virtual method by the descendant.
The default implementation searches meta_backend
's cache. It's also
not required to be online for searching, thus meta_backend
doesn't
ensure it.
meta_backend |
||
expr |
a search expression, or |
[nullable] |
out_icalstrings |
return location for the found components as 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_meta_backend_search_components_sync (ECalMetaBackend *meta_backend
,const gchar *expr
,GSList **out_components
,GCancellable *cancellable
,GError **error
);
Searches meta_backend
with given expression expr
and returns
found components as a GSList of ECalComponent out_components
.
Free the returned out_components
with g_slist_free_full (components, g_object_unref);
when no longer needed.
When the expr
is NULL
, all objects are returned. To get iCal
strings instead, call e_cal_meta_backend_search_sync()
.
It is optional to implement this virtual method by the descendant.
The default implementation searches meta_backend
's cache. It's also
not required to be online for searching, thus meta_backend
doesn't
ensure it.
meta_backend |
||
expr |
a search expression, or |
[nullable] |
out_components |
return location for the found ECalComponent-s. |
[out][transfer full][element-type ECalComponent] |
cancellable |
optional GCancellable object, or |
|
error |
return location for a GError, or |
Since: 3.26
gboolean
e_cal_meta_backend_requires_reconnect (ECalMetaBackend *meta_backend
);
Determines, whether current source content requires reconnect of the backend.
It is optional to implement this virtual method by the descendant. The default
implementation compares E_SOURCE_EXTENSION_AUTHENTICATION
and
E_SOURCE_EXTENSION_WEBDAV_BACKEND
, if existing in the source,
with the values after the last successful connect and returns
TRUE
when they changed. It always return TRUE
when there was
no successful connect done yet.
Since: 3.26
gboolean e_cal_meta_backend_get_ssl_error_details (ECalMetaBackend *meta_backend
,gchar **out_certificate_pem
,GTlsCertificateFlags *out_certificate_errors
);
It is optional to implement this virtual method by the descendants. It is used to receive SSL error details when any online operation returns E_CLIENT_ERROR, E_CLIENT_ERROR_TLS_NOT_AVAILABLE error.
meta_backend |
||
out_certificate_pem |
SSL certificate encoded in PEM format. |
[out] |
out_certificate_errors |
bit-or of GTlsCertificateFlags claiming the certificate errors. |
[out] |
TRUE
, when the SSL error details had been available and
the out parameters populated, FALSE
otherwise.
Since: 3.28
struct ECalMetaBackend;
Contains only private data that should be read and manipulated using the functions below.
Since: 3.26
struct ECalMetaBackendClass { };
Class structure for the ECalMetaBackend class.
Since: 3.26