Class

EDataBookBookMetaBackend

since: 3.26

Description [src]

abstract class EDataBook.BookMetaBackend : EDataBook.BookBackendSync
{
  /* No available fields */
}

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

Available since: 3.26

Hierarchy

hierarchy this EBookMetaBackend ancestor_0 EBookBackendSync ancestor_0--this ancestor_1 EBookBackend ancestor_1--ancestor_0 ancestor_2 EBackend ancestor_2--ancestor_1 ancestor_3 GObject ancestor_3--ancestor_2

Instance methods

e_book_meta_backend_connect_sync

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.

since: 3.26

e_book_meta_backend_disconnect_sync

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.

since: 3.26

e_book_meta_backend_dup_sync_tag

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

since: 3.28

e_book_meta_backend_empty_cache_sync

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

since: 3.26

e_book_meta_backend_ensure_connected_sync

Ensures that the meta_backend is connected to its destination.

since: 3.26

e_book_meta_backend_get_capabilities
No description available.

since: 3.26

e_book_meta_backend_get_changes_sync

Gathers the changes since the last check which had been done on the remote side.

since: 3.26

e_book_meta_backend_get_connected_writable

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

since: 3.26

e_book_meta_backend_get_ever_connected
No description available.

since: 3.26

e_book_meta_backend_get_ssl_error_details

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.

since: 3.28

e_book_meta_backend_inline_local_photos_sync

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().

since: 3.26

e_book_meta_backend_list_existing_sync

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().

since: 3.26

e_book_meta_backend_load_contact_sync

Loads a contact from the remote side.

since: 3.26

e_book_meta_backend_process_changes_sync

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.

since: 3.26

e_book_meta_backend_ref_cache
No description available.

since: 3.26

e_book_meta_backend_refresh_sync

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

since: 3.26

e_book_meta_backend_remove_contact_sync

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.

since: 3.26

e_book_meta_backend_requires_reconnect

Determines, whether current source content requires reconnect of the backend.

since: 3.26

e_book_meta_backend_save_contact_sync

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.

since: 3.26

e_book_meta_backend_schedule_refresh

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

since: 3.26

e_book_meta_backend_search_sync

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().

since: 3.26

e_book_meta_backend_search_uids_sync

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().

since: 3.26

e_book_meta_backend_set_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.

since: 3.26

e_book_meta_backend_set_connected_writable

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.

since: 3.26

e_book_meta_backend_set_ever_connected

Sets whether the meta_backend ever made a successful connection to its destination.

since: 3.26

e_book_meta_backend_set_sync_tag

Sets the sync_tag for the meta_backend.

since: 3.50

e_book_meta_backend_split_changes_sync

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.

since: 3.26

e_book_meta_backend_store_inline_photos_sync

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().

since: 3.26

Methods inherited from EBookBackendSync (9)
e_book_backend_sync_contains_email

Checks whether contains an email_address. When the email_address contains multiple addresses, then returns TRUE when at least one address exists in the address book.

since: 3.44

e_book_backend_sync_create_contacts

Creates one or more new contacts from vcards, and deposits an EContact instance for each newly-created contact in out_contacts.

since: 3.34

e_book_backend_sync_get_contact

Obtains an EContact for uid.

since: 3.34

e_book_backend_sync_get_contact_list

Obtains a set of EContact instances which satisfy the criteria specified in query, and deposits them in out_contacts.

since: 3.34

e_book_backend_sync_get_contact_list_uids

Obtains a set of ID strings for contacts which satisfy the criteria specified in query, and deposits them in out_uids.

since: 3.34

e_book_backend_sync_modify_contacts

Modifies one or more contacts according to vcards.

since: 3.34

e_book_backend_sync_open

Opens” the backend. Opening a backend is something of an outdated concept, but the operation is hanging around for a little while longer. This usually involves some custom initialization logic, and testing of remote authentication if applicable.

since: 3.34

e_book_backend_sync_refresh

Initiates a refresh for backend, if the backend supports refreshing. The actual refresh operation completes on its own time. This function merely initiates the operation.

since: 3.34

e_book_backend_sync_remove_contacts

Removes one or more contacts according to uids.

since: 3.34

Methods inherited from EBookBackend (70)

Please see EBookBackend for a full list of methods.

Methods inherited from EBackend (21)
e_backend_credentials_required

Asynchronously calls the e_backend_credentials_required_sync() on the backend, to inform clients that credentials are required.

e_backend_credentials_required_finish

Finishes the operation started with e_backend_credentials_required().

e_backend_credentials_required_sync

