1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */ 2 /* 3 * Copyright (C) 2012,2013 Intel Corporation 4 * 5 * This library is free software: you can redistribute it and/or modify it 6 * under the terms of the GNU Lesser General Public License as published by 7 * the Free Software Foundation. 8 * 9 * This library is distributed in the hope that it will be useful, but 10 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 11 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License 12 * for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public License 15 * along with this library. If not, see <http://www.gnu.org/licenses/>. 16 * 17 * Authors: Mathias Hasselmann <mathias@openismus.com> 18 */ 19 20 #if !defined (__LIBEBOOK_CONTACTS_H_INSIDE__) && !defined (LIBEBOOK_CONTACTS_COMPILATION) 21 #error "Only <libebook-contacts/libebook-contacts.h> should be included directly." 22 #endif 23 24 #ifndef E_PHONE_NUMBER_H 25 #define E_PHONE_NUMBER_H 26 27 /** 28 * SECTION: e-phone-number 29 * @include: libedataserver/libedataserver.h 30 * @short_description: Phone number support 31 * 32 * This modules provides utility functions for parsing and formatting 33 * phone numbers. Under the hood it uses Google's libphonenumber. 34 **/ 35 36 #include <glib-object.h> 37 38 G_BEGIN_DECLS 39 40 #define E_TYPE_PHONE_NUMBER (e_phone_number_get_type ()) 41 #define E_PHONE_NUMBER_ERROR (e_phone_number_error_quark ()) 42 43 /** 44 * EPhoneNumberFormat: 45 * @E_PHONE_NUMBER_FORMAT_E164: format according E.164: "+493055667788". 46 * @E_PHONE_NUMBER_FORMAT_INTERNATIONAL: a formatted phone number always 47 * starting with the country calling code: "+49 30 55667788". 48 * @E_PHONE_NUMBER_FORMAT_NATIONAL: a formatted phone number in national 49 * scope, that is without country calling code: "(030) 55667788". 50 * @E_PHONE_NUMBER_FORMAT_RFC3966: a tel: URL according to RFC 3966: 51 * "tel:+49-30-55667788". 52 * 53 * The supported formatting rules for phone numbers. 54 * 55 * Since: 3.8 56 **/ 57 typedef enum { 58 E_PHONE_NUMBER_FORMAT_E164, 59 E_PHONE_NUMBER_FORMAT_INTERNATIONAL, 60 E_PHONE_NUMBER_FORMAT_NATIONAL, 61 E_PHONE_NUMBER_FORMAT_RFC3966 62 } EPhoneNumberFormat; 63 64 /** 65 * EPhoneNumberMatch: 66 * @E_PHONE_NUMBER_MATCH_NONE: The phone numbers did not match. 67 * @E_PHONE_NUMBER_MATCH_EXACT: The phone numbers matched exactly. Two phone number strings are an exact match 68 * if the country code, national phone number, presence of a leading zero for Italian numbers and any 69 * extension present are the same. 70 * @E_PHONE_NUMBER_MATCH_NATIONAL: The national phone number matched. Two phone number strings match at 71 * this strength if either or both has no region specified, and the national phone number 72 * and extensions are the same. 73 * @E_PHONE_NUMBER_MATCH_SHORT: The weakest sort of match. Two phone numbers match at 74 * this strength if either or both has no region specified, or the region specified is the same, and one national 75 * phone number could be a shorter version of the other number. This includes the case where one has an extension specified, 76 * and the other does not. 77 * 78 * The strength of a phone number match. 79 * 80 * <example> 81 * <title>Some examples of phone number matches</title> 82 * <para> 83 * Let's consider the phone number "+1-221-5423789", then comparing with 84 * "+1.221.542.3789" we have get E_PHONE_NUMBER_MATCH_EXACT because country 85 * code, region code and local number are matching. Comparing with "2215423789" 86 * will result in E_PHONE_NUMBER_MATCH_NATIONAL because the country calling code 87 * is missing, but the national portion is matching. Finally comparing with 88 * "5423789" gives E_PHONE_NUMBER_MATCH_SHORT. For more detail have a look at 89 * the following table: 90 * 91 * <informaltable border="1" align="center"> 92 * <colgroup> 93 * <col width="20%" /> 94 * <col width="20%" /> 95 * <col width="20%" /> 96 * <col width="20%" /> 97 * <col width="20%" /> 98 * </colgroup> 99 * <tbody> 100 * <tr> 101 * <th></th> 102 * <th align="center">+1-617-5423789</th> 103 * <th align="center">+1-221-5423789</th> 104 * <th align="center">221-5423789</th> 105 * <th align="center">5423789</th> 106 * </tr><tr> 107 * <th align="right">+1-617-5423789</th> 108 * <td align="center">exact</td> 109 * <td align="center">none</td> 110 * <td align="center">none</td> 111 * <td align="center">short</td> 112 * </tr><tr> 113 * <th align="right">+1-221-5423789</th> 114 * <td align="center">none</td> 115 * <td align="center">exact</td> 116 * <td align="center">national</td> 117 * <td align="center">short</td> 118 * </tr><tr> 119 * <th align="right">221-5423789</th> 120 * <td align="center">none</td> 121 * <td align="center">national</td> 122 * <td align="center">national</td> 123 * <td align="center">short</td> 124 * </tr><tr> 125 * <th align="right">5423789</th> 126 * <td align="center">short</td> 127 * <td align="center">short</td> 128 * <td align="center">short</td> 129 * <td align="center">short</td> 130 * </tr> 131 * </tbody> 132 * </informaltable> 133 * </para> 134 * </example> 135 * 136 * Since: 3.8 137 **/ 138 typedef enum { 139 E_PHONE_NUMBER_MATCH_NONE, 140 E_PHONE_NUMBER_MATCH_EXACT, 141 E_PHONE_NUMBER_MATCH_NATIONAL = 1024, 142 E_PHONE_NUMBER_MATCH_SHORT = 2048 143 } EPhoneNumberMatch; 144 145 /** 146 * EPhoneNumberError: 147 * @E_PHONE_NUMBER_ERROR_NOT_IMPLEMENTED: the library was built without phone 148 * number support 149 * @E_PHONE_NUMBER_ERROR_UNKNOWN: the phone number parser reported a yet 150 * unknown error code. 151 * @E_PHONE_NUMBER_ERROR_INVALID_COUNTRY_CODE: the supplied phone number has an 152 * invalid country calling code. 153 * @E_PHONE_NUMBER_ERROR_NOT_A_NUMBER: the supplied text is not a phone number. 154 * @E_PHONE_NUMBER_ERROR_TOO_SHORT_AFTER_IDD: the remaining text after the 155 * country calling code is to short for a phone number. 156 * @E_PHONE_NUMBER_ERROR_TOO_SHORT: the text is too short for a phone number. 157 * @E_PHONE_NUMBER_ERROR_TOO_LONG: the text is too long for a phone number. 158 * 159 * Numeric description of a phone number related error. 160 * 161 * Since: 3.8 162 **/ 163 typedef enum { 164 E_PHONE_NUMBER_ERROR_NOT_IMPLEMENTED, 165 E_PHONE_NUMBER_ERROR_UNKNOWN, 166 E_PHONE_NUMBER_ERROR_NOT_A_NUMBER, 167 E_PHONE_NUMBER_ERROR_INVALID_COUNTRY_CODE, 168 E_PHONE_NUMBER_ERROR_TOO_SHORT_AFTER_IDD, 169 E_PHONE_NUMBER_ERROR_TOO_SHORT, 170 E_PHONE_NUMBER_ERROR_TOO_LONG 171 } EPhoneNumberError; 172 173 /** 174 * EPhoneNumberCountrySource: 175 * @E_PHONE_NUMBER_COUNTRY_FROM_FQTN: 176 * the EPhoneNumber was build from a fully qualified telephone number 177 * that contained a valid country calling code 178 * @E_PHONE_NUMBER_COUNTRY_FROM_IDD: 179 * the parsed phone number started with the current locale's international 180 * call prefix, followed by a valid country calling code 181 * @E_PHONE_NUMBER_COUNTRY_FROM_DEFAULT: 182 * the parsed phone didn't start with a (recognizable) country calling code, 183 * the code was chosen by checking the current locale settings 184 * 185 * The origin of a parsed EPhoneNumber's country calling code. 186 * 187 * Since: 3.8 188 **/ 189 typedef enum { 190 E_PHONE_NUMBER_COUNTRY_FROM_FQTN = 1, 191 E_PHONE_NUMBER_COUNTRY_FROM_IDD = 5, 192 E_PHONE_NUMBER_COUNTRY_FROM_DEFAULT = 20 193 } EPhoneNumberCountrySource; 194 195 /** 196 * EPhoneNumber: 197 * 198 * This opaque type describes a parsed phone number. It can be copied using 199 * e_phone_number_copy(). To release it call e_phone_number_free(). 200 * 201 * Since: 3.8 202 **/ 203 typedef struct _EPhoneNumber EPhoneNumber; 204 205 GType e_phone_number_get_type (void); 206 GQuark e_phone_number_error_quark (void); 207 208 gboolean e_phone_number_is_supported (void) G_GNUC_CONST; 209 gint e_phone_number_get_country_code_for_region 210 (const gchar *region_code, 211 GError **error); 212 gchar * e_phone_number_get_default_region 213 (GError **error); 214 215 EPhoneNumber * e_phone_number_from_string (const gchar *phone_number, 216 const gchar *region_code, 217 GError **error); 218 gchar * e_phone_number_to_string (const EPhoneNumber *phone_number, 219 EPhoneNumberFormat format); 220 gint e_phone_number_get_country_code (const EPhoneNumber *phone_number, 221 EPhoneNumberCountrySource *source); 222 gchar * e_phone_number_get_national_number 223 (const EPhoneNumber *phone_number); 224 225 EPhoneNumberMatch e_phone_number_compare (const EPhoneNumber *first_number, 226 const EPhoneNumber *second_number); 227 EPhoneNumberMatch e_phone_number_compare_strings (const gchar *first_number, 228 const gchar *second_number, 229 GError **error); 230 EPhoneNumberMatch e_phone_number_compare_strings_with_region 231 (const gchar *first_number, 232 const gchar *second_number, 233 const gchar *region_code, 234 GError **error); 235 236 EPhoneNumber * e_phone_number_copy (const EPhoneNumber *phone_number); 237 void e_phone_number_free (EPhoneNumber *phone_number); 238 239 G_END_DECLS 240 241 #endif /* E_PHONE_NUMBER_H */ 242