Class
EDataBookBookBackend
Description [src]
class EDataBook.BookBackend : EBackend.Backend
{
/* No available fields */
}
Contains only private data that should be read and manipulated using the functions below.
Instance methods
e_book_backend_configure_direct
This method is called on backend in direct read access mode. The config argument is the same configuration string which
the same backend reported in the EDataBookDirect returned
by e_book_backend_get_direct_book().
since: 3.8
e_book_backend_contains_email
Asynchronously 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_contains_email_finish
Finishes the operation started with e_book_backend_contains_email().
since: 3.44
e_book_backend_contains_email_sync
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_create_contacts
Asynchronously creates one or more new contacts from vcards.
since: 3.10
e_book_backend_create_contacts_finish
Finishes the operation started with e_book_backend_create_contacts().
since: 3.10
e_book_backend_create_contacts_sync
Creates one or more new contacts from vcards, and deposits an EContact
instance for each newly-created contact in out_contacts.
since: 3.10
e_book_backend_create_cursor
Creates a new EDataBookCursor for the given backend if the backend
has cursor support. If the backend does not support cursors then an E_CLIENT_ERROR_NOT_SUPPORTED error will be set in error.
since: 3.12
e_book_backend_delete_cursor
Requests backend to release and destroy cursor, this
will trigger an E_CLIENT_ERROR_INVALID_ARG error if cursor
is not owned by backend.
since: 3.12
e_book_backend_dup_cache_dir
Thread-safe variation of e_book_backend_get_cache_dir().
Use this function when accessing backend from multiple threads.
since: 3.10
e_book_backend_dup_locale
Fetches a copy of the currently configured locale for the addressbook.
since: 3.12
e_book_backend_dup_view_contacts
Returns range_length contacts from 0-based index range_start
in the view identified by the view_id.
When there are asked more than e_book_backend_get_view_n_total()
contacts only those up to the total number of contacts are read.
Asking for out of range contacts results in an error, though
it can return less than range_length contacts.
since: 3.50
e_book_backend_dup_view_indices
Returns a list of EBookIndices holding indices of the contacts
in the view identified by view_id. The array is terminated by an item
with chr member being NULL.
since: 3.50
e_book_backend_dup_view_sort_fields
Returns currently used sort fields for manual query views. The returned array is NULL only if the view could not be found. The default sort is by the file-as filed in ascending order.
since: 3.50
e_book_backend_foreach_view
Calls func for each existing view (as returned by e_book_backend_list_views()). The func can return FALSE to stop early.
since: 3.34
e_book_backend_foreach_view_notify_progress
Notifies each view of the backend about progress. When only_completed_views
is TRUE, notifies only completed views.
since: 3.34
e_book_backend_get_backend_property
Obtains the value of the backend property named prop_name.
Freed the returned string with g_free() when finished with it.
since: 3.10
e_book_backend_get_contact_finish
Finishes the operation started with e_book_backend_get_contact_finish().
since: 3.10
e_book_backend_get_contact_list
Asynchronously obtains a set of EContact instances which satisfy the
criteria specified in query.
since: 3.10
e_book_backend_get_contact_list_finish
Finishes the operation started with e_book_backend_get_contact_list().
since: 3.10
e_book_backend_get_contact_list_sync
Obtains a set of EContact instances which satisfy the criteria specified in query, and deposits them in out_contacts.
since: 3.10
e_book_backend_get_contact_list_uids
Asynchronously obtains a set of ID strings for contacts which satisfy
the criteria specified in query.
since: 3.10
e_book_backend_get_contact_list_uids_finish
Finishes the operation started with e_book_backend_get_contact_list_uids_finish().
since: 3.10
e_book_backend_get_contact_list_uids_sync
Obtains a set of ID strings for contacts which satisfy the criteria
specified in query, and deposits them in out_uids.
since: 3.10
e_book_backend_get_direct_book
Tries to create an EDataBookDirect for backend if
backend supports direct read access.
since: 3.8
e_book_backend_get_registry
Returns the data source registry to which EBackend:source belongs.
since: 3.6
e_book_backend_get_view_n_total
Returns how many contacts the view identified by view_id
contains.
since: 3.50
e_book_backend_get_writable
Returns whether backend will accept changes to its data content.
since: 3.8
e_book_backend_is_opened
Checks if backend‘s storage has been opened (and
authenticated, if necessary) and the backend itself
is ready for accessing. This property is changed automatically
after the backend is successfully opened.
since: 3.2
e_book_backend_list_views
Returns a list of EDataBookView instances added with e_book_backend_add_view().
since: 3.8
e_book_backend_modify_contacts
Asynchronously modifies one or more contacts according to vcards.
since: 3.10
e_book_backend_modify_contacts_finish
Finishes the operation started with e_book_backend_modify_contacts().
since: 3.10
e_book_backend_notify_complete
Notifies all of backend‘s book views that the current set of
notifications is complete; use this after a series of
e_book_backend_notify_update() and e_book_backend_notify_remove() calls.
e_book_backend_notify_error
Notifies each backend listener about an error. This is meant to be used for cases where is no GError return possibility, to notify user about an issue.
since: 3.2
e_book_backend_notify_remove
Notifies all of backend‘s book views that the contact with UID
id has been removed.
e_book_backend_notify_update
Notifies all of backend‘s book views about the new or modified contacts contact.
e_book_backend_open
Asynchronously “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.10
e_book_backend_open_sync
“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.10
e_book_backend_ref_data_book
Returns the EDataBook for backend. The EDataBook is essentially
the glue between incoming D-Bus requests and backend‘s native API.
since: 3.10
e_book_backend_ref_proxy_resolver
Returns the GProxyResolver for backend (if applicable), as indicated
by the ESourceAuthentication:proxy-uid of backend‘s EBackend:source
or one of its ancestors.
since: 3.12
e_book_backend_ref_view_user_data
References user data previously set by e_book_backend_take_view_user_data()
for the view_id.
since: 3.50
e_book_backend_refresh
Asynchronously initiates a refresh for backend, if the backend supports
refreshing. The actual refresh operation completes on its own time. This
function, along with e_book_backend_refresh_finish(), merely initiates the operation.
since: 3.10
e_book_backend_refresh_finish
Finishes the refresh initiation started with e_book_backend_refresh().
since: 3.10
e_book_backend_refresh_sync
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.10
e_book_backend_remove_contacts
Asynchronously removes one or more contacts according to uids.
since: 3.10
e_book_backend_remove_contacts_finish
Finishes the operation started with e_book_backend_remove_contacts().
since: 3.10
e_book_backend_schedule_custom_operation
Schedules user function func to be run in a dedicated thread as
a blocking operation.
since: 3.26
e_book_backend_set_data_book
Sets the EDataBook for backend. The EDataBook is essentially the
glue between incoming D-Bus requests and backend‘s native API.
since: 3.10
e_book_backend_set_locale
Notify the addressbook backend that the current locale has changed, this is important for backends which support ordered result lists which are locale sensitive.
since: 3.12
e_book_backend_set_view_indices
Stores current indices for the view identified by the view_id and,
if such exists, notifies about it also the corresponding EDataBookView.
The array is terminated by an item with chr member being NULL.
since: 3.50
e_book_backend_set_view_n_total
Stores how many contacts the view identified by view_id
contains. It also sets the n_total to the corresponding
EDataBookView, if such exists. The function does nothing
when the view cannot be found.
since: 3.50
e_book_backend_set_view_sort_fields
Sets the sort fields for the view identified by the view_id. The fields array should be terminated by an item, which has
the field member set to E_CONTACT_FIELD_LAST.
since: 3.50
e_book_backend_set_writable
Sets whether backend will accept changes to its data content.
since: 3.8
e_book_backend_start_view
Starts running the query specified by view, emitting signals for
matching contacts.
e_book_backend_take_view_user_data
Sets the user data for the view_id. The function assumes ownership
of the user_data. The user_data can be NULL, which unsets
the current user data for the view.
since: 3.50
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.
Properties
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.BookBackend::closed
Emitted when a client destroys its EBookClient for backend.
since: 3.10
EDataBook.BookBackend::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 EDataBookBookBackendClass {
gboolean use_serial_dispatch_queue;
gchar* (* impl_get_backend_property) (
EBookBackend* backend,
const gchar* prop_name
);
void (* impl_open) (
EBookBackend* backend,
EDataBook* book,
guint32 opid,
GCancellable* cancellable
);
void (* impl_refresh) (
EBookBackend* backend,
EDataBook* book,
guint32 opid,
GCancellable* cancellable
);
void (* impl_create_contacts) (
EBookBackend* backend,
EDataBook* book,
guint32 opid,
GCancellable* cancellable,
const gchar* const* vcards,
guint32 opflags
);
void (* impl_modify_contacts) (
EBookBackend* backend,
EDataBook* book,
guint32 opid,
GCancellable* cancellable,
const gchar* const* vcards,
guint32 opflags
);
void (* impl_remove_contacts) (
EBookBackend* backend,
EDataBook* book,
guint32 opid,
GCancellable* cancellable,
const gchar* const* uids,
guint32 opflags
);
void (* impl_get_contact) (
EBookBackend* backend,
EDataBook* book,
guint32 opid,
GCancellable* cancellable,
const gchar* id
);
void (* impl_get_contact_list) (
EBookBackend* backend,
EDataBook* book,
guint32 opid,
GCancellable* cancellable,
const gchar* query
);
void (* impl_get_contact_list_uids) (
EBookBackend* backend,
EDataBook* book,
guint32 opid,
GCancellable* cancellable,
const gchar* query
);
void (* impl_start_view) (
EBookBackend* backend,
EDataBookView* view
);
void (* impl_stop_view) (
EBookBackend* backend,
EDataBookView* view
);
void (* impl_notify_update) (
EBookBackend* backend,
const EContact* contact
);
EDataBookDirect* (* impl_get_direct_book) (
EBookBackend* backend
);
void (* impl_configure_direct) (
EBookBackend* backend,
const gchar* config
);
gboolean (* impl_set_locale) (
EBookBackend* backend,
const gchar* locale,
GCancellable* cancellable,
GError** error
);
gchar* (* impl_dup_locale) (
EBookBackend* backend
);
EDataBookCursor* (* impl_create_cursor) (
EBookBackend* backend,
EContactField* sort_fields,
EBookCursorSortType* sort_types,
guint n_fields,
GError** error
);
gboolean (* impl_delete_cursor) (
EBookBackend* backend,
EDataBookCursor* cursor,
GError** error
);
void (* closed) (
EBookBackend* backend,
const gchar* sender
);
void (* shutdown) (
EBookBackend* backend
);
void (* impl_contains_email) (
EBookBackend* backend,
EDataBook* book,
guint32 opid,
GCancellable* cancellable,
const gchar* email_address
);
void (* impl_set_view_sort_fields) (
EBookBackend* backend,
gsize view_id,
const EBookClientViewSortFields* fields
);
guint (* impl_get_view_n_total) (
EBookBackend* backend,
gsize view_id
);
EBookIndices* (* impl_dup_view_indices) (
EBookBackend* backend,
gsize view_id
);
GPtrArray* (* impl_dup_view_contacts) (
EBookBackend* backend,
gsize view_id,
guint range_start,
guint range_length
);
gpointer reserved_padding;
}
Class structure for the EBookBackend class.
These virtual methods must be implemented when writing an addressbook backend.
Class members
use_serial_dispatch_queue: gbooleanWhether a serial dispatch queue should be used for this backend or not. The default is
TRUE.impl_get_backend_property: gchar* (* impl_get_backend_property) ( EBookBackend* backend, const gchar* prop_name )Fetch a property value by name from the backend.
impl_open: void (* impl_open) ( EBookBackend* backend, EDataBook* book, guint32 opid, GCancellable* cancellable )Open the backend.
impl_refresh: void (* impl_refresh) ( EBookBackend* backend, EDataBook* book, guint32 opid, GCancellable* cancellable )Refresh the backend.
impl_create_contacts: void (* impl_create_contacts) ( EBookBackend* backend, EDataBook* book, guint32 opid, GCancellable* cancellable, const gchar* const* vcards, guint32 opflags )Add and store the passed vcards.
impl_modify_contacts: void (* impl_modify_contacts) ( EBookBackend* backend, EDataBook* book, guint32 opid, GCancellable* cancellable, const gchar* const* vcards, guint32 opflags )Modify the existing contacts using the passed vcards.
impl_remove_contacts: void (* impl_remove_contacts) ( EBookBackend* backend, EDataBook* book, guint32 opid, GCancellable* cancellable, const gchar* const* uids, guint32 opflags )Remove the contacts specified by the passed UIDs.
impl_get_contact: void (* impl_get_contact) ( EBookBackend* backend, EDataBook* book, guint32 opid, GCancellable* cancellable, const gchar* id )Fetch a contact by UID.
impl_get_contact_list: void (* impl_get_contact_list) ( EBookBackend* backend, EDataBook* book, guint32 opid, GCancellable* cancellable, const gchar* query )Fetch a list of contacts based on a search expression.
impl_get_contact_list_uids: void (* impl_get_contact_list_uids) ( EBookBackend* backend, EDataBook* book, guint32 opid, GCancellable* cancellable, const gchar* query )Fetch a list of contact UIDs based on a search expression.
impl_start_view: void (* impl_start_view) ( EBookBackend* backend, EDataBookView* view )Start up the specified view.
impl_stop_view: void (* impl_stop_view) ( EBookBackend* backend, EDataBookView* view )Stop the specified view.
impl_notify_update: void (* impl_notify_update) ( EBookBackend* backend, const EContact* contact )Notify changes which might have occured for a given contact.
impl_get_direct_book: EDataBookDirect* (* impl_get_direct_book) ( EBookBackend* backend )For addressbook backends which support Direct Read Access, report some information on how to access the addressbook persistance directly.
impl_configure_direct: void (* impl_configure_direct) ( EBookBackend* backend, const gchar* config )For addressbook backends which support Direct Read Access, configure a backend instantiated on the client side for Direct Read Access, using data reported from the server via the
get_direct_bookmethod.impl_set_locale: gboolean (* impl_set_locale) ( EBookBackend* backend, const gchar* locale, GCancellable* cancellable, GError** error )Store & remember the passed locale setting.
impl_dup_locale: gchar* (* impl_dup_locale) ( EBookBackend* backend )Return the currently set locale setting (must be a string duplicate, for thread safety).
impl_create_cursor: EDataBookCursor* (* impl_create_cursor) ( EBookBackend* backend, EContactField* sort_fields, EBookCursorSortType* sort_types, guint n_fields, GError** error )Create an
EDataBookCursor.impl_delete_cursor: gboolean (* impl_delete_cursor) ( EBookBackend* backend, EDataBookCursor* cursor, GError** error )Delete an
EDataBookCursorpreviously created by this backend.closed: void (* closed) ( EBookBackend* backend, const gchar* sender )A signal notifying that the backend was closed.
shutdown: void (* shutdown) ( EBookBackend* backend )A signal notifying that the backend is being shut down.
impl_contains_email: void (* impl_contains_email) ( EBookBackend* backend, EDataBook* book, guint32 opid, GCancellable* cancellable, const gchar* email_address )Checkes whether the backend contains an email address.
impl_set_view_sort_fields: void (* impl_set_view_sort_fields) ( EBookBackend* backend, gsize view_id, const EBookClientViewSortFields* fields )Sets sort fields for “manual query” views; default implementation saves the values into internal structures, which can be read back with e_book_backend_dup_view_sort_fields(). Since 3.50.
impl_get_view_n_total: guint (* impl_get_view_n_total) ( EBookBackend* backend, gsize view_id )Retrieve how many contacts a “manual query” view has; default implementation returns value set by e_book_backend_set_view_n_total(). Since: 3.50.
impl_dup_view_indices: EBookIndices* (* impl_dup_view_indices) ( EBookBackend* backend, gsize view_id )Retrieve indexes into an alphabet for contacts in the “manual query” view; default implementation returns value set by e_book_backend_set_view_indices(). Since: 3.50.
impl_dup_view_contacts: GPtrArray* (* impl_dup_view_contacts) ( EBookBackend* backend, gsize view_id, guint range_start, guint range_length )Returns contacts in the given range of the sorted “manual query” view; default implementation tracks view’s connect and returns the contacts accordingly. Since: 3.50.
reserved_padding: gpointerNo description available.
Virtual methods
EDataBook.BookBackendClass.impl_configure_direct
For addressbook backends which support Direct Read Access, configure a
backend instantiated on the client side for Direct Read Access, using data
reported from the server via the get_direct_book method.
EDataBook.BookBackendClass.impl_contains_email
Checkes whether the backend contains an email address.
EDataBook.BookBackendClass.impl_delete_cursor
Delete an EDataBookCursor previously created by this backend.
EDataBook.BookBackendClass.impl_dup_locale
Return the currently set locale setting (must be a string duplicate, for thread safety).
EDataBook.BookBackendClass.impl_dup_view_contacts
Returns contacts in the given range of the sorted “manual query” view; default implementation tracks view’s connect and returns the contacts accordingly. Since: 3.50.
EDataBook.BookBackendClass.impl_dup_view_indices
Retrieve indexes into an alphabet for contacts in the “manual query” view; default implementation returns value set by e_book_backend_set_view_indices(). Since: 3.50.
EDataBook.BookBackendClass.impl_get_backend_property
Fetch a property value by name from the backend.
EDataBook.BookBackendClass.impl_get_contact_list
Fetch a list of contacts based on a search expression.
EDataBook.BookBackendClass.impl_get_contact_list_uids
Fetch a list of contact UIDs based on a search expression.
EDataBook.BookBackendClass.impl_get_direct_book
For addressbook backends which support Direct Read Access, report some information on how to access the addressbook persistance directly.
EDataBook.BookBackendClass.impl_get_view_n_total
Retrieve how many contacts a “manual query” view has; default implementation returns value set by e_book_backend_set_view_n_total(). Since: 3.50.
EDataBook.BookBackendClass.impl_modify_contacts
Modify the existing contacts using the passed vcards.
EDataBook.BookBackendClass.impl_notify_update
Notify changes which might have occured for a given contact.
EDataBook.BookBackendClass.impl_set_view_sort_fields
Sets sort fields for “manual query” views; default implementation saves the values into internal structures, which can be read back with e_book_backend_dup_view_sort_fields(). Since 3.50.