![]() |
![]() |
![]() |
Evolution-Data-Server Manual: Address Book Backend (libedata-book) | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
struct EBookBackend; const gchar * e_book_backend_get_cache_dir (EBookBackend *backend
); void e_book_backend_set_cache_dir (EBookBackend *backend
,const gchar *cache_dir
); ESource * e_book_backend_get_source (EBookBackend *backend
); gboolean e_book_backend_add_client (EBookBackend *backend
,EDataBook *book
); void e_book_backend_remove_client (EBookBackend *backend
,EDataBook *book
); gboolean e_book_backend_is_removed (EBookBackend *backend
); void e_book_backend_open (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,gboolean only_if_exists
); void e_book_backend_remove (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
); void e_book_backend_create_contact (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *vcard
); void e_book_backend_remove_contacts (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const GSList *id_list
); void e_book_backend_modify_contact (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *vcard
); void e_book_backend_get_contact (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *id
); void e_book_backend_get_contact_list (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *query
); void e_book_backend_authenticate_user (EBookBackend *backend
,GCancellable *cancellable
,ECredentials *credentials
); void e_book_backend_start_book_view (EBookBackend *backend
,EDataBookView *view
); void e_book_backend_stop_book_view (EBookBackend *backend
,EDataBookView *view
); void e_book_backend_add_book_view (EBookBackend *backend
,EDataBookView *view
); void e_book_backend_remove_book_view (EBookBackend *backend
,EDataBookView *view
); void e_book_backend_notify_update (EBookBackend *backend
,const EContact *contact
); void e_book_backend_notify_remove (EBookBackend *backend
,const gchar *id
); void e_book_backend_notify_complete (EBookBackend *backend
); void e_book_backend_notify_auth_required (EBookBackend *backend
,gboolean is_self
,const ECredentials *credentials
); void e_book_backend_sync (EBookBackend *backend
); void e_book_backend_set_is_removed (EBookBackend *backend
,gboolean is_removed
); struct EBookBackendClass;
const gchar * e_book_backend_get_cache_dir (EBookBackend *backend
);
Returns the cache directory for the given backend.
|
an EBookBackend |
Returns : |
the cache directory for the backend |
Since 2.32
void e_book_backend_set_cache_dir (EBookBackend *backend
,const gchar *cache_dir
);
Sets the cache directory for the given backend.
Note that EBookBackend is initialized with a usable default based on
the ESource given to e_book_backend_open()
. Backends should
not override the default without good reason.
|
an EBookBackend |
|
a local cache directory |
Since 2.32
ESource * e_book_backend_get_source (EBookBackend *backend
);
Queries the source that an addressbook backend is serving.
|
An addressbook backend. |
Returns : |
ESource for the backend. |
gboolean e_book_backend_add_client (EBookBackend *backend
,EDataBook *book
);
Adds a client to an addressbook backend.
|
An addressbook backend. |
|
the corba object representing the client connection. |
Returns : |
TRUE on success, FALSE on failure to add the client. |
void e_book_backend_remove_client (EBookBackend *backend
,EDataBook *book
);
Removes book
from the list of backend
's clients.
|
an EBookBackend |
|
an EDataBook to remove |
gboolean e_book_backend_is_removed (EBookBackend *backend
);
Checks if backend
has been removed from its physical storage.
|
an EBookBackend |
Returns : |
TRUE if backend has been removed, FALSE otherwise.
|
void e_book_backend_open (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,gboolean only_if_exists
);
Executes an 'open' request specified by opid
on book
using backend
. This call might be finished
with e_data_book_respond_open()
or e_book_backend_respond_opened()
,
though the overall opening phase finishes only after call
of e_book_backend_notify_opened()
after which call the backend
is either fully opened (including authentication against (remote)
server/storage) or an error was encountered during this opening phase.
'opened' and 'opening' properties are updated automatically.
The backend refuses all other operations until the opening phase is finished.
The e_book_backend_notify_opened()
is called either from this function
or from e_book_backend_authenticate_user()
, or after necessary steps
initiated by these two functions.
The opening phase usually works like this:
1) client requests open for the backend
2) server receives this request and calls e_book_backend_open()
- the opening phase begun
3) either the backend is opened during this call, and notifies client
with e_book_backend_notify_opened()
about that. This is usually
for local backends; their opening phase is finished
4) or the backend requires authentication, thus it notifies client
about that with e_book_backend_notify_auth_required()
and is
waiting for credentials, which will be received from client
by e_book_backend_authenticate_user()
call. Backend's opening
phase is still running in this case, thus it doesn't call
e_book_backend_notify_opened()
within e_book_backend_open()
call.
5) when backend receives credentials in e_book_backend_authenticate_user()
then it tries to authenticate against a server/storage with them
and only after it knows result of the authentication, whether user
was or wasn't authenticated, it notifies client with the result
by e_book_backend_notify_opened()
and it's opening phase is
finished now. If there was no error returned then the backend is
considered opened, otherwise it's considered closed. Use AuthenticationFailed
error when the given credentials were rejected by the server/store, which
will result in a re-prompt on the client side, otherwise use AuthenticationRequired
if there was anything wrong with the given credentials. Set error's
message to a reason for a re-prompt, it'll be shown to a user.
6) client checks error returned from e_book_backend_notify_opened()
and
reprompts for a password if it was AuthenticationFailed. Otherwise
considers backend opened based on the error presence (no error means success).
In any case, the call of e_book_backend_open()
should be always finished
with e_data_book_respond_open()
, which has no influence on the opening phase,
or alternatively with e_book_backend_respond_opened()
. Never use authentication
errors in e_data_book_respond_open()
to notify the client the authentication is
required, there is e_book_backend_notify_auth_required()
for this.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
|
TRUE to prevent the creation of a new book
|
void e_book_backend_remove (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
);
Executes a 'remove' request to remove all of backend
's data,
specified by opid
on book
.
This might be finished with e_data_book_respond_remove()
.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
void e_book_backend_create_contact (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *vcard
);
Executes a 'create contact' request specified by opid
on book
using backend
.
This might be finished with e_data_book_respond_create()
.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
|
the VCard to add |
void e_book_backend_remove_contacts (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const GSList *id_list
);
Executes a 'remove contacts' request specified by opid
on book
using backend
.
This might be finished with e_data_book_respond_remove_contacts()
.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
|
list of string IDs to remove |
void e_book_backend_modify_contact (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *vcard
);
Executes a 'modify contact' request specified by opid
on book
using backend
.
This might be finished with e_data_book_respond_modify()
.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
|
the VCard to update |
void e_book_backend_get_contact (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *id
);
Executes a 'get contact' request specified by opid
on book
using backend
.
This might be finished with e_data_book_respond_get_contact()
.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
|
the ID of the contact to get |
void e_book_backend_get_contact_list (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *query
);
Executes a 'get contact list' request specified by opid
on book
using backend
.
This might be finished with e_data_book_respond_get_contact_list()
.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
|
the s-expression to match |
void e_book_backend_authenticate_user (EBookBackend *backend
,GCancellable *cancellable
,ECredentials *credentials
);
Notifies backend
about credentials
provided by user to use
for authentication. This notification is usually called during
opening phase as a response to e_book_backend_notify_auth_required()
on the client side and it results in setting property 'opening' to TRUE
unless the backend is already opened. This function finishes opening
phase, thus it should be finished with e_book_backend_notify_opened()
.
See information at e_book_backend_open()
for more details
how the opening phase works.
|
an EBookBackend |
|
a GCancellable for the operation |
|
ECredentials to use for authentication |
void e_book_backend_start_book_view (EBookBackend *backend
,EDataBookView *view
);
Starts running the query specified by book_view
, emitting
signals for matching contacts.
|
an EBookBackend |
|
void e_book_backend_stop_book_view (EBookBackend *backend
,EDataBookView *view
);
Stops running the query specified by book_view
, emitting
no more signals.
|
an EBookBackend |
|
void e_book_backend_add_book_view (EBookBackend *backend
,EDataBookView *view
);
Adds view
to backend
for querying.
|
an EBookBackend |
|
an EDataBookView |
void e_book_backend_remove_book_view (EBookBackend *backend
,EDataBookView *view
);
Removes view
from backend
.
|
an EBookBackend |
|
an EDataBookView |
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()
and e_data_book_respond_modify()
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.
|
an EBookBackend |
|
a new or modified contact |
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.
|
an EBookBackend |
|
a contact id |
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.
|
an EBookbackend |
void e_book_backend_notify_auth_required (EBookBackend *backend
,gboolean is_self
,const ECredentials *credentials
);
Notifies clients that backend
requires authentication in order to
connect. This function call does not influence 'opening', but
influences 'opened' property, which is set to FALSE
when is_self
is TRUE
or credentials
is NULL
. Opening phase is finished
by e_book_backend_notify_opened()
if this is requested for backend
.
See e_book_backend_open()
for a description how the whole opening
phase works.
Meant to be used by backend implementations.
|
an EBookBackend |
|
Use TRUE to indicate the authentication is required
for the backend , otheriwse the authentication is for any
other source. Having credentials NULL means is_self
automatically.
|
|
an ECredentials that contains extra information for
a source for which authentication is requested.
This parameter can be NULL to indicate "for this book".
|
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.
|
an EBookbackend |
Since 1.12
void e_book_backend_set_is_removed (EBookBackend *backend
,gboolean is_removed
);
Sets the flag indicating whether backend
was removed to is_removed
.
Meant to be used by backend implementations.
|
an EBookBackend |
|
A flag indicating whether the backend's storage was removed |
struct EBookBackendClass { GObjectClass parent_class; /* Virtual methods */ void (* get_backend_property) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *prop_name); void (* set_backend_property) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *prop_name, const gchar *prop_value); void (* open) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, gboolean only_if_exists); void (* remove) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable); void (* set_online) (EBookBackend *backend, gboolean is_online); void (* authenticate_user) (EBookBackend *backend, GCancellable *cancellable, ECredentials *credentials); void (* refresh) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable); void (* create_contact) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *vcard); void (* remove_contacts) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const GSList *id_list); void (* modify_contact) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *vcard); 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_book_view) (EBookBackend *backend, EDataBookView *book_view); void (* stop_book_view) (EBookBackend *backend, EDataBookView *book_view); /* Notification signals */ void (* last_client_gone) (EBookBackend *backend); void (* sync) (EBookBackend *backend); };
"last-client-gone"
signalvoid user_function (EBookBackend *ebookbackend, gpointer user_data) : Run First
|
the object which received the signal. |
|
user data set when the signal handler was connected. |