Functions

address_western_parse (in_address)

book_client_error_create (code, custom_msg)

book_client_error_quark ()

book_client_error_to_string (code)

book_indices_get_ascending_sort (self)

book_indices_set_ascending_sort (self, ascending_sort)

book_query_and (nqs, qs, unref)

book_query_any_field_contains (value)

book_query_field_exists (field)

book_query_field_test (field, test, value)

book_query_from_string (query_string)

book_query_or (nqs, qs, unref)

book_query_vcard_field_exists (field)

book_query_vcard_field_test (field, test, value)

book_util_conflict_resolution_to_operation_flags (conflict_resolution)

book_util_diff_categories (old_contact, new_contact)

book_util_foreach_address (email_address, func, *user_data)

book_util_operation_flags_to_conflict_resolution (flags)

contact_attr_list_copy (list)

contact_attr_list_free (list)

contact_date_from_string (str)

contact_name_from_string (name_str)

name_western_parse (full_name)

phone_number_compare_strings (first_number, second_number)

phone_number_compare_strings_with_region (first_number, second_number, region_code)

phone_number_error_quark ()

phone_number_from_string (phone_number, region_code)

phone_number_get_country_code_for_region (region_code)

phone_number_get_default_region ()

phone_number_is_supported ()

Details

EBookContacts.address_western_parse(in_address)
Parameters:

in_address (str or None) – a string representing a mailing address

Returns:

A new EBookContacts.AddressWestern structure, or None if the parsing failed or when the in_address was None.

Return type:

EBookContacts.AddressWestern or None

Parses a string representing a mailing address into a structure of type EBookContacts.AddressWestern.

EBookContacts.book_client_error_create(code, custom_msg)
Parameters:
Returns:

a new GLib.Error containing an E_BOOK_CLIENT_ERROR of the given code. If the custom_msg is None, then the error message is the one returned from EBookContacts.book_client_error_to_string() for the code, otherwise the given message is used.

Returned pointer should be freed with GLib.Error.free().

Return type:

GLib.Error

New in version 3.2.

EBookContacts.book_client_error_quark()
Return type:

int

EBookContacts.book_client_error_to_string(code)
Parameters:

code (EBookContacts.BookClientError) – an EBookContacts.BookClientError code

Returns:

Localized human readable description of the given error code

Return type:

str

Get localized human readable description of the given error code.

New in version 3.2.

EBookContacts.book_indices_get_ascending_sort(self)
Parameters:

self (EBookContacts.BookIndicesUpdater) – an EBookContacts.BookIndicesUpdater

Returns:

True, when considers contacts sorted in ascending order, False when in the descending order.

Return type:

bool

Returns whether the self considers contacts stored in the ascending order.

New in version 3.50.

EBookContacts.book_indices_set_ascending_sort(self, ascending_sort)
Parameters:

Sets whether the contacts are sorted in an ascending order; if not, then they are sorted in the descending order. That influences what indexes the indices have set.

New in version 3.50.

EBookContacts.book_query_and(nqs, qs, unref)
Parameters:
Returns:

A new EBookContacts.BookQuery

Return type:

EBookContacts.BookQuery

Create a new EBookContacts.BookQuery which is the logical AND of the queries in #qs.

EBookContacts.book_query_any_field_contains(value)
Parameters:

value (str) – a value

Returns:

the new EBookContacts.BookQuery

Return type:

EBookContacts.BookQuery

Creates a new EBookContacts.BookQuery which tests if any field contains value.

EBookContacts.book_query_field_exists(field)
Parameters:

field (EBookContacts.ContactField) – an EBookContacts.ContactField

Returns:

the new EBookContacts.BookQuery

Return type:

EBookContacts.BookQuery

Creates a new EBookContacts.BookQuery which tests if the field field exists.

EBookContacts.book_query_field_test(field, test, value)
Parameters:
Returns:

the new EBookContacts.BookQuery

