e-phone-number

e-phone-number — Phone number support

Synopsis

#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);

Description

This modules provides utility functions for parsing and formatting phone numbers. Under the hood it uses Google's libphonenumber.

Details

EPhoneNumber

typedef struct _EPhoneNumber EPhoneNumber;

enum EPhoneNumberError

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.

E_PHONE_NUMBER_ERROR_NOT_IMPLEMENTED

the library was built without phone number support

E_PHONE_NUMBER_ERROR_UNKNOWN

the phone number parser reported an yet unkown error code.

E_PHONE_NUMBER_ERROR_NOT_A_NUMBER

the supplied text is not a phone number.

E_PHONE_NUMBER_ERROR_INVALID_COUNTRY_CODE

the supplied phone number has an invalid country code.

E_PHONE_NUMBER_ERROR_TOO_SHORT_AFTER_IDD

the remaining text after the country code is to short for a phone number.

E_PHONE_NUMBER_ERROR_TOO_SHORT

the text is too short for a phone number.

E_PHONE_NUMBER_ERROR_TOO_LONG

the text is too long for a phone number.

enum EPhoneNumberFormat

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.

E_PHONE_NUMBER_FORMAT_E164

format according E.164: "+493055667788".

E_PHONE_NUMBER_FORMAT_INTERNATIONAL

a formatted phone number always starting with the country calling code: "+49 30 55667788".

E_PHONE_NUMBER_FORMAT_NATIONAL

a formatted phone number in national scope, that is without country code: "(030) 55667788".

E_PHONE_NUMBER_FORMAT_RFC3966

a tel: URL according to RFC 3966: "tel:+49-30-55667788".

enum EPhoneNumberMatch

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

E_PHONE_NUMBER_MATCH_NONE

The phone numbers did not match.

E_PHONE_NUMBER_MATCH_EXACT

The phone numbers matched exactly.

E_PHONE_NUMBER_MATCH_NATIONAL

There was no country code for at least one of the numbers, but the national parts matched.

E_PHONE_NUMBER_MATCH_SHORT

There was no country code for at least one of the numbers, but one number might be part (suffix) of the other.

e_phone_number_is_supported ()

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.

e_phone_number_from_string ()

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.

phone_number :

the phone number to parse

region_code :

a 2-letter country code, or NULL. [allow-none]

error :

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


e_phone_number_to_string ()

gchar *             e_phone_number_to_string            (const EPhoneNumber *phone_number,
                                                         EPhoneNumberFormat format);

Describes the phone_number according to the rules applying to format.

phone_number :

the phone number to format

format :

the phone number format to apply

Returns :

A formatted string for phone_number. [transfer full]

Since 3.8


e_phone_number_compare ()

EPhoneNumberMatch   e_phone_number_compare              (const EPhoneNumber *first_number,
                                                         const EPhoneNumber *second_number);

Compares two phone numbers.

first_number :

the first EPhoneNumber to compare

second_number :

the second EPhoneNumber to compare

Returns :

The quality of matching for the two phone numbers.

Since 3.8


e_phone_number_compare_strings ()

EPhoneNumberMatch   e_phone_number_compare_strings      (const gchar *first_number,
                                                         const gchar *second_number,
                                                         GError **error);

Compares two phone numbers.

first_number :

the first EPhoneNumber to compare

second_number :

the second EPhoneNumber to compare

error :

a GError to set an error, if any. [out]

Returns :

The quality of matching for the two phone numbers.

Since 3.8


e_phone_number_copy ()

EPhoneNumber *      e_phone_number_copy                 (const EPhoneNumber *phone_number);

Makes a copy of phone_number.

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


e_phone_number_free ()

void                e_phone_number_free                 (EPhoneNumber *phone_number);

Released the memory occupied by phone_number.

phone_number :

the EPhoneNumber to free

Since 3.8