EDataBookView

EDataBookView — A server side object for issuing view notifications

Functions

Object Hierarchy

    GObject
    ╰── EDataBookView

Includes

#include <libedata-book/libedata-book.h>

Description

This class communicates with EBookClientViews over the bus.

Addressbook backends can automatically own a number of views requested by the client, this API can be used by the backend to issue notifications which will be delivered to the EBookClientView

Functions

e_data_book_view_new ()

EDataBookView *
e_data_book_view_new (struct _EBookBackend *backend,
                      EBookBackendSExp *sexp,
                      GDBusConnection *connection,
                      const gchar *object_path,
                      GError **error);

Creates a new EDataBookView and exports its D-Bus interface on connection at object_path . If an error occurs while exporting, the function sets error and returns NULL.

Parameters

backend

an EBookBackend.

[type EBookBackend]

sexp

an EBookBackendSExp

 

connection

a GDBusConnection

 

object_path

an object path for the view

 

error

return location for a GError, or NULL

 

Returns

an EDataBookView or NULL on error


e_data_book_view_ref_backend ()

struct _EBookBackend *
e_data_book_view_ref_backend (EDataBookView *view);

Refs the backend that view is querying. Unref the returned backend, if not NULL, with g_object_unref(), when no longer needed.

Parameters

view

an EDataBookView

 

Returns

The associated EBookBackend.

[type EBookBackend][transfer full][nullable]

Since: 3.34


e_data_book_view_get_backend ()

struct _EBookBackend *
e_data_book_view_get_backend (EDataBookView *view);

e_data_book_view_get_backend has been deprecated since version 3.34 and should not be used in newly-written code.

Use e_data_book_view_ref_backend() instead.

Gets the backend that view is querying.

Parameters

view

an EDataBookView

 

Returns

The associated EBookBackend.

[type EBookBackend][transfer none]


e_data_book_view_get_connection ()

GDBusConnection *
e_data_book_view_get_connection (EDataBookView *view);

Returns the GDBusConnection on which the AddressBookView D-Bus interface is exported.

Parameters

view

an EDataBookView

 

Returns

the GDBusConnection.

[transfer none]

Since: 3.8


e_data_book_view_get_object_path ()

const gchar *
e_data_book_view_get_object_path (EDataBookView *view);

Returns the object path at which the AddressBookView D-Bus interface is exported.

Parameters

view

an EDataBookView

 

Returns

the object path

Since: 3.8


e_data_book_view_get_sexp ()

EBookBackendSExp *
e_data_book_view_get_sexp (EDataBookView *view);

Gets the s-expression used for matching contacts to view .

Parameters

view

an EDataBookView

 

Returns

The EBookBackendSExp used.

[transfer none]

Since: 3.8


e_data_book_view_get_flags ()

EBookClientViewFlags
e_data_book_view_get_flags (EDataBookView *view);

Gets the EBookClientViewFlags that control the behaviour of view .

Parameters

view

an EDataBookView

 

Returns

the flags for view .

Since: 3.4


e_data_book_view_get_force_initial_notifications ()

gboolean
e_data_book_view_get_force_initial_notifications
                               (EDataBookView *view);

Returns whether the view should do initial notifications even when the flags do not contain E_BOOK_CLIENT_VIEW_FLAGS_NOTIFY_INITIAL. The default is FALSE.

Parameters

view

an EDataBookView

 

Since: 3.50


e_data_book_view_set_force_initial_notifications ()

void
e_data_book_view_set_force_initial_notifications
                               (EDataBookView *view,
                                gboolean value);

Sets whether the view should do initial notifications even when the flags do not contain E_BOOK_CLIENT_VIEW_FLAGS_NOTIFY_INITIAL.

Parameters

view

an EDataBookView

 

value

value to set

 

Since: 3.50


e_data_book_view_is_completed ()

gboolean
e_data_book_view_is_completed (EDataBookView *view);

Parameters

view

an EDataBookView

 

Returns

whether the view had been completed; that is, whether e_data_book_view_notify_complete() had been called since the view had been started.

Since: 3.34


e_data_book_view_notify_update ()

void
e_data_book_view_notify_update (EDataBookView *view,
                                const EContact *contact);

Notify listeners that contact has changed. This can trigger an add, change or removal event depending on whether the change causes the contact to start matching, no longer match, or stay matching the query specified by view .

Parameters

view

an EDataBookView

 

contact

an EContact

 

e_data_book_view_notify_update_vcard ()

void
e_data_book_view_notify_update_vcard (EDataBookView *view,
                                      const gchar *id,
                                      const gchar *vcard);

Notify listeners that vcard has changed. This can trigger an add, change or removal event depending on whether the change causes the contact to start matching, no longer match, or stay matching the query specified by view . This method should be preferred over e_data_book_view_notify_update() when the native representation of a contact is a vCard.

Parameters

view

an EDataBookView

 

id

a unique id of the vcard

 

vcard

a plain vCard

 

e_data_book_view_notify_update_prefiltered_vcard ()

void
e_data_book_view_notify_update_prefiltered_vcard
                               (EDataBookView *view,
                                const gchar *id,
                                const gchar *vcard);

Notify listeners that vcard has changed. This can trigger an add, change or removal event depending on whether the change causes the contact to start matching, no longer match, or stay matching the query specified by view . This method should be preferred over e_data_book_view_notify_update() when the native representation of a contact is a vCard.

The important difference between this method and e_data_book_view_notify_update() and e_data_book_view_notify_update_vcard() is that it doesn't match the contact against the book view query to see if it should be included, it assumes that this has been done and the contact is known to exist in the view.

