EBookBackend

EBookBackend

Synopsis

struct              EBookBackend;
gboolean            e_book_backend_construct            (EBookBackend *backend);
GNOME_Evolution_Addressbook_CallStatus  e_book_backend_load_source
                                                        (EBookBackend *backend,
                                                         ESource *source,
                                                         gboolean only_if_exists);
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_has_out_of_proc_clients
                                                        (EBookBackend *backend);
gchar *             e_book_backend_get_static_capabilities
                                                        (EBookBackend *backend);
gboolean            e_book_backend_is_loaded            (EBookBackend *backend);
gboolean            e_book_backend_is_writable          (EBookBackend *backend);
gboolean            e_book_backend_is_removed           (EBookBackend *backend);
void                e_book_backend_open                 (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         gboolean only_if_exists);
void                e_book_backend_remove               (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid);
void                e_book_backend_create_contact       (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         const gchar *vcard);
void                e_book_backend_remove_contacts      (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         GList *id_list);
void                e_book_backend_modify_contact       (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         const gchar *vcard);
void                e_book_backend_get_contact          (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         const gchar *id);
void                e_book_backend_get_contact_list     (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         const gchar *query);
void                e_book_backend_get_changes          (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         const gchar *change_id);
void                e_book_backend_authenticate_user    (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         const gchar *user,
                                                         const gchar *passwd,
                                                         const gchar *auth_method);
void                e_book_backend_get_supported_fields (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid);
void                e_book_backend_get_required_fields  (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid);
void                e_book_backend_get_supported_auth_methods
                                                        (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid);
GNOME_Evolution_Addressbook_CallStatus  e_book_backend_cancel_operation
                                                        (EBookBackend *backend,
                                                         EDataBook *book);
void                e_book_backend_set_mode             (EBookBackend *backend,
                                                         GNOME_Evolution_Addressbook_BookMode mode);
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);
EList *             e_book_backend_get_book_views       (EBookBackend *backend);
void                e_book_backend_notify_update        (EBookBackend *backend,
                                                         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_writable      (EBookBackend *backend,
                                                         gboolean is_writable);
void                e_book_backend_notify_connection_status
                                                        (EBookBackend *backend,
                                                         gboolean is_online);
void                e_book_backend_notify_auth_required (EBookBackend *backend);
void                e_book_backend_sync                 (EBookBackend *backend);
void                e_book_backend_set_is_loaded        (EBookBackend *backend,
                                                         gboolean is_loaded);
void                e_book_backend_set_is_writable      (EBookBackend *backend,
                                                         gboolean is_writable);
void                e_book_backend_set_is_removed       (EBookBackend *backend,
                                                         gboolean is_removed);
GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_add_new
                                                        (const gchar *vcard);
GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_modify_new
                                                        (const gchar *vcard);
GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_delete_new
                                                        (const gchar *id);
struct              EBookBackendClass;

Object Hierarchy

  GObject
   +----EBookBackend
         +----EBookBackendSync

Signals

  "last-client-gone"                               : Run First

Description

Details

struct EBookBackend

struct EBookBackend;


e_book_backend_construct ()

gboolean            e_book_backend_construct            (EBookBackend *backend);

Does nothing.

backend :

an EBookBackend

Returns :

TRUE.

e_book_backend_load_source ()

GNOME_Evolution_Addressbook_CallStatus  e_book_backend_load_source
                                                        (EBookBackend *backend,
                                                         ESource *source,
                                                         gboolean only_if_exists);

Loads source into backend.

backend :

an EBookBackend

source :

an ESource to load

only_if_exists :

TRUE to prevent the creation of a new book

Returns :

A GNOME_Evolution_Addressbook_CallStatus indicating the outcome.

e_book_backend_get_source ()

ESource *           e_book_backend_get_source           (EBookBackend *backend);

Queries the source that an addressbook backend is serving.

backend :

An addressbook backend.

Returns :

ESource for the backend.

e_book_backend_add_client ()

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

Adds a client to an addressbook backend.

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.

backend :

an EBookBackend

book :

an EDataBook to remove

e_book_backend_has_out_of_proc_clients ()

gboolean            e_book_backend_has_out_of_proc_clients
                                                        (EBookBackend *backend);

Checks if backend has clients running in other system processes.

backend :

an EBookBackend

Returns :

TRUE if there are clients in other processes, FALSE otherwise.

e_book_backend_get_static_capabilities ()

gchar *             e_book_backend_get_static_capabilities
                                                        (EBookBackend *backend);

Gets the capabilities offered by this backend.

backend :

an EBookBackend

Returns :

A string listing the capabilities.

e_book_backend_is_loaded ()

gboolean            e_book_backend_is_loaded            (EBookBackend *backend);

Checks if backend's storage has been opened and the backend itself is ready for accessing.

backend :

an EBookBackend

Returns :

TRUE if loaded, FALSE otherwise.

e_book_backend_is_writable ()

gboolean            e_book_backend_is_writable          (EBookBackend *backend);

Checks if we can write to backend.

backend :

an EBookBackend

Returns :

TRUE if writeable, FALSE if not.

e_book_backend_is_removed ()

gboolean            e_book_backend_is_removed           (EBookBackend *backend);

Checks if backend has been removed from its physical storage.

backend :

an EBookBackend

Returns :

TRUE if backend has been removed, FALSE otherwise.

e_book_backend_open ()

void                e_book_backend_open                 (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         gboolean only_if_exists);

Executes an 'open' request specified by opid on book using backend.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this 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);

