EBook.BookClient

g EBook.BookClient EBook.BookClient EDataServer.Client EDataServer.Client EDataServer.Client->EBook.BookClient GObject.GInterface GObject.GInterface Gio.AsyncInitable Gio.AsyncInitable GObject.GInterface->Gio.AsyncInitable Gio.Initable Gio.Initable GObject.GInterface->Gio.Initable GObject.Object GObject.Object GObject.Object->EDataServer.Client Gio.AsyncInitable->EBook.BookClient Gio.Initable->EBook.BookClient

Subclasses:

None

Methods

Inherited:

EDataServer.Client (47), GObject.Object (37), Gio.AsyncInitable (4), Gio.Initable (2)

Structs:

GObject.ObjectClass (5)

class

connect (source, wait_for_connected_seconds, cancellable, callback, *user_data)

class

connect_direct (source, wait_for_connected_seconds, cancellable, callback, *user_data)

class

connect_direct_finish (result)

class

connect_direct_sync (registry, source, wait_for_connected_seconds, cancellable)

class

connect_finish (result)

class

connect_sync (source, wait_for_connected_seconds, cancellable)

class

get_self (registry)

class

is_self (contact)

class

new (source)

add_contact (contact, opflags, cancellable, callback, *user_data)

add_contact_finish (result)

add_contact_sync (contact, opflags, cancellable)

add_contacts (contacts, opflags, cancellable, callback, *user_data)

add_contacts_finish (result)

add_contacts_sync (contacts, opflags, cancellable)

contains_email (email_address, cancellable, callback, *user_data)

contains_email_finish (result)

contains_email_sync (email_address, cancellable)

get_contact (uid, cancellable, callback, *user_data)

get_contact_finish (result)

get_contact_sync (uid, cancellable)

get_contacts (sexp, cancellable, callback, *user_data)

get_contacts_finish (result)

get_contacts_sync (sexp, cancellable)

get_contacts_uids (sexp, cancellable, callback, *user_data)

get_contacts_uids_finish (result)

get_contacts_uids_sync (sexp, cancellable)

get_cursor (sexp, sort_fields, sort_types, n_fields, cancellable, callback, *user_data)

get_cursor_finish (result)

get_cursor_sync (sexp, sort_fields, sort_types, n_fields, cancellable)

get_locale ()

get_view (sexp, cancellable, callback, *user_data)

get_view_finish (result)

get_view_sync (sexp, cancellable)

modify_contact (contact, opflags, cancellable, callback, *user_data)

modify_contact_finish (result)

modify_contact_sync (contact, opflags, cancellable)

modify_contacts (contacts, opflags, cancellable, callback, *user_data)

modify_contacts_finish (result)

modify_contacts_sync (contacts, opflags, cancellable)

remove_contact (contact, opflags, cancellable, callback, *user_data)

remove_contact_by_uid (uid, opflags, cancellable, callback, *user_data)

remove_contact_by_uid_finish (result)

remove_contact_by_uid_sync (uid, opflags, cancellable)

remove_contact_finish (result)

remove_contact_sync (contact, opflags, cancellable)

remove_contacts (uids, opflags, cancellable, callback, *user_data)

remove_contacts_finish (result)

remove_contacts_sync (uids, opflags, cancellable)

set_self (contact)

Virtual Methods

Inherited:

EDataServer.Client (24), GObject.Object (7), Gio.AsyncInitable (2), Gio.Initable (1)

Properties

Inherited:

EDataServer.Client (6)

Name

Type

Flags

Short Description

locale

str

r

The currently active locale for this addressbook

Signals

Inherited:

EDataServer.Client (4), GObject.Object (1)

Fields

Inherited:

EDataServer.Client (4), GObject.Object (1)

Name

Type

Access

Description

parent

EDataServer.Client

r

Class Details

class EBook.BookClient(**kwargs)
Bases:

EDataServer.Client, Gio.AsyncInitable, Gio.Initable

Abstract:

No

Structure:

EBook.BookClientClass

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

New in version 3.2.

classmethod connect(source, wait_for_connected_seconds, cancellable, callback, *user_data)
Parameters:

