EDataBookView: Evolution-Data-Server Reference Manual

## EDataBookView EDataBookView — A server side object for issuing view notifications |

## Functions

EDataBookView * | e_data_book_view_new ()
struct _EBookBackend * | e_data_book_view_ref_backend ()
struct _EBookBackend * | e_data_book_view_get_backend ()
GDBusConnection * | e_data_book_view_get_connection ()
const gchar * | e_data_book_view_get_object_path ()
EBookBackendSExp * | e_data_book_view_get_sexp ()
EBookClientViewFlags | e_data_book_view_get_flags ()
gboolean | e_data_book_view_get_force_initial_notifications ()
void | e_data_book_view_set_force_initial_notifications ()
gboolean | e_data_book_view_is_completed ()
void | e_data_book_view_notify_update ()
void | e_data_book_view_notify_update_vcard ()
void | e_data_book_view_notify_update_prefiltered_vcard ()
void | e_data_book_view_notify_remove ()
void | e_data_book_view_notify_complete ()
void | e_data_book_view_notify_progress ()
GHashTable * | e_data_book_view_get_fields_of_interest ()
gsize | e_data_book_view_get_id ()
void | e_data_book_view_set_sort_fields ()
guint | e_data_book_view_get_n_total ()
void | e_data_book_view_set_n_total ()
EBookIndices * | e_data_book_view_dup_indices ()
void | e_data_book_view_set_indices ()
GPtrArray * | e_data_book_view_dup_contacts ()
void | e_data_book_view_notify_content_changed ()
void | e_data_book_view_claim_contact_uid ()

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

#### Returns

value set by `e_data_book_view_set_force_initial_notifications()`

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