![]() |
![]() |
![]() |
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