EBookMetaBackend

EBookMetaBackend — An EBookBackend descendant for book backends

Functions

EBookMetaBackendInfo * e_book_meta_backend_info_new ()
EBookMetaBackendInfo * e_book_meta_backend_info_copy ()
void e_book_meta_backend_info_free ()
const gchar * e_book_meta_backend_get_capabilities ()
void e_book_meta_backend_set_ever_connected ()
gboolean e_book_meta_backend_get_ever_connected ()
void e_book_meta_backend_set_connected_writable ()
gboolean e_book_meta_backend_get_connected_writable ()
gchar * e_book_meta_backend_dup_sync_tag ()
void e_book_meta_backend_set_cache ()
EBookCache * e_book_meta_backend_ref_cache ()
gboolean e_book_meta_backend_inline_local_photos_sync ()
gboolean e_book_meta_backend_store_inline_photos_sync ()
gboolean e_book_meta_backend_empty_cache_sync ()
void e_book_meta_backend_schedule_refresh ()
gboolean e_book_meta_backend_refresh_sync ()
gboolean e_book_meta_backend_ensure_connected_sync ()
gboolean e_book_meta_backend_split_changes_sync ()
gboolean e_book_meta_backend_process_changes_sync ()
gboolean e_book_meta_backend_connect_sync ()
gboolean e_book_meta_backend_disconnect_sync ()
gboolean e_book_meta_backend_get_changes_sync ()
gboolean e_book_meta_backend_list_existing_sync ()
gboolean e_book_meta_backend_load_contact_sync ()
gboolean e_book_meta_backend_save_contact_sync ()
gboolean e_book_meta_backend_remove_contact_sync ()
gboolean e_book_meta_backend_search_sync ()
gboolean e_book_meta_backend_search_uids_sync ()
gboolean e_book_meta_backend_requires_reconnect ()
gboolean e_book_meta_backend_get_ssl_error_details ()

Properties

EBookCache * cache Read / Write

Signals

void refresh-completed Run Last
void source-changed Run Last

Types and Values

Object Hierarchy

    GBoxed
    ╰── EBookMetaBackendInfo
    GObject
    ╰── EBackend
        ╰── EBookBackend
            ╰── EBookBackendSync
                ╰── EBookMetaBackend

Includes

#include <libedata-book/libedata-book.h>

Description

The EBookMetaBackend is an abstract EBookBackend 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 contacts, listing available contacts and so on, thus the backend implementation can focus on things like converting (possibly) remote data into vCard objects and back.

As the EBookMetaBackend uses an EBookCache, the offline support is provided by default.

The structure is thread safe.

Functions

e_book_meta_backend_info_new ()

EBookMetaBackendInfo *
e_book_meta_backend_info_new (const gchar *uid,
                              const gchar *revision,
                              const gchar *object,
                              const gchar *extra);

Creates a new EBookMetaBackendInfo prefilled with the given values.

Parameters

uid

a contact UID; cannot be NULL

 

revision

the contact revision; can be NULL.

[nullable]

object

the contact object as a vCard string; can be NULL.

[nullable]

extra

extra backend-specific data; can be NULL.

[nullable]

Returns

A new EBookMetaBackendInfo. Free it with e_book_meta_backend_info_free(), when no longer needed.

[transfer full]

Since: 3.26


e_book_meta_backend_info_copy ()

EBookMetaBackendInfo *
e_book_meta_backend_info_copy (const EBookMetaBackendInfo *src);

Parameters

src

a source EBookMetaBackendInfo to copy, or NULL.

[nullable]

Returns

Copy of the given src . Free it with e_book_meta_backend_info_free() when no longer needed. If the src is NULL, then returns NULL as well.

[transfer full]

Since: 3.26


e_book_meta_backend_info_free ()

void
e_book_meta_backend_info_free (gpointer ptr);

Frees the ptr structure, previously allocated with e_book_meta_backend_info_new() or e_book_meta_backend_info_copy().

Parameters

