EBookClientView: Evolution-Data-Server Reference Manual

## EBookClientView EBookClientView — Receiving change notifications on addressbooks |

## Functions

struct _EBookClient * | e_book_client_view_ref_client ()
GDBusConnection * | e_book_client_view_get_connection ()
const gchar * | e_book_client_view_get_object_path ()
void | e_book_client_view_set_fields_of_interest ()
void | e_book_client_view_start ()
void | e_book_client_view_stop ()
void | e_book_client_view_set_flags ()
gboolean | e_book_client_view_set_sort_fields_sync ()
gsize | e_book_client_view_get_id ()
guint | e_book_client_view_get_n_total ()
EBookIndices * | e_book_client_view_dup_indices ()
void | e_book_client_view_dup_contacts ()
gboolean | e_book_client_view_dup_contacts_finish ()
struct _EBookClient * | e_book_client_view_get_client ()

## Properties

EBookClient * | client | Read / Write / Construct Only
GDBusConnection * | connection | Read / Write / Construct Only
EBookBackend * | direct-backend | Write / Construct Only
EBookIndices * | indices | Read
guint | n-total | Read
char * | object-path | Read / Write / Construct Only

## Signals

void | complete | Run Last
void | content-changed | Run Last
void | objects-added | Run Last
void | objects-modified | Run Last
void | objects-removed | Run Last
void | progress | Run Last

## Types and Values

struct | EBookClientView
struct | EBookClientViewClass

## Object Hierarchy

        GObject
        ╰── EBookClientView

## Implemented Interfaces

EBookClientView implements GInitable.

## Includes

    #include <libebook/libebook.h>

## Description

This class provides functionality for watching for changes on a given addressbook opened with an EBookClient. Use `e_book_client_get_view()` to create an EBookClientView.

## Functions

### e_book_client_view_ref_client ()

    struct _EBookClient *
    e_book_client_view_ref_client (EBookClientView *client_view);

Returns the “client” associated with `client_view` .

The returned EBookClient is referenced for thread-safety. Unreference the EBookClient with `g_object_unref()` when finished with it.

#### Parameters

client_view | an EBookClientView |

#### Returns

an EBookClient.

[transfer full][type EBookClient]

Since: 3.10

### e_book_client_view_get_connection ()

    GDBusConnection *
    e_book_client_view_get_connection (EBookClientView *client_view);

Returns the GDBusConnection used to create the D-Bus proxy.

#### Parameters

client_view | an EBookClientView |

#### Returns

the GDBusConnection.

[transfer none]

Since: 3.8

### e_book_client_view_get_object_path ()

    const gchar *
    e_book_client_view_get_object_path (EBookClientView *client_view);

Returns the object path used to create the D-Bus proxy.

#### Parameters

client_view | an EBookClientView |

#### Returns

the object path

Since: 3.8

### e_book_client_view_set_fields_of_interest ()

    void
    e_book_client_view_set_fields_of_interest
                                   (EBookClientView *client_view,
                                    const GSList *fields_of_interest,
                                    GError **error);

Client can instruct server to which fields it is interested in only, thus the server can return less data over the wire. The server can still return complete objects, this is just a hint to it that the listed fields will be used only. The UID field is returned always. Initial views has no fields of interest and using `NULL` for `fields_of_interest` will unset any previous changes.

Some backends can use summary information of its cache to create artifical objects, which will omit stored object parsing. If this cannot be done then it will simply return object as is stored in the cache.

#### Parameters

client_view | an EBookClientView |
fields_of_interest | List of field names in which the client is interested. | [element-type utf8]
error | return location for a GError, or `NULL` |

### e_book_client_view_start ()

    void
    e_book_client_view_start (EBookClientView *client_view,
                              GError **error);

Tells `client_view` to start processing events.

#### Parameters

client_view | an EBookClientView |
error | return location for a GError, or `NULL` |

