EBookClientView

EBookClientView — Recieving change notifications on addressbooks

Functions

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

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

gboolean
e_book_client_view_is_running (EBookClientView *client_view);

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]

user_data

user data for cb .

[closure 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;

Contains only private data the should be read and manipulated using the functions below.

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