EBookBackend

EBookBackend

Functions

Properties

gchar * cache-dir Read / Write

Types and Values

Object Hierarchy

    GObject
    ╰── EBackend
        ╰── EBookBackend
            ╰── EBookBackendSync

Description

Functions

e_book_backend_get_cache_dir ()

const gchar *
e_book_backend_get_cache_dir (EBookBackend *backend);

Returns the cache directory for the given backend.

Parameters

backend

an EBookBackend

 

Returns

the cache directory for the backend

Since 2.32


e_book_backend_set_cache_dir ()

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.

Parameters

backend

an EBookBackend

 

cache_dir

a local cache directory

 

Since 2.32


e_book_backend_add_client ()

gboolean
e_book_backend_add_client (EBookBackend *backend,
                           EDataBook *book);

Adds a client to an addressbook backend.

Parameters

backend

An addressbook backend.

 

book

the corba object representing the client connection.

 

Returns

TRUE on success, FALSE on failure to add the client.


e_book_backend_remove_client ()

void
e_book_backend_remove_client (EBookBackend *backend,
                              EDataBook *book);

Removes book from the list of backend 's clients.

Parameters

backend

an EBookBackend

 

book

an EDataBook to remove

 

e_book_backend_is_opened ()

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

Parameters

backend

an EBookBackend

 

Returns

TRUE if fully opened, FALSE otherwise.

Since 3.2


e_book_backend_is_opening ()

gboolean
e_book_backend_is_opening (EBookBackend *backend);

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.

Parameters

backend

an EBookBackend

 

Returns

TRUE if opening phase is in the effect, FALSE otherwise.

Since 3.2


e_book_backend_is_readonly ()

gboolean
e_book_backend_is_readonly (EBookBackend *backend);

Checks if we can write to backend .

Parameters

backend

an EBookBackend

 

Returns

TRUE if writeable, FALSE if not.

Since 3.2


e_book_backend_is_removed ()

gboolean
e_book_backend_is_removed (EBookBackend *backend);

Checks if backend has been removed from its physical storage.

Parameters

backend

an EBookBackend

 

Returns

TRUE if backend has been removed, FALSE otherwise.


e_book_backend_authenticate_user ()

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.

Parameters

backend

an EBookBackend

 

cancellable

a GCancellable for the operation

 

credentials

ECredentials to use for authentication

 

e_book_backend_get_backend_property ()

void
e_book_backend_get_backend_property (EBookBackend *backend,
                                     EDataBook *book,
                                     guint32 opid,
                                     GCancellable *cancellable,
                                     const gchar *prop_name);

e_book_backend_set_backend_property ()

void
e_book_backend_set_backend_property (EBookBackend *backend,
                                     EDataBook *book,
                                     guint32 opid,
                                     GCancellable *cancellable,
                                     const gchar *prop_name,
                                     const gchar *prop_value);

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.

Parameters

backend

an EBookBackend

 

book

an EDataBook

 

opid

the ID to use for this operation

 

cancellable

a GCancellable for the operation

 

prop_name

property name to change; cannot be NULL

 

prop_value

value to set to prop_name ; cannot be NULL

 

Since 3.2


e_book_backend_open ()

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.

Parameters

backend

an EBookBackend

 

book

an EDataBook

 

opid

the ID to use for this operation

 

cancellable

a GCancellable for the operation

 

only_if_exists

TRUE to prevent the creation of a new book

 

e_book_backend_remove ()

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

Parameters

backend

an EBookBackend

 

book

an EDataBook

 

cancellable

a GCancellable for the operation

 

opid

the ID to use for this operation

 

e_book_backend_refresh ()

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.

Parameters

backend

an EBookBackend

 

book

an EDataBook

 

opid

the ID to use for this operation

 

cancellable

a GCancellable for the operation

 

Since 3.2


e_book_backend_create_contacts ()

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

Parameters

backend

an EBookBackend

 

book

an EDataBook

 

opid

the ID to use for this operation

 

cancellable

a GCancellable for the operation

 

vcards

a GSList of vCards to add

 

Since 3.4


e_book_backend_remove_contacts ()

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

Parameters

backend

an EBookBackend

 

book

an EDataBook

 

opid

the ID to use for this operation

 

cancellable

a GCancellable for the operation

 

id_list

list of string IDs to remove

 

e_book_backend_modify_contacts ()

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

Parameters

backend

an EBookBackend

 

book

an EDataBook

 

opid

the ID to use for this operation

 

cancellable

a GCancellable for the operation

 

vcards

the VCards to update

 

Since 3.4


e_book_backend_get_contact ()

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

Parameters

backend

an EBookBackend

 

book

an EDataBook

 

opid

the ID to use for this operation

 

cancellable

a GCancellable for the operation

 

id

the ID of the contact to get

 

e_book_backend_get_contact_list ()

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

Parameters

backend

an EBookBackend

 

book

an EDataBook

 

opid

the ID to use for this operation

 

cancellable

a GCancellable for the operation

 

query

the s-expression to match

 

e_book_backend_get_contact_list_uids ()

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

Parameters

backend

an EBookBackend

 

book

an EDataBook

 

opid

the ID to use for this operation

 

cancellable

a GCancellable for the operation

 

query

the s-expression to match

 

Since 3.2


e_book_backend_start_book_view ()

void
e_book_backend_start_book_view (EBookBackend *backend,
                                EDataBookView *view);

Starts running the query specified by view , emitting signals for matching contacts.

Parameters

backend

an EBookBackend

 

view

the EDataBookView to start

 

e_book_backend_stop_book_view ()

void
e_book_backend_stop_book_view (EBookBackend *backend,
                               EDataBookView *view);

