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:

code (EBookContacts.BookClientError) – an EBookContacts.BookClientError code to create
custom_msg (str) – custom message to use for the error; can be None

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:	nqs (`int`) – the number of queries to AND qs (`EBookContacts.BookQuery`) – pointer to an array of `EBookContacts.BookQuery` items unref (`bool`) – if `True`, the new query takes ownership of the existing queries
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:	field (`EBookContacts.ContactField`) – an `EBookContacts.ContactField` to test test (`EBookContacts.BookQueryTest`) – the test to apply value (`str`) – the value to test for
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:	nqs (`int`) – the number of queries to OR qs (`EBookContacts.BookQuery`) – pointer to an array of `EBookContacts.BookQuery` items unref (`bool`) – if `True`, the new query takes ownership of the existing queries
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:	field (`str`) – a `EBookContacts.VCard` field name to test test (`EBookContacts.BookQueryTest`) – the test to apply value (`str`) – the value to test for
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:	first_number (`str`) – the first `EBookContacts.PhoneNumber` to compare second_number (`str`) – the second `EBookContacts.PhoneNumber` to compare
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:	first_number (`str`) – the first `EBookContacts.PhoneNumber` to compare second_number (`str`) – the second `EBookContacts.PhoneNumber` to compare region_code (`str` or `None`) – a two-letter country code, or `None`
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.