Return type:

EBookContacts.BookQuery

Creates a new EBookContacts.BookQuery which tests field for value using the test test.

EBookContacts.book_query_from_string(query_string)
Parameters:

query_string (str) – the query

Returns:

the new EBookContacts.BookQuery.

Return type:

EBookContacts.BookQuery

Parse query_string and return a new EBookContacts.BookQuery representing it.

EBookContacts.book_query_or(nqs, qs, unref)
Parameters:
Returns:

A new EBookContacts.BookQuery

Return type:

EBookContacts.BookQuery

Creates a new EBookContacts.BookQuery which is the logical OR of the queries in #qs.

EBookContacts.book_query_vcard_field_exists(field)
Parameters:

field (str) – a field name

Returns:

the new EBookContacts.BookQuery

Return type:

EBookContacts.BookQuery

Creates a new EBookContacts.BookQuery which tests if the field field exists. field should be a vCard field name, such as EBookContacts.EVC_FN or EBookContacts.EVC_X_MSN.

EBookContacts.book_query_vcard_field_test(field, test, value)
Parameters:
Returns:

the new EBookContacts.BookQuery

Return type:

EBookContacts.BookQuery

Creates a new EBookContacts.BookQuery which tests field for value using the test test.

New in version 2.22.

EBookContacts.book_util_conflict_resolution_to_operation_flags(conflict_resolution)
Parameters:

conflict_resolution (EDataServer.ConflictResolution) – an EDataServer.ConflictResolution

Returns:

a bit-or of EBookContacts.BookOperationFlags, corresponding to the conflict_resolution

Return type:

int

Encodes the EDataServer.ConflictResolution into the bit-or of EBookContacts.BookOperationFlags. The returned value can be bit-or-ed with other EBookContacts.BookOperationFlags values.

New in version 3.34.

EBookContacts.book_util_diff_categories(old_contact, new_contact)
Parameters:
Returns:

out_added:

a GLib.HashTable with added categories

out_removed:

a GLib.HashTable with removed categories

Return type:

(out_added: {str: int}, out_removed: {str: int})

Compares list of categories on the old_contact with the list of categories on the new_contact and fills out_added categories and out_removed categories accordingly, as if the old_contact is replaced with the new_contact. When either of the contacts is None, it’s considered as having no categories set. Rather than returning empty GLib.HashTable, the return argument is set to None when there are no added/removed categories.

The key of the hash table is the category string, the value is an integer (1). There is used the hash table only for speed.

The returned GLib.HashTable-s should be freed with GLib.HashTable.unref(), when no longer needed.

New in version 3.48.

EBookContacts.book_util_foreach_address(email_address, func, *user_data)
Parameters:

  • email_address (str) – one or more email addresses as string

  • func (GLib.HRFunc) – a function to call for each email user_data (closure Camel.func): user data passed to func

  • user_data (object or None) –

Parses the email_address and calls func for each found address. The first parameter of the func is the name, the second parameter of the func is the email, the third parameters of the func is the user_data. The func returns True, to continue processing.

New in version 3.44.

EBookContacts.book_util_operation_flags_to_conflict_resolution(flags)
Parameters:

flags (int) – bit-or of EBookContacts.BookOperationFlags

Returns:

an EDataServer.ConflictResolution as stored in the flags

Return type:

EDataServer.ConflictResolution

Decodes the EDataServer.ConflictResolution from the bit-or of EBookContacts.BookOperationFlags.

New in version 3.34.

EBookContacts.contact_attr_list_copy(list)
Parameters:

list ([str]) – A GLib.List of strings

Returns:

A copy of list

Return type:

[str]

Copies a list of allocated strings, specifically for the #EContactAttrList boxed type used for multi valued contact fields.

New in version 3.8.

EBookContacts.contact_attr_list_free(list)
Parameters:

list ([str]) – A GLib.List of strings