Asynchronously creates a new EBook.BookClient for source.

The wait_for_connected_seconds argument had been added since 3.16, to let the caller decide how long to wait for the backend to fully connect to its (possibly remote) data store. This is required due to a change in the authentication process, which is fully asynchronous and done on the client side, while not every client is supposed to response to authentication requests. In case the backend will not connect within the set interval, then it is opened in an offline mode. A special value -1 can be used to not wait for the connected state at all.

Unlike with EBook.BookClient.new(), there is no need to call EDataServer.Client.open() after obtaining the EBook.BookClient.

When the operation is finished, callback will be called. You can then call EBook.BookClient.connect_finish() to get the result of the operation.

New in version 3.8.

classmethod connect_direct(source, wait_for_connected_seconds, cancellable, callback, *user_data)
Parameters:

Like EBook.BookClient.connect(), except creates the book client for direct read access to the underlying addressbook.

When the operation is finished, callback will be called. You can then call EBook.BookClient.connect_direct_finish() to get the result of the operation.

New in version 3.12.

classmethod connect_direct_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

a new EBook.BookClient, or None on error

Return type:

EBook.BookClient

Finishes the operation started with EBook.BookClient.connect_direct(). If an error occurs in connecting to the D-Bus service, the function sets error and returns None.

For error handling convenience, any error message returned by this function will have a descriptive prefix that includes the display name of the EDataServer.Source passed to EBook.BookClient.connect_direct().

New in version 3.12.