Synchronously lets the clients know that the backned requires credentials to be properly opened. It’s a proxy function for e_source_invoke_credentials_required_sync(), where can be found more information about actual parameters meaning.

e_backend_ensure_online_state_updated

Makes sure that the “online” property is updated, that is, if there is any destination reachability test pending, it’ll be done immediately and the only state will be updated as well.

e_backend_ensure_source_status_connected

Makes sure that the associated ESource::connection-status is connected. This is useful in cases when the backend can connect to the destination without invoking EBackendClass.authenticate_sync(), possibly through e_backend_schedule_authenticate().

e_backend_get_destination_address

Provides destination server host name and port to which the backend connects. This is used to determine required connection point for e_backend_is_destination_reachable(). The host is a newly allocated string, which will be freed with g_free(). When backend sets both host and port, then it should return TRUE, indicating it’s a remote backend. Default implementation returns FALSE, which is treated like the backend is local, no checking for server reachability is possible.

e_backend_get_network_monitor

Returns a GNetworkMonitor used to check whether the backend can access the remote server. The instance is owned by the backend.

e_backend_get_online

Returns the online state of backend: TRUE if backend is online, FALSE if offline.

e_backend_get_source

Returns the ESource to which backend is paired.

e_backend_get_user_prompter

Gets an instance of EUserPrompter, associated with this backend.

e_backend_is_destination_reachable

Checks whether the backend‘s destination server, as returned by e_backend_get_destination_address(), is reachable. If the e_backend_get_destination_address() returns FALSE, this function returns TRUE, meaning the destination is always reachable. This uses GNetworkMonitor‘s g_network_monitor_can_reach() for reachability tests.

e_backend_prepare_shutdown

Let’s the backend know that it’ll be shut down shortly, no client connects to it anymore. The backend can free any resources which reference it, for example the opened views.

e_backend_ref_connectable

Returns the socket endpoint for the network service to which backend is a client, or NULL if backend does not use network sockets.

e_backend_ref_main_context

Returns the GMainContext on which event sources for backend are to be attached.

e_backend_schedule_authenticate

Schedules a new authenticate session, cancelling any previously run. This is usually done automatically, when an ‘authenticate’ signal is received for the associated ESource. With NULL credentials an attempt without it is run.

e_backend_schedule_credentials_required

Asynchronously invokes e_backend_credentials_required(), but installs its own callback which only prints a runtime warning on the console when the call fails. The who_calls is a prefix of the console message. This is useful when the caller just wants to start the operation without having actual place where to show the operation result.

e_backend_set_connectable

Sets the socket endpoint for the network service to which backend is a client. This can be NULL if backend does not use network sockets.

e_backend_set_online

Sets the online state of backend: TRUE if backend is online, FALSE if offline.

e_backend_trust_prompt

Initiates a user trust prompt with given parameters.

e_backend_trust_prompt_finish

Finishes the operation started with e_backend_trust_prompt(). If an error occurred, the function will set error and return E_TRUST_PROMPT_RESPONSE_UNKNOWN.

e_backend_trust_prompt_sync

Asks a user a trust prompt with given parameters, and returns what user responded. This blocks until the response is delivered.

Methods inherited from GObject (43)

Please see GObject for a full list of methods.

Properties

EDataBook.BookMetaBackend:cache

The EBookCache being used for this meta backend.

Properties inherited from EBookBackend (4)
EDataBook.BookBackend:cache-dir

The backend’s cache directory.

EDataBook.BookBackend:proxy-resolver

The proxy resolver for this backend.

EDataBook.BookBackend:registry

Data source registry.

EDataBook.BookBackend:writable

Whether the backend will accept changes.

Properties inherited from EBackend (5)
EBackend.Backend:connectable

Socket endpoint of a network service.

EBackend.Backend:main-context

The main loop context on which to attach event sources.

EBackend.Backend:online

Whether the backend is online.

EBackend.Backend:source

The data source being acted upon.

EBackend.Backend:user-prompter

User prompter instance.

Signals

EDataBook.BookMetaBackend::source-changed

This signal is emitted whenever the underlying backend ESource changes. Unlike the ESources ‘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.

since: 3.26

Signals inherited from EBookBackend (2)
EBookBackend::closed

Emitted when a client destroys its EBookClient for backend.

since: 3.10

EBookBackend::shutdown

Emitted when the last client destroys its EBookClient for backend. This signals the backend to begin final cleanup tasks such as synchronizing data to permanent storage.

since: 3.10

Signals inherited from GObject (1)
GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

Class structure