Parameters

view

an EDataBookView

 

id

the UID of this contact

 

vcard

a plain vCard

 

e_data_book_view_notify_remove ()

void
e_data_book_view_notify_remove (EDataBookView *view,
                                const gchar *id);

Notify listeners that a contact specified by id was removed from view .

Parameters

view

an EDataBookView

 

id

a unique contact ID

 

e_data_book_view_notify_complete ()

void
e_data_book_view_notify_complete (EDataBookView *view,
                                  const GError *error);

Notifies listeners that all pending updates on view have been sent. The listener's information should now be in sync with the backend's.

Parameters

view

an EDataBookView

 

error

the error of the query, if any

 

e_data_book_view_notify_progress ()

void
e_data_book_view_notify_progress (EDataBookView *view,
                                  guint percent,
                                  const gchar *message);

Provides listeners with a human-readable text describing the current backend operation. This can be used for progress reporting.

Parameters

view

an EDataBookView

 

percent

percent done; use -1 when not available

 

message

a text message

 

Since: 3.2


e_data_book_view_get_fields_of_interest ()

GHashTable *
e_data_book_view_get_fields_of_interest
                               (EDataBookView *view);

Parameters

view

an EDataBookView

 

Returns

Hash table of field names which the listener is interested in. Backends can return fully populated objects, but the listener advertised that it will use only these. Returns NULL for all available fields.

Note: The data pointer in the hash table has no special meaning, it's only GINT_TO_POINTER(1) for easier checking. Also, field names are compared case insensitively.

[transfer none][element-type utf8 gint][nullable]


e_data_book_view_get_id ()

gsize
e_data_book_view_get_id (EDataBookView *self);

Returns an identifier of the self . It does not change for the whole life time of the self .

Note: This function can be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY .

Parameters

self

an EDataBookView

 

Returns

an identifier of the view

Since: 3.50


e_data_book_view_set_sort_fields ()

void
e_data_book_view_set_sort_fields (EDataBookView *self,
                                  const EBookClientViewSortFields *fields);

Sets fields to sort the view by. The default is to sort by the file-as field. The contacts are always sorted in ascending order. Not every field can be used for sorting, the default available fields are E_CONTACT_FILE_AS, E_CONTACT_GIVEN_NAME and E_CONTACT_FAMILY_NAME.

The first sort field is used to populate indices, as returned by e_data_book_view_dup_indices().

Note: This function can be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY .

Parameters

self

an EDataBookView

 

fields

an array of EBookClientViewSortFields fields to sort by

 

Since: 3.50


e_data_book_view_get_n_total ()

guint
e_data_book_view_get_n_total (EDataBookView *self);

Returns how many contacts are available in the view.

Note: This function can be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY .

Parameters

self

an EDataBookView

 

Returns

how many contacts are available in the view

Since: 3.50


e_data_book_view_set_n_total ()

void
e_data_book_view_set_n_total (EDataBookView *self,
                              guint n_total);

Sets how many contacts are available in the view.

Note: This function can be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY .

Parameters

self

an EDataBookView

 

n_total

a value to set

 

Since: 3.50


e_data_book_view_dup_indices ()

EBookIndices *
e_data_book_view_dup_indices (EDataBookView *self);

Returns a list of EBookIndices holding indices of the contacts in the view. These are received from the first sort field set by e_data_book_view_set_sort_fields(). The last item of the returned array is the one with chr member being NULL.

Free the returned array with e_book_indices_free(), when no longer needed.

Note: This function can be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY .

Parameters

self

an EDataBookView

 

Returns

list of indices for the view, or NULL when cannot determine.

[transfer full][nullable]

Since: 3.50


e_data_book_view_set_indices ()

void
e_data_book_view_set_indices (EDataBookView *self,
                              const EBookIndices *indices);

Sets indices used by the self . The array is terminated by an item with chr member being NULL. See e_data_book_view_dup_indices() for more information.

Note: This function can be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY .

Parameters

self

an EDataBookView

 

indices

an array of EBookIndices

 

Since: 3.50


e_data_book_view_dup_contacts ()

GPtrArray *
e_data_book_view_dup_contacts (EDataBookView *self,
                               guint range_start,
                               guint range_length);

Reads range_length contacts from index range_start . When there are asked more than e_data_book_view_get_n_total() contacts only those up to the total number of contacts are read.

Free the returned GPtrArray with g_ptr_array_unref(), when no longer needed.

Note: This function can be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY .

Parameters

self

an EDataBookView

 

range_start

0-based range start to retrieve the contacts for

 

range_length

how many contacts to retrieve

 

Returns

array of the read contacts, or NULL, when not applicable or when the range_start it out of bounds.

[transfer container][element-type EContact][nullable]

Since: 3.50


e_data_book_view_notify_content_changed ()

void
e_data_book_view_notify_content_changed
                               (EDataBookView *self);

Notifies the client side that the content of the self changed, which it should use to refresh the view data.

Note: This function can be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY .

Parameters

self

an EDataBookView

 

Since: 3.50


e_data_book_view_claim_contact_uid ()

void
e_data_book_view_claim_contact_uid (EDataBookView *self,
                                    const gchar *uid);

Tells the self , that it contains a contact with UID uid . This is useful for "manual query" view, which do not do initial notifications. It helps to not send "objects-added" signal for contacts, which are already part of the self , because for them the "objects-modified" should be emitted instead.

Parameters

self

an EDataBookView

 

uid

a contact UID

 

Since: 3.50