Executes a 'remove' request to remove all of backend's data, specified by opid on book.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this operation

e_book_backend_create_contact ()

void                e_book_backend_create_contact       (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         const gchar *vcard);

Executes a 'create contact' request specified by opid on book using backend.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this operation

vcard :

the VCard to add

e_book_backend_remove_contacts ()

void                e_book_backend_remove_contacts      (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         GList *id_list);

Executes a 'remove contacts' request specified by opid on book using backend.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this operation

id_list :

list of string IDs to remove

e_book_backend_modify_contact ()

void                e_book_backend_modify_contact       (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         const gchar *vcard);

Executes a 'modify contact' request specified by opid on book using backend.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this operation

vcard :

the VCard to update

e_book_backend_get_contact ()

void                e_book_backend_get_contact          (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         const gchar *id);

Executes a 'get contact' request specified by opid on book using backend.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this 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,
                                                         const gchar *query);

Executes a 'get contact list' request specified by opid on book using backend.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this operation

query :

the s-expression to match

e_book_backend_get_changes ()

void                e_book_backend_get_changes          (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         const gchar *change_id);

Executes a 'get changes' request specified by opid on book using backend.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this operation

change_id :

the ID of the changeset

e_book_backend_authenticate_user ()

void                e_book_backend_authenticate_user    (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid,
                                                         const gchar *user,
                                                         const gchar *passwd,
                                                         const gchar *auth_method);

Executes an 'authenticate' request specified by opid on book using backend.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this operation

user :

the name of the user account

passwd :

the user's password

auth_method :

the authentication method to use

e_book_backend_get_supported_fields ()

void                e_book_backend_get_supported_fields (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid);

Executes a 'get supported fields' request specified by opid on book using backend.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this operation

e_book_backend_get_required_fields ()

void                e_book_backend_get_required_fields  (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid);

Executes a 'get required fields' request specified by opid on book using backend.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this operation

e_book_backend_get_supported_auth_methods ()

void                e_book_backend_get_supported_auth_methods
                                                        (EBookBackend *backend,
                                                         EDataBook *book,
                                                         guint32 opid);

Executes a 'get supported auth methods' request specified by opid on book using backend.

backend :

an EBookBackend

book :

an EDataBook

opid :

the ID to use for this operation

e_book_backend_cancel_operation ()

GNOME_Evolution_Addressbook_CallStatus  e_book_backend_cancel_operation
                                                        (EBookBackend *backend,
                                                         EDataBook *book);

Cancel book's running operation on backend.

backend :

an EBookBackend

book :

an EDataBook whose operation should be cancelled

Returns :

A GNOME_Evolution_Addressbook_CallStatus indicating the outcome.

e_book_backend_set_mode ()

void                e_book_backend_set_mode             (EBookBackend *backend,
                                                         GNOME_Evolution_Addressbook_BookMode mode);

Sets backend's online/offline mode to mode. Mode can be 1 for offline or 2 indicating that it is connected and online.

backend :

an EBookbackend

mode :

a mode indicating the online/offline status of the backend

e_book_backend_start_book_view ()

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

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

backend :

an EBookBackend

view :


e_book_backend_stop_book_view ()

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

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

backend :

an EBookBackend

view :


e_book_backend_add_book_view ()

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

Adds view to backend for querying.

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.

backend :

an EBookBackend

view :

an EDataBookView

e_book_backend_get_book_views ()

EList *             e_book_backend_get_book_views       (EBookBackend *backend);

Gets the list of EDataBookView views running on this backend.

backend :

an EBookBackend

Returns :

An EList of EDataBookView objects.

e_book_backend_notify_update ()

