![]() |
![]() |
![]() |
Evolution-Data-Server Manual: Address Book Backend (libedata-book) | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
struct EBookBackend; #define CLIENT_BACKEND_PROPERTY_ONLINE #define CLIENT_BACKEND_PROPERTY_READONLY #define CLIENT_BACKEND_PROPERTY_CACHE_DIR #define CLIENT_BACKEND_PROPERTY_CAPABILITIES #define BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS #define BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS #define BOOK_BACKEND_PROPERTY_REVISION const gchar * e_book_backend_get_cache_dir (EBookBackend *backend
); void e_book_backend_set_cache_dir (EBookBackend *backend
,const gchar *cache_dir
); ESourceRegistry * e_book_backend_get_registry (EBookBackend *backend
); gboolean e_book_backend_get_writable (EBookBackend *backend
); void e_book_backend_set_writable (EBookBackend *backend
,gboolean writable
); 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_opened (EBookBackend *backend
); gboolean e_book_backend_is_readonly (EBookBackend *backend
); gboolean e_book_backend_is_removed (EBookBackend *backend
); void e_book_backend_get_backend_property (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *prop_name
); void e_book_backend_open (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,gboolean only_if_exists
); void e_book_backend_refresh (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
); void e_book_backend_create_contacts (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const GSList *vcards
); void e_book_backend_remove_contacts (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const GSList *id_list
); void e_book_backend_modify_contacts (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const GSList *vcards
); 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_get_contact_list_uids (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *query
); void e_book_backend_start_view (EBookBackend *backend
,EDataBookView *view
); void e_book_backend_stop_view (EBookBackend *backend
,EDataBookView *view
); void e_book_backend_add_view (EBookBackend *backend
,EDataBookView *view
); void e_book_backend_remove_view (EBookBackend *backend
,EDataBookView *view
); GList * e_book_backend_list_views (EBookBackend *backend
); 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_error (EBookBackend *backend
,const gchar *message
); void e_book_backend_notify_property_changed (EBookBackend *backend
,const gchar *prop_name
,const gchar *prop_value
); void e_book_backend_sync (EBookBackend *backend
); void e_book_backend_set_is_removed (EBookBackend *backend
,gboolean is_removed
); #define CLIENT_BACKEND_PROPERTY_OPENED #define CLIENT_BACKEND_PROPERTY_OPENING #define BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS gboolean e_book_backend_is_opening (EBookBackend *backend
); void e_book_backend_set_backend_property (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *prop_name
,const gchar *prop_value
); void e_book_backend_foreach_view (EBookBackend *backend
,gboolean (*callback) (EDataBookView *view, gpointer user_data)
,gpointer user_data
); void e_book_backend_notify_opened (EBookBackend *backend
,GError *error
); void e_book_backend_notify_readonly (EBookBackend *backend
,gboolean is_readonly
); void e_book_backend_notify_online (EBookBackend *backend
,gboolean is_online
); void e_book_backend_respond_opened (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GError *error
);
"cache-dir" gchar* : Read / Write "registry" ESourceRegistry* : Read / Write / Construct Only "writable" gboolean : Read / Write
#define CLIENT_BACKEND_PROPERTY_ONLINE "online"
FIXME: Document me.
Since 3.2
#define CLIENT_BACKEND_PROPERTY_READONLY "readonly"
FIXME: Document me.
Since 3.2
#define CLIENT_BACKEND_PROPERTY_CACHE_DIR "cache-dir"
FIXME: Document me.
Since 3.2
#define CLIENT_BACKEND_PROPERTY_CAPABILITIES "capabilities"
FIXME: Document me.
Since 3.2
#define BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS "required-fields"
FIXME: Document me.
Since 3.2
#define BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS "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
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
ESourceRegistry * e_book_backend_get_registry (EBookBackend *backend
);
Returns the data source registry to which "source" belongs.
|
an EBookBackend |
Returns : |
an ESourceRegistry |
Since 3.6
gboolean e_book_backend_get_writable (EBookBackend *backend
);
Returns whether backend
will accept changes to its data content.
|
an EBookBackend |
Returns : |
whether backend is writable |
Since 3.8
void e_book_backend_set_writable (EBookBackend *backend
,gboolean writable
);
Sets whether backend
will accept changes to its data content.
|
an EBookBackend |
|
whether backend is writable |
Since 3.8
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_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()
.
|
an EBookBackend |
Returns : |
TRUE if fully opened, FALSE otherwise. |
Since 3.2
gboolean e_book_backend_is_readonly (EBookBackend *backend
);
Checks if we can write to backend
.
|
an EBookBackend |
Returns : |
TRUE if read-only, FALSE if not. |
Since 3.2
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_get_backend_property (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *prop_name
);
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_refresh (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
);
Refreshes the address book being accessed by the given backend.
This might be finished with e_data_book_respond_refresh()
,
and it might be called as soon as possible; it doesn't mean
that the refreshing is done after calling that, the backend
is only notifying client whether it started the refresh process
or not.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
Since 3.2
void e_book_backend_create_contacts (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const GSList *vcards
);
Executes a 'create contacts' request specified by opid
on book
using backend
.
This might be finished with e_data_book_respond_create_contacts()
.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
|
a GSList of vCards to add |
Since 3.4
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_contacts (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const GSList *vcards
);
Executes a 'modify contacts' request specified by opid
on book
using backend
.
This might be finished with e_data_book_respond_modify_contacts()
.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
|
the VCards to update |
Since 3.4
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_get_contact_list_uids (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *query
);
Executes a 'get contact list uids' request specified by opid
on book
using backend
.
This might be finished with e_data_book_respond_get_contact_list_uids()
.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
|
the s-expression to match |
Since 3.2
void e_book_backend_start_view (EBookBackend *backend
,EDataBookView *view
);
Starts running the query specified by view
, emitting signals for
matching contacts.
|
an EBookBackend |
|
the EDataBookView to start |
void e_book_backend_stop_view (EBookBackend *backend
,EDataBookView *view
);
Stops running the query specified by view
, emitting no more signals.
|
an EBookBackend |
|
the EDataBookView to stop |
void e_book_backend_add_view (EBookBackend *backend
,EDataBookView *view
);
Adds view
to backend
for querying.
|
an EBookBackend |
|
an EDataBookView |
void e_book_backend_remove_view (EBookBackend *backend
,EDataBookView *view
);
Removes view
from backend
.
|
an EBookBackend |
|
an EDataBookView |
GList * e_book_backend_list_views (EBookBackend *backend
);
Returns a list of EDataBookView instances added with
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()
when finished
with them. Free the returned list itself with g_list_free()
.
An easy way to free the list properly in one step is as follows:
1 |
g_list_free_full (list, g_object_unref); |
|
an EBookBackend |
Returns : |
a list of book views |
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.
|
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_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.
|
an EBookBackend |
|
an error message |
Since 3.2
void e_book_backend_notify_property_changed (EBookBackend *backend
,const gchar *prop_name
,const gchar *prop_value
);
Notifies clients about property value change.
|
an EBookBackend |
|
property name, which changed |
|
new property value |
Since 3.2
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 |
#define CLIENT_BACKEND_PROPERTY_OPENED "opened"
CLIENT_BACKEND_PROPERTY_OPENED
has been deprecated since version 3.8 and should not be used in newly-written code. Clients don't need to care if they're fully opened
anymore. This property will always return TRUE
.
FIXME: Document me.
Since 3.2
#define CLIENT_BACKEND_PROPERTY_OPENING "opening"
CLIENT_BACKEND_PROPERTY_OPENING
has been deprecated since version 3.8 and should not be used in newly-written code. Clients don't need to care if they're fully opened
anymore. This property will always return FALSE
.
FIXME: Document me.
Since 3.2
#define BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS "supported-auth-methods"
BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS
has been deprecated since version 3.8 and should not be used in newly-written code. The property is no longer supported.
Since 3.2
gboolean e_book_backend_is_opening (EBookBackend *backend
);
e_book_backend_is_opening
has been deprecated since version 3.8 and should not be used in newly-written code. This function is no longer relevant,
and always returns FALSE
.
Checks if backend
is processing its opening phase, which
includes everything since the e_book_backend_open()
call,
through authentication, up to e_book_backend_notify_opened()
.
This property is managed automatically and the backend deny
every operation except of cancel and authenticate_user while
it is being opening.
|
an EBookBackend |
Returns : |
FALSE always |
Since 3.2
void e_book_backend_set_backend_property (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GCancellable *cancellable
,const gchar *prop_name
,const gchar *prop_value
);
e_book_backend_set_backend_property
has been deprecated since version 3.8 and should not be used in newly-written code. This function no longer does anything.
Calls the set_backend_property method on the given backend.
This might be finished with e_data_book_respond_set_backend_property()
.
Default implementation simply returns an 'unsupported' error.
The subclass may always call this default implementation for properties
which fetching it doesn't overwrite.
|
an EBookBackend |
|
an EDataBook |
|
the ID to use for this operation |
|
a GCancellable for the operation |
|
property name to change; cannot be NULL |
|
value to set to prop_name ; cannot be NULL |
Since 3.2
void e_book_backend_foreach_view (EBookBackend *backend
,gboolean (*callback) (EDataBookView *view, gpointer user_data)
,gpointer user_data
);
e_book_backend_foreach_view
has been deprecated since version 3.8 and should not be used in newly-written code. Use e_book_backend_list_views()
instead.
Calls callback
for each known book view of this backend
.
callback
returns FALSE
to stop further processing.
|
an EBookBackend |
|
callback to call |
|
user_data passed into the callback
|
Since 3.2
void e_book_backend_notify_opened (EBookBackend *backend
,GError *error
);
e_book_backend_notify_opened
has been deprecated since version 3.8 and should not be used in newly-written code. Use e_data_book_respond_open()
instead.
Notifies clients that backend
finished its opening phase.
See e_book_backend_open()
for more information how the opening
phase works. Calling this function changes 'opening' property,
same as 'opened'. 'opening' is set to FALSE
and the backend
is considered 'opened' only if the error
is NULL
.
See also: e_book_backend_respond_opened()
Note: The error
is freed automatically if not NULL
.
Meant to be used by backend implementations.
|
an EBookBackend |
|
a GError corresponding to the error encountered during
the opening phase. Use NULL for success. The error is freed
automatically if not NULL . |
Since 3.2
void e_book_backend_notify_readonly (EBookBackend *backend
,gboolean is_readonly
);
e_book_backend_notify_readonly
has been deprecated since version 3.8 and should not be used in newly-written code. Use e_book_backend_set_writable()
instead.
Notifies all backend's clients about the current readonly state.
|
an EBookBackend |
|
flag indicating readonly status |
Since 3.2
void e_book_backend_notify_online (EBookBackend *backend
,gboolean is_online
);
e_book_backend_notify_online
has been deprecated since version 3.8 and should not be used in newly-written code. Use e_backend_set_online()
instead.
Notifies clients of backend
's connection status indicated by is_online
.
Meant to be used by backend implementations.
|
an EBookBackend |
|
flag indicating whether backend is connected and online |
Since 3.2
void e_book_backend_respond_opened (EBookBackend *backend
,EDataBook *book
,guint32 opid
,GError *error
);
e_book_backend_respond_opened
has been deprecated since version 3.8 and should not be used in newly-written code. Use e_data_book_respond_open()
instead.
This is a replacement for e_data_book_respond_open()
for cases where
the finish of 'open' method call also finishes backend opening phase.
This function covers calling of both e_book_backend_notify_opened()
and e_data_book_respond_open()
with the same error
.
See e_book_backend_open()
for more details how the opening phase works.
|
an EBookBackend |
|
an EDataBook |
|
an operation ID |
|
result error; can be NULL , if it isn't then it's automatically freed |
Since 3.2
"cache-dir"
property "cache-dir" gchar* : Read / Write
The backend's cache directory.
Default value: NULL
"registry"
property"registry" ESourceRegistry* : Read / Write / Construct Only
Data source registry.