Stops running the query specified by view , emitting no more signals.

Parameters

backend

an EBookBackend

 

view

the EDataBookView to stop

 

e_book_backend_add_book_view ()

void
e_book_backend_add_book_view (EBookBackend *backend,
                              EDataBookView *view);

Adds view to backend for querying.

Parameters

backend

an EBookBackend

 

view

an EDataBookView

 

e_book_backend_remove_book_view ()

void
e_book_backend_remove_book_view (EBookBackend *backend,
                                 EDataBookView *view);

Removes view from backend .

Parameters

backend

an EBookBackend

 

view

an EDataBookView

 

e_book_backend_foreach_view ()

void
e_book_backend_foreach_view (EBookBackend *backend,
                             gboolean (*callback) (EDataBookView *view, gpointer user_data),
                             gpointer user_data);

Calls callback for each known book view of this backend . callback returns FALSE to stop further processing.

Parameters

backend

an EBookBackend

 

callback

callback to call

 

user_data

user_data passed into the callback

 

Since 3.2


e_book_backend_notify_update ()

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.

Parameters

backend

an EBookBackend

 

contact

a new or modified contact

 

e_book_backend_notify_remove ()

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.

Parameters

backend

an EBookBackend

 

id

a contact id

 

e_book_backend_notify_complete ()

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.

Parameters

backend

an EBookbackend

 

e_book_backend_notify_error ()

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.

Parameters

backend

an EBookBackend

 

message

an error message

 

Since 3.2


e_book_backend_notify_readonly ()

void
e_book_backend_notify_readonly (EBookBackend *backend,
                                gboolean is_readonly);

Notifies all backend's clients about the current readonly state.

Parameters

backend

an EBookBackend

 

is_readonly

flag indicating readonly status

 

Since 3.2


e_book_backend_notify_online ()

void
e_book_backend_notify_online (EBookBackend *backend,
                              gboolean is_online);

Notifies clients of backend 's connection status indicated by is_online . Meant to be used by backend implementations.

Parameters

backend

an EBookBackend

 

is_online

flag indicating whether backend is connected and online

 

Since 3.2


e_book_backend_notify_auth_required ()

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.

Parameters

backend

an EBookBackend

 

is_self

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.

 

credentials

an ECredentials that contains extra information for a source for which authentication is requested. This parameter can be NULL to indicate "for this book".

 

e_book_backend_notify_opened ()

void
e_book_backend_notify_opened (EBookBackend *backend,
                              GError *error);

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.

Parameters

backend

an EBookBackend

 

error

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


e_book_backend_notify_property_changed ()

void
e_book_backend_notify_property_changed
                               (EBookBackend *backend,
                                const gchar *prop_name,
                                const gchar *prop_value);

Notifies clients about property value change.

Parameters

backend

an EBookBackend

 

prop_name

property name, which changed

 

prop_value

new property value

 

Since 3.2


e_book_backend_sync ()

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.

Parameters

backend

an EBookbackend

 

Since 1.12


e_book_backend_set_is_removed ()

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.

Parameters

backend

an EBookBackend

 

is_removed

A flag indicating whether the backend's storage was removed

 

e_book_backend_respond_opened ()

void
e_book_backend_respond_opened (EBookBackend *backend,
                               EDataBook *book,
                               guint32 opid,
                               GError *error);

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.

Parameters

backend

an EBookBackend

 

book

an EDataBook

 

opid

an operation ID

 

error

result error; can be NULL, if it isn't then it's automatically freed

 

Since 3.2

Types and Values

struct EBookBackend

struct EBookBackend;

CLIENT_BACKEND_PROPERTY_OPENED

#define CLIENT_BACKEND_PROPERTY_OPENED			"opened"

FIXME: Document me.

Since 3.2


CLIENT_BACKEND_PROPERTY_OPENING

#define CLIENT_BACKEND_PROPERTY_OPENING			"opening"

FIXME: Document me.

Since 3.2


CLIENT_BACKEND_PROPERTY_ONLINE

#define CLIENT_BACKEND_PROPERTY_ONLINE			"online"

FIXME: Document me.

Since 3.2


CLIENT_BACKEND_PROPERTY_READONLY

#define CLIENT_BACKEND_PROPERTY_READONLY		"readonly"

FIXME: Document me.

Since 3.2


CLIENT_BACKEND_PROPERTY_CACHE_DIR

#define CLIENT_BACKEND_PROPERTY_CACHE_DIR		"cache-dir"

FIXME: Document me.

Since 3.2


CLIENT_BACKEND_PROPERTY_CAPABILITIES

#define CLIENT_BACKEND_PROPERTY_CAPABILITIES		"capabilities"

FIXME: Document me.

Since 3.2


BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS

#define BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS		"required-fields"

FIXME: Document me.

Since 3.2


BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS

#define BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS		"supported-fields"

FIXME: Document me.

Since 3.2


BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS

#define BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS "supported-auth-methods"

FIXME: Document me.

Since 3.2


BOOK_BACKEND_PROPERTY_REVISION

#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 EBookBackendClass

struct EBookBackendClass {
	EBackendClass 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 (* authenticate_user)		(EBookBackend *backend, GCancellable *cancellable, ECredentials *credentials);

	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_book_view)		(EBookBackend *backend, EDataBookView *book_view);
	void (* stop_book_view)		(EBookBackend *backend, EDataBookView *book_view);

	void    (* notify_update)               (EBookBackend *backend, const EContact *contact);

	/* Notification signals */
	void (* last_client_gone)		(EBookBackend *backend);
	void (* sync)			(EBookBackend *backend);
};

Property Details

The “cache-dir” property

  “cache-dir”                gchar *

Flags: Read / Write

Default value: NULL