| Evolution-Data-Server Manual: Address Book Client (libebook) | ||||
|---|---|---|---|---|
| Top | Description | ||||
#include <libedataserver/libedataserver.h>
EPhoneNumber;
enum EPhoneNumberError;
enum EPhoneNumberFormat;
enum EPhoneNumberMatch;
gboolean e_phone_number_is_supported (void);
EPhoneNumber * e_phone_number_from_string (const gchar *phone_number,
const gchar *region_code,
GError **error);
gchar * e_phone_number_to_string (const EPhoneNumber *phone_number,
EPhoneNumberFormat format);
EPhoneNumberMatch e_phone_number_compare (const EPhoneNumber *first_number,
const EPhoneNumber *second_number);
EPhoneNumberMatch e_phone_number_compare_strings (const gchar *first_number,
const gchar *second_number,
GError **error);
EPhoneNumber * e_phone_number_copy (const EPhoneNumber *phone_number);
void e_phone_number_free (EPhoneNumber *phone_number);
This modules provides utility functions for parsing and formatting phone numbers. Under the hood it uses Google's libphonenumber.
typedef enum {
E_PHONE_NUMBER_ERROR_NOT_IMPLEMENTED,
E_PHONE_NUMBER_ERROR_UNKNOWN,
E_PHONE_NUMBER_ERROR_NOT_A_NUMBER,
E_PHONE_NUMBER_ERROR_INVALID_COUNTRY_CODE,
E_PHONE_NUMBER_ERROR_TOO_SHORT_AFTER_IDD,
E_PHONE_NUMBER_ERROR_TOO_SHORT,
E_PHONE_NUMBER_ERROR_TOO_LONG
} EPhoneNumberError;
Numeric description of a phone number related error.
| the library was built without phone number support | |
| the phone number parser reported an yet unkown error code. | |
| the supplied text is not a phone number. | |
| the supplied phone number has an invalid country code. | |
| the remaining text after the country code is to short for a phone number. | |
| the text is too short for a phone number. | |
| the text is too long for a phone number. |
typedef enum {
E_PHONE_NUMBER_FORMAT_E164,
E_PHONE_NUMBER_FORMAT_INTERNATIONAL,
E_PHONE_NUMBER_FORMAT_NATIONAL,
E_PHONE_NUMBER_FORMAT_RFC3966
} EPhoneNumberFormat;
The supported formatting rules for phone numbers.
| format according E.164: "+493055667788". | |
| a formatted phone number always starting with the country calling code: "+49 30 55667788". | |
| a formatted phone number in national scope, that is without country code: "(030) 55667788". | |
| a tel: URL according to RFC 3966: "tel:+49-30-55667788". |
typedef enum {
E_PHONE_NUMBER_MATCH_NONE,
E_PHONE_NUMBER_MATCH_EXACT,
E_PHONE_NUMBER_MATCH_NATIONAL = 1024,
E_PHONE_NUMBER_MATCH_SHORT = 2048
} EPhoneNumberMatch;
The quality of a phone number match.
Let's consider the phone number "+1-221-5423789", then comparing with "+1.221.542.3789" we have get E_PHONE_NUMBER_MATCH_EXACT because country code, region code and local number are matching. Comparing with "2215423789" will result in E_PHONE_NUMBER_MATCH_NATIONAL because the country code is missing, but the national portion is matching. Finally comparing with "5423789" gives E_PHONE_NUMBER_MATCH_SHORT. For more detail have a look at the following table:
| +1-617-5423789 | +1-221-5423789 | 221-5423789 | 5423789 | |
|---|---|---|---|---|
| +1-617-5423789 | exact | none | none | short |
| +1-221-5423789 | none | exact | national | short |
| 221-5423789 | none | national | national | short |
| 5423789 | short | short | short | short |
| The phone numbers did not match. | |
| The phone numbers matched exactly. | |
| There was no country code for at least one of the numbers, but the national parts matched. | |
| There was no country code for at least one of the numbers, but one number might be part (suffix) of the other. |
gboolean e_phone_number_is_supported (void);
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 mechnisms if needed.
Returns : |
TRUE if phone number support is available. |
EPhoneNumber * e_phone_number_from_string (const gchar *phone_number,const gchar *region_code,GError **error);
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 2-letter country code passed in region_code only is used if the
phone_number is not written in international format. The applications's
currently locale is consulted if NULL gets passed for region_code.
If the number is guaranteed to start with a '+' followed by the country
calling code, then "ZZ" can be passed here.
|
the phone number to parse |
|
a 2-letter country code, or NULL. [allow-none]
|
|
a GError to set an error, if any. [out] |
Returns : |
a new EPhoneNumber instance on success,
or NULL on error. Call e_phone_number_free() to release this instance. [transfer full]
|
Since 3.8
gchar * e_phone_number_to_string (const EPhoneNumber *phone_number,EPhoneNumberFormat format);
Describes the phone_number according to the rules applying to format.
|
the phone number to format |
|
the phone number format to apply |
Returns : |
A formatted string for phone_number. [transfer full]
|
Since 3.8
EPhoneNumberMatch e_phone_number_compare (const EPhoneNumber *first_number,const EPhoneNumber *second_number);
Compares two phone numbers.
|
the first EPhoneNumber to compare |
|
the second EPhoneNumber to compare |
Returns : |
The quality of matching for the two phone numbers. |
Since 3.8
EPhoneNumberMatch e_phone_number_compare_strings (const gchar *first_number,const gchar *second_number,GError **error);
Compares two phone numbers.
|
the first EPhoneNumber to compare |
|
the second EPhoneNumber to compare |
|
a GError to set an error, if any. [out] |
Returns : |
The quality of matching for the two phone numbers. |
Since 3.8
EPhoneNumber * e_phone_number_copy (const EPhoneNumber *phone_number);
Makes a copy of phone_number.
|
the EPhoneNumber to copy |
Returns : |
A newly allocated EPhoneNumber instance.
Call e_phone_number_free() to release this instance. [transfer full]
|
Since 3.8
void e_phone_number_free (EPhoneNumber *phone_number);
Released the memory occupied by phone_number.
|
the EPhoneNumber to free |
Since 3.8