Top | ![]() |
![]() |
![]() |
![]() |
#define | CLIENT_BACKEND_PROPERTY_CAPABILITIES |
#define | BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS |
#define | BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS |
#define | BOOK_BACKEND_PROPERTY_REVISION |
struct | EBookBackend |
struct | EBookBackendClass |
This is the main server facing API for interfacing with addressbook backends, addressbook backends must implement methods on this class.
constgchar * e_book_backend_get_cache_dir (EBookBackend *backend
);
Returns the cache directory path used by backend
.
Since: 2.32
gchar * e_book_backend_dup_cache_dir (EBookBackend *backend
);
Thread-safe variation of e_book_backend_get_cache_dir()
.
Use this function when accessing backend
from multiple threads.
The returned string should be freed with g_free()
Since: 3.10
void e_book_backend_set_cache_dir (EBookBackend *backend
,const
);gchar *cache_dir
Sets the cache directory path for use by backend
.
Note that EBookBackend is initialized with a default cache directory path which should suffice for most cases. Backends should not override the default path without good reason.
Since: 2.32
EDataBook * e_book_backend_ref_data_book (EBookBackend *backend
);
Returns the backend
. The backend
's native API.
An backend
is first created.
If an NULL
The returned g_object_unref()
Since: 3.10
void e_book_backend_set_data_book (EBookBackend *backend
,);
EDataBook *data_book
Sets the backend
. The backend
's native API.
An backend
is first created.
Since: 3.10
GProxyResolver * e_book_backend_ref_proxy_resolver (EBookBackend *backend
);
Returns the backend
(if applicable), as indicated
by the backend
's
The returned g_object_unref()
Since: 3.12
ESourceRegistry *
e_book_backend_get_registry (EBookBackend *backend
);
Returns the data source registry to which
Since: 3.6
gboolean e_book_backend_get_writable (EBookBackend *backend
);
Returns whether backend
will accept changes to its data content.
Since: 3.8
void e_book_backend_set_writable (EBookBackend *backend
,);
gboolean writable
Sets whether backend
will accept changes to its data content.
Since: 3.8
gboolean e_book_backend_is_opened (EBookBackend *backend
);
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
within call of e_book_backend_notify_opened()
Since: 3.2
gboolean e_book_backend_is_readonly (EBookBackend *backend
);
Checks if we can write to backend
.
Since: 3.2
gchar * e_book_backend_get_backend_property (EBookBackend *backend
,const
);gchar *prop_name
Obtains the value of the backend property named prop_name
.
Freed the returned string with g_free()
Since: 3.10
gboolean e_book_backend_open_sync (EBookBackend *backend
,,
GCancellable *cancellable);
GError **error
"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.
If an error occurs, the function will set error
and return FALSE
backend |
an EBookBackend |
|
cancellable |
optional |
|
error |
return location for a |
Since: 3.10
void e_book_backend_open (EBookBackend *backend
,,
GCancellable *cancellable,
GAsyncReadyCallback callback);
gpointer user_data
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.
When the operation is finished, callback
will be called. You can then
call e_book_backend_open_finish()
to get the result of the operation.
backend |
an EBookBackend |
|
cancellable |
optional |
|
callback |
a |
|
user_data |
data to pass to the callback function |
Since: 3.10
gboolean e_book_backend_open_finish (EBookBackend *backend
,,
GAsyncResult *result);
GError **error
Finishes the operation started with e_book_backend_open()
.
If an error occurred, the function will set error
and return FALSE
backend |
an EBookBackend |
|
result |
a |
|
error |
return location for a |
Since: 3.10
gboolean e_book_backend_refresh_sync (EBookBackend *backend
,,
GCancellable *cancellable);
GError **error
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.
If an error occurs while initiating the refresh, the function will set
error
and return FALSE
backend
does not support refreshing,
the function will set an E_CLIENT_ERROR_NOT_SUPPORTED
error and return
FALSE
backend |
an EBookBackend |
|
cancellable |
optional |
|
error |
return location for a |
Since: 3.10
void e_book_backend_refresh (EBookBackend *backend
,,
GCancellable *cancellable,
GAsyncReadyCallback callback);
gpointer user_data
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.
Once the refresh is initiated, callback
will be called. You can then
call e_book_backend_refresh_finish()
to get the result of the initiation.
backend |
an EBookBackend |
|
cancellable |
optional |
|
callback |
a |
|
user_data |
data to pass to the callback function |
Since: 3.10
gboolean e_book_backend_refresh_finish (EBookBackend *backend
,,
GAsyncResult *result);
GError **error
Finishes the refresh initiation started with e_book_backend_refresh()
.
If an error occurred while initiating the refresh, the function will set
error
and return FALSE
backend
does not support refreshing,
the function will set an E_CLIENT_ERROR_NOT_SUPPORTED
error and return
FALSE
backend |
an EBookBackend |
|
result |
a |
|
error |
return location for a |
Since: 3.10
gboolean e_book_backend_create_contacts_sync (EBookBackend *backend
,const
,gchar * const *vcards,
GQueue *out_contacts,
GCancellable *cancellable);
GError **error
Creates one or more new contacts from vcards
, and deposits an out_contacts
.
The returned g_object_unref()
If an error occurs, the function will set error
and return FALSE
backend |
an EBookBackend |
|
vcards |
a |
|
out_contacts |
a |
|
cancellable |
optional |
|
error |
return location for a |
Since: 3.10
void e_book_backend_create_contacts (EBookBackend *backend
,const
,gchar * const *vcards,
GCancellable *cancellable,
GAsyncReadyCallback callback);
gpointer user_data
Asynchronously creates one or more new contacts from vcards
.
When the operation is finished, callback
will be called. You can then
call e_book_backend_create_contacts_finish()
to get the result of the
operation.
backend |
an EBookBackend |
|
vcards |
a |
|
cancellable |
optional |
|
callback |
a |
|
user_data |
data to pass to the callback function |
Since: 3.10
gboolean e_book_backend_create_contacts_finish (EBookBackend *backend
,,
GAsyncResult *result,
GQueue *out_contacts);
GError **error
Finishes the operation started with e_book_backend_create_contacts()
.
An out_contacts
. The returned g_object_unref()
If an error occurred, the function will set error
and return FALSE
backend |
an EBookBackend |
|
result |
a |
|
out_contacts |
a |
|
error |
return location for a |
Since: 3.10
gboolean e_book_backend_modify_contacts_sync (EBookBackend *backend
,const
,gchar * const *vcards,
GCancellable *cancellable);
GError **error
Modifies one or more contacts according to vcards
.
If an error occurs, the function will set error
and return FALSE
backend |
an EBookBackend |
|
vcards |
a |
|
cancellable |
optional |
|
error |
return location for a |
Since: 3.10
void e_book_backend_modify_contacts (EBookBackend *backend
,const
,gchar * const *vcards,
GCancellable *cancellable,
GAsyncReadyCallback callback);
gpointer user_data
Asynchronously modifies one or more contacts according to vcards
.
When the operation is finished, callback
will be called. You can then
call e_book_backend_modify_contacts_finish()
to get the result of the
operation.
backend |
an EBookBackend |
|
vcards |
a |
|
cancellable |
optional |
|
callback |
a |
|
user_data |
data to pass to the callback function |
Since: 3.10
gboolean e_book_backend_modify_contacts_finish (EBookBackend *backend
,,
GAsyncResult *result);
GError **error
Finishes the operation started with e_book_backend_modify_contacts()
.
If an error occurred, the function will set error
and return FALSE
backend |
an EBookBackend |
|
result |
a |
|
error |
return location for a |
Since: 3.10
gboolean e_book_backend_remove_contacts_sync (EBookBackend *backend
,const
,gchar * const *uids,
GCancellable *cancellable);
GError **error
Removes one or more contacts according to uids
.
If an error occurs, the function will set error
and return FALSE
backend |
an EBookBackend |
|
uids |
a |
|
cancellable |
optional |
|
error |
return location for a |
Since: 3.10
void e_book_backend_remove_contacts (EBookBackend *backend
,const
,gchar * const *uids,
GCancellable *cancellable,
GAsyncReadyCallback callback);
gpointer user_data
Asynchronously removes one or more contacts according to uids
.
When the operation is finished, callback
will be called. You can then
call e_book_backend_remove_contacts_finish()
to get the result of the
operation.
backend |
an EBookBackend |
|
uids |
a |
|
cancellable |
optional |
|
callback |
a |
|
user_data |
data to pass to the callback function |
Since: 3.10
gboolean e_book_backend_remove_contacts_finish (EBookBackend *backend
,,
GAsyncResult *result);
GError **error
Finishes the operation started with e_book_backend_remove_contacts()
.
If an error occurred, the function will set error
and return FALSE
backend |
an EBookBackend |
|
result |
a |
|
error |
return location for a |
Since: 3.10
EContact * e_book_backend_get_contact_sync (EBookBackend *backend
,const
,gchar *uid,
GCancellable *cancellable);
GError **error
Obtains an uid
.
The returned g_object_unref()
If an error occurs, the function will set error
and return NULL
backend |
an EBookBackend |
|
uid |
a contact ID |
|
cancellable |
optional |
|
error |
return location for a |
Since: 3.10
void e_book_backend_get_contact (EBookBackend *backend
,const
,gchar *uid,
GCancellable *cancellable,
GAsyncReadyCallback callback);
gpointer user_data
Asynchronously obtains an uid
.
When the operation is finished, callback
will be called. You can
then call e_book_backend_get_contact_finish()
to get the result of the
operation.
backend |
an EBookBackend |
|
uid |
a contact ID |
|
cancellable |
optional |
|
callback |
a |
|
user_data |
data to pass to the callback function |
Since: 3.10
EContact * e_book_backend_get_contact_finish (EBookBackend *backend
,,
GAsyncResult *result);
GError **error
Finishes the operation started with e_book_backend_get_contact_finish()
.
The returned g_object_unref()
If an error occurred, the function will set error
and return NULL
backend |
an EBookBackend |
|
result |
a |
|
error |
return location for a |
Since: 3.10
gboolean e_book_backend_get_contact_list_sync (EBookBackend *backend
,const
,gchar *query,
GQueue *out_contacts,
GCancellable *cancellable);
GError **error
Obtains a set of query
, and deposits them in out_contacts
.
The returned g_object_unref()
If an error occurs, the function will set error
and return FALSE
backend |
an EBookBackend |
|
query |
a search query in S-expression format |
|
out_contacts |
a |
|
cancellable |
optional |
|
error |
return location for a |
Since: 3.10
void e_book_backend_get_contact_list (EBookBackend *backend
,const
,gchar *query,
GCancellable *cancellable,
GAsyncReadyCallback callback);
gpointer user_data
Asynchronously obtains a set of query
.
When the operation is finished, callback
will be called. You can then
call e_book_backend_get_contact_list_finish()
to get the result of the
operation.
backend |
an EBookBackend |
|
query |
a search query in S-expression format |
|
cancellable |
optional |
|
callback |
a |
|
user_data |
data to pass to the callback function |
Since: 3.10
gboolean e_book_backend_get_contact_list_finish (EBookBackend *backend
,,
GAsyncResult *result,
GQueue *out_contacts);
GError **error
Finishes the operation started with e_book_backend_get_contact_list()
.
The matching out_contacts
. The
returned g_object_unref()
If an error occurred, the function will set error
and return FALSE
backend |
an EBookBackend |
|
result |
a |
|
out_contacts |
a |
|
error |
return location for a |
Since: 3.10
gboolean e_book_backend_get_contact_list_uids_sync (EBookBackend *backend
,const
,gchar *query,
GQueue *out_uids,
GCancellable *cancellable);
GError **error
Obtains a set of ID strings for contacts which satisfy the criteria
specified in query
, and deposits them in out_uids
.
The returned ID strings must be freed with g_free()
If an error occurs, the function will set error
and return FALSE
backend |
an EBookBackend |
|
query |
a search query in S-expression format |
|
out_uids |
a |
|
cancellable |
optional |
|
error |
return location for a |
Since: 3.10
void e_book_backend_get_contact_list_uids (EBookBackend *backend
,const
,gchar *query,
GCancellable *cancellable,
GAsyncReadyCallback callback);
gpointer user_data
Asynchronously obtains a set of ID strings for contacts which satisfy
the criteria specified in query
.
When the operation is finished, callback
will be called. You can then
call e_book_backend_get_contact_list_uids_finish()
to get the result of
the operation.
backend |
an EBookBackend |
|
query |
a search query in S-expression format |
|
cancellable |
optional |
|
callback |
a |
|
user_data |
data to pass to the callback function |
Since: 3.10
gboolean e_book_backend_get_contact_list_uids_finish (EBookBackend *backend
,,
GAsyncResult *result,
GQueue *out_uids);
GError **error
Finishes the operation started with
e_book_backend_get_contact_list_uids_finish()
.
ID strings for the matching contacts are deposited in out_uids
, and
must be freed with g_free()
If an error occurs, the function will set error
and return FALSE
backend |
an EBookBackend |
|
result |
a |
|
out_uids |
a |
|
error |
return location for a |
Since: 3.10
void e_book_backend_start_view (EBookBackend *backend
,);
EDataBookView *view
Starts running the query specified by view
, emitting signals for
matching contacts.
void e_book_backend_stop_view (EBookBackend *backend
,);
EDataBookView *view
Stops running the query specified by view
, emitting no more signals.
void e_book_backend_add_view (EBookBackend *backend
,);
EDataBookView *view
Adds view
to backend
for querying.
void e_book_backend_remove_view (EBookBackend *backend
,);
EDataBookView *view
Removes view
from backend
.
GList * e_book_backend_list_views (EBookBackend *backend
);
Returns a list of e_book_backend_add_view()
.
The views returned in the list are referenced for thread-safety.
They must each be unreferenced with g_object_unref()
g_list_free()
An easy way to free the list properly in one step is as follows:
g_list_free_full (list, g_object_unref);
Since: 3.8
void e_book_backend_notify_update (EBookBackend *backend
,const
);EContact *contact
Notifies all of backend
's book views about the new or modified
contacts contact
.
e_data_book_respond_create_contacts() and e_data_book_respond_modify_contacts()
call this
function for you. You only need to call this from your backend if
contacts are created or modified by another (non-PAS-using) client.
void e_book_backend_notify_remove (EBookBackend *backend
,const
);gchar *id
Notifies all of backend
's book views that the contact with UID
id
has been removed.
e_data_book_respond_remove_contacts() calls this function for you. You only need to call this from your backend if contacts are removed by another (non-PAS-using) client.
void e_book_backend_notify_complete (EBookBackend *backend
);
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.
void e_book_backend_notify_error (EBookBackend *backend
,const
);gchar *message
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
void e_book_backend_notify_property_changed (EBookBackend *backend
,const
,gchar *prop_nameconst
);gchar *prop_value
Notifies clients about property value change.
backend |
an EBookBackend |
|
prop_name |
property name, which changed |
|
prop_value |
new property value |
Since: 3.2
EDataBookDirect * e_book_backend_get_direct_book (EBookBackend *backend
);
Tries to create an backend
if
backend supports direct read access.
A new NULL
backend
does not support direct access.
[transfer full]
Since: 3.8
void e_book_backend_configure_direct (EBookBackend *backend
,const
);gchar *config
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 e_book_backend_get_direct_book()
.
The configuration string is optional and is used to ensure that direct access backends are properly configured to interface with the same data as the running server side backend.
Since: 3.8
void e_book_backend_sync (EBookBackend *backend
);
Write all pending data to disk. This is only required under special circumstances (for example before a live backup) and should not be used in normal use.
Since: 1.12
gboolean e_book_backend_set_locale (EBookBackend *backend
,const
,gchar *locale,
GCancellable *cancellable);
GError **error
Notify the addressbook backend that the current locale has changed, this is important for backends which support ordered result lists which are locale sensitive.
backend |
an |
|
locale |
the new locale for the addressbook |
|
cancellable |
optional |
|
error |
return location for a |
Since: 3.12
gchar * e_book_backend_dup_locale (EBookBackend *backend
);
Fetches a copy of the currently configured locale for the addressbook
A copy of the currently configured locale for the addressbook.
Free with g_free()
Since: 3.12
EDataBookCursor * e_book_backend_create_cursor (EBookBackend *backend
,EContactField *sort_fields
,EBookCursorSortType *sort_types
,,
guint n_fields);
GError **error
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
.
Backends can also refuse to create cursors for some values of sort_fields
and report more specific errors.
The returned cursor belongs to backend
and should be destroyed
with e_book_backend_delete_cursor()
when no longer needed.
backend |
an EBookBackend |
|
sort_fields |
the |
|
sort_types |
the |
|
n_fields |
the number of fields in the |
|
error |
return location for a |
A newly created cursor, the cursor belongs
to the backend and should not be unreffed, or NULL
[transfer none]
Since: 3.12
gboolean e_book_backend_delete_cursor (EBookBackend *backend
,EDataBookCursor *cursor
,);
GError **error
Requests backend
to release and destroy cursor
, this
will trigger an E_CLIENT_ERROR_INVALID_ARG
error if cursor
is not owned by backend
.
backend |
an EBookBackend |
|
cursor |
the EDataBookCursor to destroy |
|
error |
return location for a |
Since: 3.12
GSimpleAsyncResult * e_book_backend_prepare_for_completion (EBookBackend *backend
,,
guint32 opid);
GQueue **result_queue
Obtains the opid
and sets result_queue
as a
place to deposit results prior to completing the
This is a temporary function to serve
backend |
an EBookBackend |
|
opid |
an operation ID given to |
|
result_queue |
return location for a |
Since: 3.10
#define CLIENT_BACKEND_PROPERTY_CAPABILITIES
FIXME: Document me.
Since: 3.2
#define BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS
FIXME: Document me.
Since: 3.2
#define BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS
FIXME: Document me.
Since: 3.2
#define BOOK_BACKEND_PROPERTY_REVISION "revision"
The current overall revision string, this can be used as a quick check to see if data has changed at all since the last time the addressbook revision was observed.
Since: 3.4
struct EBookBackend { };
Contains only private data that should be read and manipulated using the functions below.
struct EBookBackendClass { /* Set this to TRUE to use a serial dispatch queue, instead * of a concurrent dispatch queue. A serial dispatch queue * executes one method at a time in the order in which they * were called. This is generally slower than a concurrent * dispatch queue, but helps avoid thread-safety issues. */ gboolean use_serial_dispatch_queue; gchar * (*get_backend_property) (EBookBackend *backend, const gchar *prop_name); gboolean (*open_sync) (EBookBackend *backend, GCancellable *cancellable, GError **error); gboolean (*refresh_sync) (EBookBackend *backend, GCancellable *cancellable, GError **error); gboolean (*create_contacts_sync) (EBookBackend *backend, const gchar * const *vcards, GQueue *out_contacts, GCancellable *cancellable, GError **error); gboolean (*modify_contacts_sync) (EBookBackend *backend, const gchar * const *vcards, GQueue *out_contacts, GCancellable *cancellable, GError **error); gboolean (*remove_contacts_sync) (EBookBackend *backend, const gchar * const *uids, GCancellable *cancellable, GError **error); EContact * (*get_contact_sync) (EBookBackend *backend, const gchar *uid, GCancellable *cancellable, GError **error); gboolean (*get_contact_list_sync) (EBookBackend *backend, const gchar *query, GQueue *out_contacts, GCancellable *cancellable, GError **error); /* This method is optional. By default, it simply calls * get_contact_list_sync() and extracts UID strings from * the matched EContacts. Backends may override this if * they can implement it more efficiently. */ gboolean (*get_contact_list_uids_sync) (EBookBackend *backend, const gchar *query, GQueue *out_uids, GCancellable *cancellable, GError **error); /* These methods are deprecated and will be removed once all * known subclasses are converted to the new methods above. */ void (*open) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, gboolean only_if_exists); void (*refresh) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable); void (*create_contacts) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const GSList *vcards); void (*remove_contacts) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const GSList *id_list); void (*modify_contacts) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const GSList *vcards); void (*get_contact) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *id); void (*get_contact_list) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *query); void (*get_contact_list_uids) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *query); void (*start_view) (EBookBackend *backend, EDataBookView *book_view); void (*stop_view) (EBookBackend *backend, EDataBookView *book_view); void (*notify_update) (EBookBackend *backend, const EContact *contact); EDataBookDirect * (*get_direct_book) (EBookBackend *backend); void (*configure_direct) (EBookBackend *backend, const gchar *config); void (*sync) (EBookBackend *backend); gboolean (*set_locale) (EBookBackend *backend, const gchar *locale, GCancellable *cancellable, GError **error); gchar * (*dup_locale) (EBookBackend *backend); EDataBookCursor * (*create_cursor) (EBookBackend *backend, EContactField *sort_fields, EBookCursorSortType *sort_types, guint n_fields, GError **error); gboolean (*delete_cursor) (EBookBackend *backend, EDataBookCursor *cursor, GError **error); /* Signals */ void (*closed) (EBookBackend *backend, const gchar *sender); void (*shutdown) (EBookBackend *backend); };
Class structure for the EBookBackend class.
These virtual methods must be implemented when writing an addressbook backend.
Whether a serial dispatch queue should be used for this backend or not. |
||
Fetch a property value by name from the backend |
||
Open the backend |
||
Refresh the backend |
||
Add and store the passed vcards |
||
Modify the existing contacts using the passed vcards |
||
Remove the contacts specified by the passed UIDs |
||
Fetch a contact by UID |
||
Fetch a list of contacts based on a search expression |
||
Fetch a list of contact UIDs based on a search expression (optional) |
||
Deprecated method |
||
Deprecated method |
||
Deprecated method |
||
Deprecated method |
||
Deprecated method |
||
Deprecated method |
||
Deprecated method |
||
Deprecated method |
||
Start up the specified view |
||
Stop the specified view |
||
Notify changes which might have occured for a given contact |
||
For addressbook backends which support Direct Read Access, report some information on how to access the addressbook persistance directly |
||
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 |
||
Sync the backend's persistance |
||
Store & remember the passed locale setting |
||
Return the currently set locale setting (must be a string duplicate, for thread safety). |
||
Create an EDataBookCursor |
||
Delete an EDataBookCursor previously created by this backend |
||
A signal notifying that the backend was closed |
||
A signal notifying that the backend is being shut down |