classmethod connect_direct_sync(registry, source, wait_for_connected_seconds, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

a new but unopened EBook.BookClient or None on error.

Return type:

EBook.BookClient

Like EBook.BookClient.connect_sync(), except creates the book client for direct read access to the underlying addressbook.

New in version 3.8.

classmethod connect_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

a new EBook.BookClient, or None on error

Return type:

EBook.BookClient

Finishes the operation started with EBook.BookClient.connect(). If an error occurs in connecting to the D-Bus service, the function sets error and returns None.

For error handling convenience, any error message returned by this function will have a descriptive prefix that includes the display name of the EDataServer.Source passed to EBook.BookClient.connect().

New in version 3.8.

classmethod connect_sync(source, wait_for_connected_seconds, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

a new EBook.BookClient, or None on error

Return type:

EBook.BookClient

Creates a new EBook.BookClient for source. If an error occurs, the function will set error and return False.

Unlike with EBook.BookClient.new(), there is no need to call EDataServer.Client.open_sync() after obtaining the EBook.BookClient.

The wait_for_connected_seconds argument had been added since 3.16, to let the caller decide how long to wait for the backend to fully connect to its (possibly remote) data store. This is required due to a change in the authentication process, which is fully asynchronous and done on the client side, while not every client is supposed to response to authentication requests. In case the backend will not connect within the set interval, then it is opened in an offline mode. A special value -1 can be used to not wait for the connected state at all.

For error handling convenience, any error message returned by this function will have a descriptive prefix that includes the display name of source.

New in version 3.8.

classmethod get_self(registry)
Parameters:

registry (EDataServer.SourceRegistry) – an EDataServer.SourceRegistry

Raises:

GLib.Error

Returns:

True if successful, otherwise False.

out_contact:

an EBookContacts.Contact pointer to set

out_client:

an EBook.BookClient pointer to set

Return type:

(bool, out_contact: EBookContacts.Contact, out_client: EBook.BookClient)

Get the EBookContacts.Contact referring to the user of the address book and set it in out_contact and out_client.

New in version 3.2.

classmethod is_self(contact)
Parameters:

contact (EBookContacts.Contact) – an EBookContacts.Contact

Returns:

True if contact is the user, False otherwise.

Return type:

bool

Check if contact is the user of the address book.

New in version 3.2.

classmethod new(source)
Parameters:

source (EDataServer.Source) – An EDataServer.Source pointer

Raises:

GLib.Error

Returns:

a new but unopened EBook.BookClient.

Return type:

EBook.BookClient

Creates a new EBook.BookClient corresponding to the given source. There are only two operations that are valid on this book at this point: EDataServer.Client.open(), and EDataServer.Client.remove().

New in version 3.2.

Deprecated since version 3.8: It covertly makes synchronous D-Bus calls, with no way to cancel. Use EBook.BookClient.connect() instead, which combines EBook.BookClient.new() and EDataServer.Client.open() into one step.

add_contact(contact, opflags, cancellable, callback, *user_data)
Parameters:

Adds contact to self. The call is finished by EBook.BookClient.add_contact_finish() from the callback.

New in version 3.2.

add_contact_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_added_uid:

UID of a newly added contact; can be None

Return type:

(bool, out_added_uid: str)

Finishes previous call of EBook.BookClient.add_contact() and sets out_added_uid to a UID of a newly added contact. This string should be freed with GLib.free().

Note: This is not modifying original EBookContacts.Contact.

New in version 3.2.

add_contact_sync(contact, opflags, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_added_uid:

UID of a newly added contact; can be None

Return type:

(bool, out_added_uid: str)

Adds contact to self and sets out_added_uid to a UID of a newly added contact. This string should be freed with GLib.free().

Note: This is not modifying original contact, thus if it’s needed, then use EBookContacts.Contact.set (contact, EBookContacts.ContactField.UID, new_uid).

New in version 3.2.

add_contacts(contacts, opflags, cancellable, callback, *user_data)
Parameters:

Adds contacts to self. The call is finished by EBook.BookClient.add_contacts_finish() from the callback.

New in version 3.4.

add_contacts_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_added_uids:

UIDs of newly added contacts; can be None

Return type:

(bool, out_added_uids: [str])

Finishes previous call of EBook.BookClient.add_contacts() and sets out_added_uids to the UIDs of newly added contacts if successful. This GLib.SList should be freed with EDataServer.Client.util_free_string_slist().

If any of the contacts cannot be inserted, all of the insertions will be reverted and this method will return False.

Note: This is not modifying original EBookContacts.Contact objects.

New in version 3.4.

add_contacts_sync(contacts, opflags, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_added_uids:

UIDs of newly added contacts; can be None

Return type:

(bool, out_added_uids: [str])

Adds contacts to self and sets out_added_uids to the UIDs of newly added contacts if successful. This GLib.SList should be freed with EDataServer.Client.util_free_string_slist().

If any of the contacts cannot be inserted, all of the insertions will be reverted and this method will return False.

Note: This is not modifying original contacts, thus if it’s needed, then use EBookContacts.Contact.set (contact, EBookContacts.ContactField.UID, new_uid).

New in version 3.4.

contains_email(email_address, cancellable, callback, *user_data)
Parameters:

Asynchronously checks whether contains an email_address. When the email_address contains multiple addresses, then returns True when at least one address exists in the address book.

When the operation is finished, callback will be called. You can then call EBook.BookClient.contains_email_finish() to get the result of the operation.

New in version 3.44.

contains_email_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Finishes previous call of EBook.BookClient.contains_email().

New in version 3.44.

contains_email_sync(email_address, cancellable)
Parameters:
Raises:

GLib.Error

Return type:

bool

get_contact(uid, cancellable, callback, *user_data)
Parameters:

Receive EBookContacts.Contact from the self for the gived uid. The call is finished by EBook.BookClient.get_contact_finish() from the callback.

New in version 3.2.

get_contact_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_contact:

an EBookContacts.Contact for previously given uid

Return type:

(bool, out_contact: EBookContacts.Contact)

Finishes previous call of EBook.BookClient.get_contact(). If successful, then the out_contact is set to newly allocated EBookContacts.Contact, which should be freed with GObject.Object.unref().

New in version 3.2.

get_contact_sync(uid, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_contact:

an EBookContacts.Contact for given uid

Return type:

(bool, out_contact: EBookContacts.Contact)

Receive EBookContacts.Contact from the self for the gived uid. If successful, then the out_contact is set to newly allocated EBookContacts.Contact, which should be freed with GObject.Object.unref().

New in version 3.2.

get_contacts(sexp, cancellable, callback, *user_data)
Parameters:

Query self with sexp, receiving a list of contacts which matched. The call is finished by EBook.BookClient.get_contacts_finish() from the callback.

Note: sexp can be obtained through EBookContacts.BookQuery, by converting it to a string with EBookContacts.BookQuery.to_string().

New in version 3.2.

get_contacts_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_contacts:

a GLib.SList of matched EBookContacts.Contact(s)

Return type:

(bool, out_contacts: [EBookContacts.Contact])

Finishes previous call of EBook.BookClient.get_contacts(). If successful, then the out_contacts is set to newly allocated list of EBookContacts.Contact(s), which should be freed with EDataServer.Client.util_free_object_slist().

New in version 3.2.

get_contacts_sync(sexp, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_contacts:

a GLib.SList of matched EBookContacts.Contact(s)

Return type:

(bool, out_contacts: [EBookContacts.Contact])

Query self with sexp, receiving a list of contacts which matched. If successful, then the out_contacts is set to newly allocated GLib.SList of EBookContacts.Contact(s), which should be freed with EDataServer.Client.util_free_object_slist().

Note: sexp can be obtained through EBookContacts.BookQuery, by converting it to a string with EBookContacts.BookQuery.to_string().

New in version 3.2.

get_contacts_uids(sexp, cancellable, callback, *user_data)
Parameters:

Query self with sexp, receiving a list of contacts UIDs which matched. The call is finished by EBook.BookClient.get_contacts_uids_finish() from the callback.

Note: sexp can be obtained through EBookContacts.BookQuery, by converting it to a string with EBookContacts.BookQuery.to_string().

New in version 3.2.

get_contacts_uids_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_contact_uids:

a GLib.SList of matched contact UIDs stored as strings

Return type:

(bool, out_contact_uids: [str])

Finishes previous call of EBook.BookClient.get_contacts_uids(). If successful, then the out_contact_uids is set to newly allocated list of UID strings, which should be freed with EDataServer.Client.util_free_string_slist().

New in version 3.2.

get_contacts_uids_sync(sexp, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_contact_uids:

a GLib.SList of matched contacts UIDs stored as strings

Return type:

(bool, out_contact_uids: [str])

Query self with sexp, receiving a list of contacts UIDs which matched. If successful, then the out_contact_uids is set to newly allocated list of UID strings, which should be freed with EDataServer.Client.util_free_string_slist().

Note: sexp can be obtained through EBookContacts.BookQuery, by converting it to a string with EBookContacts.BookQuery.to_string().

New in version 3.2.

get_cursor(sexp, sort_fields, sort_types, n_fields, cancellable, callback, *user_data)
Parameters:

Create an EBook.BookClientCursor. The call is finished by EBook.BookClient.get_view_finish() from the callback.

Note: sexp can be obtained through EBookContacts.BookQuery, by converting it to a string with EBookContacts.BookQuery.to_string().

New in version 3.12.

get_cursor_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_cursor:

return location for an EBook.BookClientCursor

Return type:

(bool, out_cursor: EBook.BookClientCursor)

Finishes previous call of EBook.BookClient.get_cursor(). If successful, then the out_cursor is set to newly create EBook.BookClientCursor, the cursor should be freed with GObject.Object.unref() when no longer needed.

New in version 3.12.

get_cursor_sync(sexp, sort_fields, sort_types, n_fields, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_cursor:

return location for an EBook.BookClientCursor

Return type:

(bool, out_cursor: EBook.BookClientCursor)

Create an EBook.BookClientCursor. If successful, then the out_cursor is set to newly allocated EBook.BookClientCursor, the cursor should be freed with GObject.Object.unref() when no longer needed.

Note: sexp can be obtained through EBookContacts.BookQuery, by converting it to a string with EBookContacts.BookQuery.to_string().

New in version 3.12.

get_locale()
Returns:

The currently set locale for self

Return type:

str

Reports the locale in use for self. The addressbook might sort contacts in different orders, or store and compare phone numbers in different ways depending on the currently set locale.

Locales can change dynamically if systemd decides to change the locale, so it’s important to listen for notifications on the EBook.BookClient :locale property if you depend on sorted result lists. Ordered results should be reloaded after a locale change is detected.

New in version 3.12.

get_view(sexp, cancellable, callback, *user_data)
Parameters:

Query self with sexp, creating an EBook.BookClientView. The call is finished by EBook.BookClient.get_view_finish() from the callback.

Note: sexp can be obtained through EBookContacts.BookQuery, by converting it to a string with EBookContacts.BookQuery.to_string().

New in version 3.2.

get_view_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_view:

an EBook.BookClientView

Return type:

(bool, out_view: EBook.BookClientView)

Finishes previous call of EBook.BookClient.get_view(). If successful, then the out_view is set to newly allocated EBook.BookClientView, which should be freed with GObject.Object.unref().

New in version 3.2.

get_view_sync(sexp, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

out_view:

an EBook.BookClientView

Return type:

(bool, out_view: EBook.BookClientView)

Query self with sexp, creating an EBook.BookClientView. If successful, then the out_view is set to newly allocated EBook.BookClientView, which should be freed with GObject.Object.unref().

Note: sexp can be obtained through EBookContacts.BookQuery, by converting it to a string with EBookContacts.BookQuery.to_string().

New in version 3.2.

modify_contact(contact, opflags, cancellable, callback, *user_data)
Parameters:

Applies the changes made to contact to the stored version in self. The call is finished by EBook.BookClient.modify_contact_finish() from the callback.

New in version 3.2.

modify_contact_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Finishes previous call of EBook.BookClient.modify_contact().

New in version 3.2.

modify_contact_sync(contact, opflags, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Applies the changes made to contact to the stored version in self.

New in version 3.2.

modify_contacts(contacts, opflags, cancellable, callback, *user_data)
Parameters:

Applies the changes made to contacts to the stored versions in self. The call is finished by EBook.BookClient.modify_contacts_finish() from the callback.

New in version 3.4.

modify_contacts_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Finishes previous call of EBook.BookClient.modify_contacts().

New in version 3.4.

modify_contacts_sync(contacts, opflags, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Applies the changes made to contacts to the stored versions in self.

New in version 3.4.

remove_contact(contact, opflags, cancellable, callback, *user_data)
Parameters:

Removes contact from the self. The call is finished by EBook.BookClient.remove_contact_finish() from the callback.

New in version 3.2.

remove_contact_by_uid(uid, opflags, cancellable, callback, *user_data)
Parameters:

Removes contact with uid from the self. The call is finished by EBook.BookClient.remove_contact_by_uid_finish() from the callback.

New in version 3.2.

remove_contact_by_uid_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Finishes previous call of EBook.BookClient.remove_contact_by_uid().

New in version 3.2.

remove_contact_by_uid_sync(uid, opflags, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Removes contact with uid from the self.

New in version 3.2.

remove_contact_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Finishes previous call of EBook.BookClient.remove_contact().

New in version 3.2.

remove_contact_sync(contact, opflags, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Removes contact from the self.

New in version 3.2.

remove_contacts(uids, opflags, cancellable, callback, *user_data)
Parameters:

Removes the contacts with uids from the list uids from self. This is always more efficient than calling EBook.BookClient.remove_contact() if you have more than one uid to remove, as some backends can implement it as a batch request. The call is finished by EBook.BookClient.remove_contacts_finish() from the callback.

New in version 3.2.

remove_contacts_finish(result)
Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Finishes previous call of EBook.BookClient.remove_contacts().

New in version 3.2.

remove_contacts_sync(uids, opflags, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Removes the contacts with uids from the list uids from self. This is always more efficient than calling EBook.BookClient.remove_contact() if you have more than one uid to remove, as some backends can implement it as a batch request.

New in version 3.2.

set_self(contact)
Parameters:

contact (EBookContacts.Contact) – an EBookContacts.Contact

Raises:

GLib.Error

Returns:

True if successful, False otherwise.

Return type:

bool

Specify that contact residing in self is the EBookContacts.Contact that refers to the user of the address book.

New in version 3.2.

Property Details

EBook.BookClient.props.locale
Name:

locale

Type:

str

Default Value:

None

Flags:

READABLE

The currently active locale for this addressbook.

New in version 3.12.