struct EDataBookBookMetaBackendClass {
  gboolean (* connect_sync) (
    EBookMetaBackend* meta_backend,
    const ENamedParameters* credentials,
    ESourceAuthenticationResult* out_auth_result,
    gchar** out_certificate_pem,
    GTlsCertificateFlags* out_certificate_errors,
    GCancellable* cancellable,
    GError** error
  );
  gboolean (* disconnect_sync) (
    EBookMetaBackend* meta_backend,
    GCancellable* cancellable,
    GError** error
  );
  gboolean (* 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
  );
  gboolean (* list_existing_sync) (
    EBookMetaBackend* meta_backend,
    gchar** out_new_sync_tag,
    GSList** out_existing_objects,
    GCancellable* cancellable,
    GError** error
  );
  gboolean (* load_contact_sync) (
    EBookMetaBackend* meta_backend,
    const gchar* uid,
    const gchar* extra,
    EContact** out_contact,
    gchar** out_extra,
    GCancellable* cancellable,
    GError** error
  );
  gboolean (* 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
  );
  gboolean (* remove_contact_sync) (
    EBookMetaBackend* meta_backend,
    EConflictResolution conflict_resolution,
    const gchar* uid,
    const gchar* extra,
    const gchar* object,
    guint32 opflags,
    GCancellable* cancellable,
    GError** error
  );
  gboolean (* search_sync) (
    EBookMetaBackend* meta_backend,
    const gchar* expr,
    gboolean meta_contact,
    GSList** out_contacts,
    GCancellable* cancellable,
    GError** error
  );
  gboolean (* search_uids_sync) (
    EBookMetaBackend* meta_backend,
    const gchar* expr,
    GSList** out_uids,
    GCancellable* cancellable,
    GError** error
  );
  gboolean (* requires_reconnect) (
    EBookMetaBackend* meta_backend
  );
  void (* source_changed) (
    EBookMetaBackend* meta_backend
  );
  gboolean (* get_ssl_error_details) (
    EBookMetaBackend* meta_backend,
    gchar** out_certificate_pem,
    GTlsCertificateFlags* out_certificate_errors
  );
  
}

Class structure for the EBookMetaBackend class.

Class members
connect_sync: gboolean (* connect_sync) ( EBookMetaBackend* meta_backend, const ENamedParameters* credentials, ESourceAuthenticationResult* out_auth_result, gchar** out_certificate_pem, GTlsCertificateFlags* out_certificate_errors, GCancellable* cancellable, GError** error )

No description available.

disconnect_sync: gboolean (* disconnect_sync) ( EBookMetaBackend* meta_backend, GCancellable* cancellable, GError** error )

No description available.

get_changes_sync: gboolean (* 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 )

No description available.

list_existing_sync: gboolean (* list_existing_sync) ( EBookMetaBackend* meta_backend, gchar** out_new_sync_tag, GSList** out_existing_objects, GCancellable* cancellable, GError** error )

No description available.

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

No description available.

save_contact_sync: gboolean (* 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 )

No description available.

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

No description available.

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

No description available.

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

No description available.

requires_reconnect: gboolean (* requires_reconnect) ( EBookMetaBackend* meta_backend )

No description available.

source_changed: void (* source_changed) ( EBookMetaBackend* meta_backend )

No description available.

get_ssl_error_details: gboolean (* get_ssl_error_details) ( EBookMetaBackend* meta_backend, gchar** out_certificate_pem, GTlsCertificateFlags* out_certificate_errors )

No description available.

Virtual methods

EDataBook.BookMetaBackendClass.connect_sync

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.

since: 3.26

EDataBook.BookMetaBackendClass.disconnect_sync

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.

since: 3.26

EDataBook.BookMetaBackendClass.get_changes_sync

Gathers the changes since the last check which had been done on the remote side.

since: 3.26

EDataBook.BookMetaBackendClass.get_ssl_error_details

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.

since: 3.28

EDataBook.BookMetaBackendClass.list_existing_sync

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().

since: 3.26

EDataBook.BookMetaBackendClass.load_contact_sync

Loads a contact from the remote side.

since: 3.26

EDataBook.BookMetaBackendClass.remove_contact_sync

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.

since: 3.26

EDataBook.BookMetaBackendClass.requires_reconnect

Determines, whether current source content requires reconnect of the backend.

since: 3.26

EDataBook.BookMetaBackendClass.save_contact_sync

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.

since: 3.26

EDataBook.BookMetaBackendClass.search_sync

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().

since: 3.26

EDataBook.BookMetaBackendClass.search_uids_sync

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().

since: 3.26