### e_book_client_view_stop ()

    void
    e_book_client_view_stop (EBookClientView *client_view,
                             GError **error);

Tells `client_view` to stop processing events.

#### Parameters

client_view | an EBookClientView |
error | return location for a GError, or `NULL` |

### e_book_client_view_set_flags ()

    void
    e_book_client_view_set_flags (EBookClientView *client_view,
                                  EBookClientViewFlags flags,
                                  GError **error);

Sets the `flags` which control the behaviour of `client_view` .

#### Parameters

client_view | an EBookClientView |
flags | the EBookClientViewFlags for `client_view` |
error | return location for a GError, or `NULL` |

Since: 3.4

### e_book_client_view_set_sort_fields_sync ()

    gboolean
    e_book_client_view_set_sort_fields_sync
                                   (EBookClientView *self,
                                    const EBookClientViewSortFields *fields,
                                    GCancellable *cancellable,
                                    GError **error);

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

The array is terminated by an item with an `E_CONTACT_FIELD_LAST` field.

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

Note: This function can be used only with `E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY` .

#### Parameters

self | an EBookClientView |
fields | an array of EBookClientViewSortFields, terminated by item with `E_CONTACT_FIELD_LAST` field |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.50

### e_book_client_view_get_id ()

    gsize
    e_book_client_view_get_id (EBookClientView *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 EBookClientView |

#### Returns

an identifier of the view

Since: 3.50

### e_book_client_view_get_n_total ()

    guint
    e_book_client_view_get_n_total (EBookClientView *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 EBookClientView |

#### Returns

how many contacts are available in the view

Since: 3.50

### e_book_client_view_dup_indices ()

    EBookIndices *
    e_book_client_view_dup_indices (EBookClientView *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_book_client_view_set_sort_fields_sync()`. 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 EBookClientView |

#### Returns

list of indices for the view.

[transfer full]

Since: 3.50

### e_book_client_view_dup_contacts ()

    void
    e_book_client_view_dup_contacts (EBookClientView *self,
                                     guint range_start,
                                     guint range_length,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback cb,
                                     gpointer user_data);

Asynchronously reads `range_length` contacts from index `range_start` . When there are asked more than `e_book_client_view_get_n_total()` contacts only those up to the total number of contacts are read. Asking for out of range contacts results in an error.

Finish the call by `e_book_client_view_dup_contacts_finish()` from the `cb` .

Note: This function can be used only with `E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY` .

#### Parameters

self | an EBookClientView |
range_start | 0-based range start to retrieve the contacts for |
range_length | how many contacts to retrieve |
cancellable | optional GCancellable object, or `NULL` |
cb | a callback to call when the contacts are received. | [scope async][closure user_data]
user_data | user data for `cb` |

Since: 3.50

### e_book_client_view_dup_contacts_finish ()

    gboolean
    e_book_client_view_dup_contacts_finish
                                   (EBookClientView *self,
                                    GAsyncResult *result,
                                    guint *out_range_start,
                                    GPtrArray **out_contacts,
                                    GError **error);

Finishes previous call of `e_book_client_view_dup_contacts()`; see it for further information.

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 EBookClientView |
result | an asynchronous call result |
out_range_start | output location where to store original range start, or `NULL`. | [out][optional]
out_contacts | output location where to store array of the read contacts. | [out callee-allocates][transfer container][element-type EContact]
error | return location for a GError, or `NULL` |

#### Returns

whether succeeded; if not, the `error` is set

Since: 3.50

### e_book_client_view_get_client ()

    struct _EBookClient *
    e_book_client_view_get_client (EBookClientView *client_view);

`e_book_client_view_get_client` has been deprecated since version 3.10 and should not be used in newly-written code.

Use `e_book_client_view_ref_client()` instead.

Returns the “client” associated with `client_view` .

#### Parameters

client_view | an EBookClientView |

#### Returns

an EBookClient.

[transfer none][type EBookClient]

## Types and Values

### struct EBookClientView

    struct EBookClientView;

Since: 3.2

### struct EBookClientViewClass

    struct EBookClientViewClass {
    	/* Signals */
    	void		(*objects_added) (EBookClientView *client_view,
    						 const GSList *objects);
    	void		(*objects_modified) (EBookClientView *client_view,
    						 const GSList *objects);
    	void		(*objects_removed) (EBookClientView *client_view,
    						 const GSList *uids);
    	void		(*progress)		(EBookClientView *client_view,
    						 guint percent,
    						 const gchar *message);
    	void		(*complete)		(EBookClientView *client_view,
    						 const GError *error);
    };

Class structure for the EBookClient class.

#### Members

`objects_added` () | Signal emitted when contacts are added in the view |
`objects_modified` () | Signal emitted when contacts in the view are modified |
`objects_removed` () | Signal emitted when contacts are removed from the view |
`progress` () | Signal emitted intermittently while loading a view after calling `e_book_client_view_start()` |
`complete` () | Notification that loading a view has completed, after calling `e_book_client_view_start()` |

Since: 3.2

## Property Details

### The `“client”` property

      “client”                   EBookClient *

The EBookClient for the view

Owner: EBookClientView

Flags: Read / Write / Construct Only

### The `“connection”` property

      “connection”               GDBusConnection *

The GDBusConnection used to create the D-Bus proxy

Owner: EBookClientView

Flags: Read / Write / Construct Only

### The `“direct-backend”` property

      “direct-backend”           EBookBackend *

The EBookBackend to fetch contact data from, if direct read access is enabled

Owner: EBookClientView

Flags: Write / Construct Only

### The `“indices”` property

      “indices”                  EBookIndices *

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

Note: This property can be used only with `E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY` .

Owner: EBookClientView

Flags: Read

Since: 3.50

### The `“n-total”` property

      “n-total”                  guint

How many contacts are available in the view.

Note: This property can be used only with `E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY` .

Owner: EBookClientView

Flags: Read

Default value: 0

Since: 3.50

### The `“object-path”` property

      “object-path”              char *

The object path used to create the D-Bus proxy

Owner: EBookClientView

Flags: Read / Write / Construct Only

Default value: NULL

## Signal Details

### The `“complete”` signal

    void
    user_function (EBookClientView *ebookclientview,
                   GError          *arg1,
                   gpointer         user_data)

Flags: Run Last

### The `“content-changed”` signal

    void
    user_function (EBookClientView *client_view,
                   gpointer         user_data)

The signal is emitted whenever content of any contact in the `client_view` changes, or a contact is added or removed. It may or may not change `EBookClientView` :n-total property too.

Note: This signal can be used only with `E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY` .

#### Parameters

client_view | the EBookClientView which emitted the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.50

### The `“objects-added”` signal

    void
    user_function (EBookClientView *client_view,
                   gpointer         objects,
                   gpointer         user_data)

#### Parameters

client_view | the EBookClientView which emitted the signal |
objects | a GSList of added EContact objects into the `client_view` . | [type GSList][transfer none][element-type EContact]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“objects-modified”` signal

    void
    user_function (EBookClientView *client_view,
                   gpointer         objects,
                   gpointer         user_data)

#### Parameters

client_view | the EBookClientView which emitted the signal |
objects | a GSList of modified EContact objects within the `client_view` . | [type GSList][transfer none][element-type EContact]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“objects-removed”` signal

    void
    user_function (EBookClientView *client_view,
                   gpointer         uids,
                   gpointer         user_data)

#### Parameters

client_view | the EBookClientView which emitted the signal |
uids | a GSList of removed objects, described by their UID. | [type GSList][transfer none][element-type utf8]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“progress”` signal

    void
    user_function (EBookClientView *ebookclientview,
                   guint            arg1,
                   char            *arg2,
                   gpointer         user_data)

Flags: Run Last