Frees a list of allocated strings, specifically for the #EContactAttrList boxed type used for multi valued contact fields.

New in version 3.8.

EBookContacts.contact_date_from_string(str)
Parameters:

str (str) – a date string in the format YYYY-MM-DD or YYYYMMDD

Returns:

A new EBookContacts.ContactDate struct.

Return type:

EBookContacts.ContactDate

Creates a new EBookContacts.ContactDate based on str.

EBookContacts.contact_name_from_string(name_str)
Parameters:

name_str (str) – a string representing a contact’s full name

Returns:

A new EBookContacts.ContactName struct.

Return type:

EBookContacts.ContactName

Creates a new EBookContacts.ContactName based on the parsed name_str.

EBookContacts.name_western_parse(full_name)
Parameters:

full_name (str) – A string containing a western name.

Returns:

A new EBookContacts.NameWestern struct.

Return type:

EBookContacts.NameWestern

Parses full_name and returns an EBookContacts.NameWestern struct filled with the component parts of the name.

EBookContacts.phone_number_compare_strings(first_number, second_number)
Parameters:
Raises:

GLib.Error

Returns:

The quality of matching for the two phone numbers.

Return type:

EBookContacts.PhoneNumberMatch

Compares two phone numbers.

New in version 3.8.

EBookContacts.phone_number_compare_strings_with_region(first_number, second_number, region_code)
Parameters:
Raises:

GLib.Error

Returns:

The quality of matching for the two phone numbers.

Return type:

EBookContacts.PhoneNumberMatch

Compares two phone numbers within the context of region_code.

New in version 3.8.

EBookContacts.phone_number_error_quark()
Return type:

int

EBookContacts.phone_number_from_string(phone_number, region_code)
Parameters:

  • phone_number (str) – the phone number to parse

  • region_code (str or None) – a two-letter country code, or None

Raises:

GLib.Error

Returns:

a new EBookContacts.PhoneNumber instance on success, or None on error. Call EBookContacts.PhoneNumber.free() to release this instance.

Return type:

EBookContacts.PhoneNumber

Parses the string passed in phone_number. Note that no validation is performed whether the recognized phone number is valid for a particular region.

The two-letter country code passed in region_code only is used if the phone_number is not written in international format. The application’s default region as returned by EBookContacts.PhoneNumber.get_default_region() is used if region_code is None.

If the number is guaranteed to start with a ‘+’ followed by the country calling code, then “ZZ” can be passed for region_code.

New in version 3.8.

EBookContacts.phone_number_get_country_code_for_region(region_code)
Parameters:

region_code (str or None) – a two-letter country code, a locale name, or None

Raises:

GLib.Error

Returns:

a valid country calling code, or zero if an unknown region code was passed.

Return type:

int

Retrieves the preferred country calling code for region_code, e.g. 358 for “fi” or 1 for “en_USUTF-8”.

If None is passed for region_code the default region as returned by EBookContacts.PhoneNumber.get_default_region() is used.

New in version 3.8.

EBookContacts.phone_number_get_default_region()
Raises:

GLib.Error

Returns:

a newly allocated string containing the current locale’s two-letter code for phone number parsing.

Return type:

str

Retrieves the current two-letter country code that’s used by default for parsing phone numbers in EBookContacts.PhoneNumber.from_string(). It can be useful to store this number before parsing a bigger number of phone numbers.

The result of this functions depends on the current setup of the %LC_ADDRESS category: If that category provides a reasonable value for %_NL_ADDRESS_COUNTRY_AB2 this value is returned. Otherwise the locale name configured for %LC_ADDRESS is parsed.

New in version 3.8.

EBookContacts.phone_number_is_supported()
Returns:

True if phone number support is available.

Return type:

bool

Checks if phone number support is available. It is recommended to call this function before using any of the phone-utils functions to ensure that the required functionality is available, and to pick alternative mechanisms if needed.

New in version 3.8.