## EPhoneNumber EPhoneNumber — Phone number support |

## Synopsis

    #include <libedataserver/libedataserver.h>

    #define             E_PHONE_NUMBER_ERROR
    enum                EPhoneNumberFormat;
    enum                EPhoneNumberMatch;
    enum                EPhoneNumberError;
    enum                EPhoneNumberCountrySource;
                        EPhoneNumber;
    GQuark              e_phone_number_error_quark          (void);
    gboolean            e_phone_number_is_supported         (void);
    gint                e_phone_number_get_country_code_for_region
                                                            (const gchar *region_code,
                                                             GError **error);
    gchar *             e_phone_number_get_default_region   (GError **error);
    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);
    gint                e_phone_number_get_country_code     (const EPhoneNumber *phone_number,
                                                             EPhoneNumberCountrySource *source);
    gchar *             e_phone_number_get_national_number  (const EPhoneNumber *phone_number);
    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);
    EPhoneNumberMatch   e_phone_number_compare_strings_with_region
                                                            (const gchar *first_number,
                                                             const gchar *second_number,
                                                             const gchar *region_code,
                                                             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

### E_PHONE_NUMBER_ERROR

    #define E_PHONE_NUMBER_ERROR (e_phone_number_error_quark ())

### 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 calling code: "(030) 55667788".
`E_PHONE_NUMBER_FORMAT_RFC3966` | a tel: URL according to RFC 3966: "tel:+49-30-55667788".

Since 3.8

### 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 strength of a phone number match.

Example 3. Some examples of phone number matches

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 calling 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. Two phone number strings are an exact match if the country code, national phone number, presence of a leading zero for Italian numbers and any extension present are the same.
`E_PHONE_NUMBER_MATCH_NATIONAL` | The national phone number matched. Two phone number strings match at this strength if either or both has no region specified, and the national phone number and extensions are the same.
`E_PHONE_NUMBER_MATCH_SHORT` | The weakest sort of match. Two phone numbers match at this strength if either or both has no region specified, or the region specified is the same, and one national phone number could be a shorter version of the other number. This includes the case where one has an extension specified, and the other does not.

Since 3.8

### 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 calling code.
`E_PHONE_NUMBER_ERROR_TOO_SHORT_AFTER_IDD` | the remaining text after the country calling 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.

Since 3.8

### enum EPhoneNumberCountrySource

    typedef enum {
    	E_PHONE_NUMBER_COUNTRY_FROM_FQTN = 1,
    	E_PHONE_NUMBER_COUNTRY_FROM_IDD = 5,
    	E_PHONE_NUMBER_COUNTRY_FROM_DEFAULT = 20
    } EPhoneNumberCountrySource;

The origin of a parsed EPhoneNumber's country calling code.

`E_PHONE_NUMBER_COUNTRY_FROM_FQTN` | the EPhoneNumber was build from a fully qualified telephone number that contained a valid country calling code
`E_PHONE_NUMBER_COUNTRY_FROM_IDD` | the parsed phone number started with the current locale's international call prefix, followed by a valid country calling code
`E_PHONE_NUMBER_COUNTRY_FROM_DEFAULT` | the parsed phone didn't start with a (recognizable) country calling code, the code was chosen by checking the current locale settings

Since 3.8

### EPhoneNumber

    typedef struct _EPhoneNumber EPhoneNumber;

This opaque type describes a parsed phone number. It can be copied using `e_phone_number_copy()`. To release it call `e_phone_number_free()`.

Since 3.8

### e_phone_number_error_quark ()

    GQuark              e_phone_number_error_quark          (void);

### 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.

Since 3.8

### e_phone_number_get_country_code_for_region ()

    gint                e_phone_number_get_country_code_for_region
                                                            (const gchar *region_code,
                                                             GError **error);

Retrieves the preferred country calling code for `region_code`, e.g. 358 for "fi" or 1 for "en_US`UTF`-8".

If `NULL` is passed for `region_code` the default region as returned by `e_phone_number_get_default_region()` is used.

`region_code` : | a two-letter country code, a locale name, or `NULL`. [allow-none]
`error` : | a GError to set an error, if any. [out]
Returns : | a valid country calling code, or zero if an unknown region code was passed.

Since 3.8

### e_phone_number_get_default_region ()

    gchar *             e_phone_number_get_default_region   (GError **error);

Retrieves the current two-letter country code that's used by default for parsing phone numbers in `e_phone_number_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.

`error` : | a GError to set an error, if any. [out]
Returns : | a newly allocated string containing the current locale's two-letter code for phone number parsing. [transfer full]

Since 3.8

### 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 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 `e_phone_number_get_default_region()` is used if `region_code` is `NULL`.

If the number is guaranteed to start with a '+' followed by the country calling code, then "ZZ" can be passed for `region_code`.

`phone_number` : | the phone number to parse
`region_code` : | a two-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_get_country_code ()

    gint                e_phone_number_get_country_code     (const EPhoneNumber *phone_number,
                                                             EPhoneNumberCountrySource *source);

Queries the `phone_number`'s country calling code and optionally stores the country calling code's origin in `source`. For instance when parsing "+1-617-5423789" this function would return one and assing E_PHONE_NUMBER_COUNTRY_FROM_FQTN to `source`.

`phone_number` : | the phone number to query
`source` : | an optional location for storing the phone number's origin, or `NULL`
Returns : | A valid country calling code, or zero if no code is known.

Since 3.8

### e_phone_number_get_national_number ()

    gchar *             e_phone_number_get_national_number  (const EPhoneNumber *phone_number);

Queries the national portion of `phone_number` without any call-out prefixes. For instance when parsing "+1-617-5423789" this function would return the string "6175423789".

`phone_number` : | the phone number to query
Returns : | The national portion of `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_compare_strings_with_region ()

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

Compares two phone numbers within the context of `region_code`.

`first_number` : | the first EPhoneNumber to compare
`second_number` : | the second EPhoneNumber to compare
`region_code` : | a two-letter country code, or `NULL`. [allow-none]
`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