ptr

an EBookMetaBackendInfo.

[nullable]

Since: 3.26


e_book_meta_backend_get_capabilities ()

const gchar *
e_book_meta_backend_get_capabilities (EBookMetaBackend *meta_backend);

Parameters

meta_backend

an EBookMetaBackend

 

Returns

an “capabilities” property to be used by the descendant in conjunction to the descendant's capabilities in the result of e_book_backend_get_backend_property() with CLIENT_BACKEND_PROPERTY_CAPABILITIES.

Since: 3.26


e_book_meta_backend_set_ever_connected ()

void
e_book_meta_backend_set_ever_connected
                               (EBookMetaBackend *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.

Parameters

meta_backend

an EBookMetaBackend

 

value

value to set

 

Since: 3.26


e_book_meta_backend_get_ever_connected ()

gboolean
e_book_meta_backend_get_ever_connected
                               (EBookMetaBackend *meta_backend);

Parameters

meta_backend

an EBookMetaBackend

 

Returns

Whether the meta_backend ever made a successful connection to its destination.

Since: 3.26


e_book_meta_backend_set_connected_writable ()

void
e_book_meta_backend_set_connected_writable
                               (EBookMetaBackend *meta_backend,
                                gboolean value);

Sets whether the meta_backend connected to a writable destination. This value has meaning only if e_book_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.

Parameters

meta_backend

an EBookMetaBackend

 

value

value to set

 

Since: 3.26


e_book_meta_backend_get_connected_writable ()

gboolean
e_book_meta_backend_get_connected_writable
                               (EBookMetaBackend *meta_backend);

This value has meaning only if e_book_meta_backend_get_ever_connected() is TRUE.

Parameters

meta_backend

an EBookMetaBackend

 

Returns

Whether the meta_backend connected to a writable destination.

Since: 3.26


e_book_meta_backend_dup_sync_tag ()

gchar *
e_book_meta_backend_dup_sync_tag (EBookMetaBackend *meta_backend);

Returns the last known synchronization tag, the same as used to call e_book_meta_backend_get_changes_sync().

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

Parameters

meta_backend

an EBookMetaBackend

 

Returns

The last known synchronization tag, or NULL, when none is stored.

[transfer full][nullable]

Since: 3.28


e_book_meta_backend_set_cache ()

void
e_book_meta_backend_set_cache (EBookMetaBackend *meta_backend,
                               EBookCache *cache);

Sets the cache as the cache to be used by the meta_backend . By default, a cache.db in EBookBackend::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 .

Parameters

meta_backend

an EBookMetaBackend

 

cache

an EBookCache to use

 

Since: 3.26


e_book_meta_backend_ref_cache ()

EBookCache *
e_book_meta_backend_ref_cache (EBookMetaBackend *meta_backend);

Parameters

meta_backend

an EBookMetaBackend

 

Returns

Referenced EBookCache, which is used by meta_backend . Unref it with g_object_unref(), when no longer needed.

[transfer full]

Since: 3.26


e_book_meta_backend_inline_local_photos_sync ()

gboolean
e_book_meta_backend_inline_local_photos_sync
                               (EBookMetaBackend *meta_backend,
                                EContact *contact,
                                GCancellable *cancellable,
                                GError **error);

Changes all URL photos and logos which point to a local file in contact to inline type, aka adds the file content into the contact . This is called automatically before e_book_meta_backend_save_contact_sync().

The reverse operation is e_book_meta_backend_store_inline_photos_sync().

Parameters

meta_backend

an EBookMetaBackend

 

contact

an EContact to work with

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_store_inline_photos_sync ()

gboolean
e_book_meta_backend_store_inline_photos_sync
                               (EBookMetaBackend *meta_backend,
                                EContact *contact,
                                GCancellable *cancellable,
                                GError **error);

Changes all inline photos and logos to URL type in contact , which will point to a local file instead, beside the cache file. This is called automatically after e_book_meta_backend_load_contact_sync().

The reverse operation is e_book_meta_backend_inline_local_photos_sync().

Parameters

meta_backend

an EBookMetaBackend

 

contact

an EContact to work with

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_empty_cache_sync ()

gboolean
e_book_meta_backend_empty_cache_sync (EBookMetaBackend *meta_backend,
                                      GCancellable *cancellable,
                                      GError **error);

Empties the local cache by removing all known contacts from it and notifies about such removal any opened views.

Parameters

meta_backend

an EBookMetaBackend

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_schedule_refresh ()

void
e_book_meta_backend_schedule_refresh (EBookMetaBackend *meta_backend);

Schedules refresh of the content of the meta_backend . If there's any already scheduled, then the function does nothing.

Use e_book_meta_backend_refresh_sync() to refresh the meta_backend immediately.

Parameters

meta_backend

an EBookMetaBackend

 

Since: 3.26


e_book_meta_backend_refresh_sync ()

gboolean
e_book_meta_backend_refresh_sync (EBookMetaBackend *meta_backend,
                                  GCancellable *cancellable,
                                  GError **error);

Refreshes the meta_backend immediately. To just schedule refresh operation call e_book_meta_backend_schedule_refresh().

Parameters

meta_backend

an EBookMetaBackend

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_ensure_connected_sync ()

gboolean
e_book_meta_backend_ensure_connected_sync
                               (EBookMetaBackend *meta_backend,
                                GCancellable *cancellable,
                                GError **error);

Ensures that the meta_backend is connected to its destination.

Parameters

meta_backend

an EBookMetaBackend

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_split_changes_sync ()

gboolean
e_book_meta_backend_split_changes_sync
                               (EBookMetaBackend *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_book_meta_backend_info_free); when no longer needed.

The caller is still responsible to free objects as well.

Parameters

meta_backend

an EBookMetaBackend

 

objects

a GSList of EBookMetaBackendInfo object infos to split.

[inout][element-type EBookMetaBackendInfo]

out_created_objects

a GSList of EBookMetaBackendInfo object infos which had been created.

[out][element-type EBookMetaBackendInfo][transfer full]

out_modified_objects

a GSList of EBookMetaBackendInfo object infos which had been modified.

[out][element-type EBookMetaBackendInfo][transfer full]

out_removed_objects

a GSList of EBookMetaBackendInfo object infos which had been removed; it can be NULL, to not gather list of removed object infos.

[out][element-type EBookMetaBackendInfo][transfer full][nullable]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_process_changes_sync ()

gboolean
e_book_meta_backend_process_changes_sync
                               (EBookMetaBackend *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.

Parameters

meta_backend

an EBookMetaBackend

 

created_objects

a GSList of EBookMetaBackendInfo object infos which had been created.

[element-type EBookMetaBackendInfo][nullable]

modified_objects

a GSList of EBookMetaBackendInfo object infos which had been modified.

[element-type EBookMetaBackendInfo][nullable]

removed_objects

a GSList of EBookMetaBackendInfo object infos which had been removed.

[element-type EBookMetaBackendInfo][nullable]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_connect_sync ()

gboolean
e_book_meta_backend_connect_sync (EBookMetaBackend *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_book_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.

Parameters

meta_backend

an EBookMetaBackend

 

credentials

an ENamedParameters with previously used credentials, or NULL.

[nullable]

out_auth_result

an ESourceAuthenticationResult with an authentication result.

[out]

out_certificate_pem

a PEM encoded certificate on failure, or NULL.

[out][transfer full]

out_certificate_errors

a GTlsCertificateFlags on failure, or 0.

[out]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_disconnect_sync ()

gboolean
e_book_meta_backend_disconnect_sync (EBookMetaBackend *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.

Parameters

meta_backend

an EBookMetaBackend

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_get_changes_sync ()

gboolean
e_book_meta_backend_get_changes_sync (EBookMetaBackend *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 EBookMetaBackendInfo::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_book_meta_backend_load_contact_sync().

It is optional to implement this virtual method by the descendant. The default implementation calls e_book_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_book_meta_backend_info_free); when no longer needed.

Parameters

meta_backend

an EBookMetaBackend

 

last_sync_tag

optional sync tag from the last check.

[nullable]

is_repeat

set to TRUE when this is the repeated call

 

out_new_sync_tag

new sync tag to store on success.

[out][transfer full]

out_repeat

whether to repeat this call again; default is FALSE.

[out]

out_created_objects

a GSList of EBookMetaBackendInfo object infos which had been created since the last check.

[out][element-type EBookMetaBackendInfo][transfer full]

out_modified_objects

a GSList of EBookMetaBackendInfo object infos which had been modified since the last check.

[out][element-type EBookMetaBackendInfo][transfer full]

out_removed_objects

a GSList of EBookMetaBackendInfo object infos which had been removed since the last check.

[out][element-type EBookMetaBackendInfo][transfer full]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_list_existing_sync ()

gboolean
e_book_meta_backend_list_existing_sync
                               (EBookMetaBackend *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 EBookMetaBackendInfo::object of the out_existing_objects , if known, in which case this will be used instead of loading it with e_book_meta_backend_load_contact_sync().

It is mandatory to implement this virtual method by the descendant, unless it implements its own EBookMetaBackendClass.get_changes_sync().

The out_existing_objects GSList should be freed with g_slist_free_full (objects, e_book_meta_backend_info_free); when no longer needed.

Parameters

meta_backend

an EBookMetaBackend

 

out_new_sync_tag

optional return location for a new sync tag.

[out][transfer full]

out_existing_objects

a GSList of EBookMetaBackendInfo object infos which are stored on the remote side.

[out][element-type EBookMetaBackendInfo][transfer full]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_load_contact_sync ()

gboolean
e_book_meta_backend_load_contact_sync (EBookMetaBackend *meta_backend,
                                       const gchar *uid,
                                       const gchar *extra,
                                       EContact **out_contact,
                                       gchar **out_extra,
                                       GCancellable *cancellable,
                                       GError **error);

Loads a contact from the remote side.

It is mandatory to implement this virtual method by the descendant.

The returned out_contact 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.

Parameters

meta_backend

an EBookMetaBackend

 

uid

a contact UID

 

extra

optional extra data stored with the contact, or NULL.

[nullable]

out_contact

a loaded contact, as an EContact.

[out][transfer full]

out_extra

an extra data to store to EBookCache with this contact.

[out][transfer full]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_save_contact_sync ()

gboolean
e_book_meta_backend_save_contact_sync (EBookMetaBackend *meta_backend,
                                       gboolean overwrite_existing,
                                       EConflictResolution conflict_resolution,
                                       EContact *contact,
                                       const gchar *extra,
                                       guint32 opflags,
                                       gchar **out_new_uid,
                                       gchar **out_new_extra,
                                       GCancellable *cancellable,
                                       GError **error);

Saves one contact into the remote side. 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 contact has already converted locally stored photos and logos into inline variants, thus it's not needed to call e_book_meta_backend_inline_local_photos_sync() by the descendant.

The out_new_uid can be populated with a UID of the saved contact 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 contact by the remote side.

The out_new_extra can be populated with a new extra data to save with the contact. 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 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.

Parameters

meta_backend

an EBookMetaBackend

 

overwrite_existing

TRUE when can overwrite existing contacts, FALSE otherwise

 

conflict_resolution

one of EConflictResolution, what to do on conflicts

 

contact

an EContact to save

 

extra

extra data saved with the contacts in an EBookCache.

[nullable]

opflags

bit-or of EBookOperationFlags

 

out_new_uid

return location for the UID of the saved contact.

[out][transfer full]

out_new_extra

return location for the extra data to store with the contact.

[out][transfer full]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_remove_contact_sync ()

gboolean
e_book_meta_backend_remove_contact_sync
                               (EBookMetaBackend *meta_backend,
                                EConflictResolution conflict_resolution,
                                const gchar *uid,
                                const gchar *extra,
                                const gchar *object,
                                guint32 opflags,
                                GCancellable *cancellable,
                                GError **error);

Removes a contact from the remote side. 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 EBookCache.

It is mandatory to implement this virtual method by the writable descendant.

Parameters

meta_backend

an EBookMetaBackend

 

conflict_resolution

an EConflictResolution to use

 

uid

a contact UID

 

extra

extra data being saved with the contact in the local cache, or NULL.

[nullable]

object

corresponding vCard object, as stored in the local cache, or NULL.

[nullable]

opflags

bit-or of EBookOperationFlags

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_search_sync ()

gboolean
e_book_meta_backend_search_sync (EBookMetaBackend *meta_backend,
                                 const gchar *expr,
                                 gboolean meta_contact,
                                 GSList **out_contacts,
                                 GCancellable *cancellable,
                                 GError **error);

Searches meta_backend with given expression expr and returns found contacts as a GSList of EContact out_contacts . Free the returned out_contacts with g_slist_free_full (contacts, g_object_unref); when no longer needed. When the expr is NULL, all objects are returned. To get UID-s instead, call e_book_meta_backend_search_uids_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.

Parameters

meta_backend

an EBookMetaBackend

 

expr

a search expression, or NULL.

[nullable]

meta_contact

TRUE, when return EContact filled with UID and REV only, FALSE to return full contacts

 

out_contacts

return location for the found contacts as EContact.

[out][transfer full][element-type EContact]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_search_uids_sync ()

gboolean
e_book_meta_backend_search_uids_sync (EBookMetaBackend *meta_backend,
                                      const gchar *expr,
                                      GSList **out_uids,
                                      GCancellable *cancellable,
                                      GError **error);

Searches meta_backend with given expression expr and returns found contact UID-s as a GSList out_contacts . Free the returned out_uids with g_slist_free_full (uids, g_free); when no longer needed. When the expr is NULL, all UID-s are returned. To get EContact(s) instead, call e_book_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.

Parameters

meta_backend

an EBookMetaBackend

 

expr

a search expression, or NULL.

[nullable]

out_uids

return location for the found contact UID-s.

[out][transfer full][element-type utf8]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

Whether succeeded.

Since: 3.26


e_book_meta_backend_requires_reconnect ()

gboolean
e_book_meta_backend_requires_reconnect
                               (EBookMetaBackend *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.

Parameters

meta_backend

an EBookMetaBackend

 

Returns

TRUE, when reconnect is required, FALSE otherwise.

Since: 3.26


e_book_meta_backend_get_ssl_error_details ()

gboolean
e_book_meta_backend_get_ssl_error_details
                               (EBookMetaBackend *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.

Parameters

meta_backend

an EBookMetaBackend

 

out_certificate_pem

SSL certificate encoded in PEM format.

[out]

out_certificate_errors

bit-or of GTlsCertificateFlags claiming the certificate errors.

[out]

Returns

TRUE, when the SSL error details had been available and the out parameters populated, FALSE otherwise.

Since: 3.28

Types and Values

struct EBookMetaBackend

struct EBookMetaBackend;

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

Since: 3.26


struct EBookMetaBackendClass

struct EBookMetaBackendClass {
};

Class structure for the EBookMetaBackend class.

Since: 3.26

Property Details

The “cache” property

  “cache”                    EBookCache *

The EBookCache being used for this meta backend.

Flags: Read / Write

Signal Details

The “refresh-completed” signal

void
user_function (EBookMetaBackend *ebookmetabackend,
               gpointer          user_data)

Flags: Run Last


The “source-changed” signal

void
user_function (EBookMetaBackend *ebookmetabackend,
               gpointer          user_data)

This signal is emitted whenever the underlying backend ESource changes. Unlike the ESource's 'changed' signal this one is tight to the EBookMetaBackend itself and is emitted from a dedicated thread, thus it doesn't block the main thread.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 3.26