Functions

  address_western_parse (in_address)
  book_client_error_create (code, custom_msg)
  book_client_error_quark ()
  book_client_error_to_string (code)
  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_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) – a string representing a mailing address
Returns:A new EBookContacts.AddressWestern structure, or None if the parsing failed.
Return type:EBookContacts.AddressWestern

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_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) – a 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_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.