void                e_book_backend_notify_update        (EBookBackend *backend,
                                                         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.

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.

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.

backend :

an EBookbackend

e_book_backend_notify_writable ()

void                e_book_backend_notify_writable      (EBookBackend *backend,
                                                         gboolean is_writable);

Notifies all backends clients about the current writable state.

backend :

an EBookBackend

is_writable :

flag indicating writable status

e_book_backend_notify_connection_status ()

void                e_book_backend_notify_connection_status
                                                        (EBookBackend *backend,
                                                         gboolean is_online);

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

backend :

an EBookBackend

is_online :

flag indicating whether backend is connected and online

e_book_backend_notify_auth_required ()

void                e_book_backend_notify_auth_required (EBookBackend *backend);

Notifies clients that backend requires authentication in order to connect. Means to be used by backend implementations.

backend :

an EBookBackend

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.

backend :

an EBookbackend

Since 1.12


e_book_backend_set_is_loaded ()

void                e_book_backend_set_is_loaded        (EBookBackend *backend,
                                                         gboolean is_loaded);

Sets the flag indicating whether backend is loaded to is_loaded. Meant to be used by backend implementations.

backend :

an EBookBackend

is_loaded :

A flag indicating whether the backend is loaded

e_book_backend_set_is_writable ()

void                e_book_backend_set_is_writable      (EBookBackend *backend,
                                                         gboolean is_writable);

Sets the flag indicating whether backend is writeable to is_writeable. Meant to be used by backend implementations.

backend :

an EBookBackend

is_writable :

A flag indicating whether the backend is writeable

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.

backend :

an EBookBackend

is_removed :

A flag indicating whether the backend's storage was removed

e_book_backend_change_add_new ()

GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_add_new
                                                        (const gchar *vcard);

Creates a new change item indicating vcard was added. Meant to be used by backend implementations.

vcard :

a VCard string

Returns :

A new GNOME_Evolution_Addressbook_BookChangeItem.

e_book_backend_change_modify_new ()

GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_modify_new
                                                        (const gchar *vcard);

Creates a new change item indicating vcard was modified. Meant to be used by backend implementations.

vcard :

a VCard string

Returns :

A new GNOME_Evolution_Addressbook_BookChangeItem.

e_book_backend_change_delete_new ()

GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_delete_new
                                                        (const gchar *id);

Creates a new change item indicating vcard was deleted. Meant to be used by backend implementations.

id :

Returns :

A new GNOME_Evolution_Addressbook_BookChangeItem.

struct EBookBackendClass

struct EBookBackendClass {
	GObjectClass parent_class;

	/* Virtual methods */
	GNOME_Evolution_Addressbook_CallStatus (*load_source) (EBookBackend *backend, ESource *source, gboolean only_if_exists);
	void (*remove) (EBookBackend *backend, EDataBook *book, guint32 opid);
        gchar *(*get_static_capabilities) (EBookBackend *backend);

	void (*create_contact)  (EBookBackend *backend, EDataBook *book, guint32 opid, const gchar *vcard);
	void (*remove_contacts) (EBookBackend *backend, EDataBook *book, guint32 opid, GList *id_list);
	void (*modify_contact)  (EBookBackend *backend, EDataBook *book, guint32 opid, const gchar *vcard);
	void (*get_contact) (EBookBackend *backend, EDataBook *book, guint32 opid, const gchar *id);
	void (*get_contact_list) (EBookBackend *backend, EDataBook *book, guint32 opid, const gchar *query);
	void (*start_book_view) (EBookBackend *backend, EDataBookView *book_view);
	void (*stop_book_view) (EBookBackend *backend, EDataBookView *book_view);
	void (*get_changes) (EBookBackend *backend, EDataBook *book, guint32 opid, const gchar *change_id);
	void (*authenticate_user) (EBookBackend *backend, EDataBook *book, guint32 opid, const gchar *user, const gchar *passwd, const gchar *auth_method);
	void (*get_required_fields) (EBookBackend *backend, EDataBook *bokk, guint32 opid);
	void (*get_supported_fields) (EBookBackend *backend, EDataBook *book, guint32 opid);
	void (*get_supported_auth_methods) (EBookBackend *backend, EDataBook *book, guint32 opid);
	GNOME_Evolution_Addressbook_CallStatus (*cancel_operation) (EBookBackend *backend, EDataBook *book);
	void (*set_mode) (EBookBackend *backend, GNOME_Evolution_Addressbook_BookMode mode);

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

	void (*sync) (EBookBackend *backend);

	/* Padding for future expansion */
	void (*_pas_reserved1) (void);
	void (*_pas_reserved2) (void);
	void (*_pas_reserved3) (void);
	void (*_pas_reserved4) (void);
};

Signal Details

The "last-client-gone" signal

void                user_function                      (EBookBackend *ebookbackend,
                                                        gpointer      user_data)         : Run First

ebookbackend :

the object which received the signal.

user_data :

user data set when the signal handler was connected.