1 // Copyright (C) 2012 The Libphonenumber Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 // Author: Patrick Mezard 16 17 #ifndef I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_ 18 #define I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_ 19 20 #include <map> 21 #include <string> 22 23 #include <unicode/locid.h> // NOLINT(build/include_order) 24 25 #include "phonenumbers/base/basictypes.h" 26 #include "phonenumbers/base/memory/scoped_ptr.h" 27 28 namespace i18n { 29 namespace phonenumbers { 30 31 using std::map; 32 using std::string; 33 34 class AreaCodeMap; 35 class MappingFileProvider; 36 class PhoneNumber; 37 class PhoneNumberUtil; 38 struct CountryLanguages; 39 struct PrefixDescriptions; 40 typedef icu::Locale Locale; 41 42 // An offline geocoder which provides geographical information related to a 43 // phone number. 44 class PhoneNumberOfflineGeocoder { 45 private: 46 typedef map<string, const AreaCodeMap*> AreaCodeMaps; 47 48 public: 49 typedef const CountryLanguages* (*country_languages_getter)(int index); 50 typedef const PrefixDescriptions* (*prefix_descriptions_getter)(int index); 51 52 PhoneNumberOfflineGeocoder(); 53 54 // For tests 55 PhoneNumberOfflineGeocoder( 56 const int* country_calling_codes, 57 int country_calling_codes_size, 58 country_languages_getter get_country_languages, 59 const char** prefix_language_code_pairs, 60 int prefix_language_code_pairs_size, 61 prefix_descriptions_getter get_prefix_descriptions); 62 63 virtual ~PhoneNumberOfflineGeocoder(); 64 65 // Returns a text description for the given phone number, in the language 66 // provided. The description might consist of the name of the country where 67 // the phone number is from, or the name of the geographical area the phone 68 // number is from if more detailed information is available. Returns an empty 69 // string if the number could come from multiple countries, or the country 70 // code is in fact invalid. 71 // 72 // This method assumes the validity of the number passed in has already been 73 // checked, and that the number is suitable for geocoding. We consider 74 // fixed-line and mobile numbers possible candidates for geocoding. 75 string GetDescriptionForValidNumber(const PhoneNumber& number, 76 const Locale& language) const; 77 78 // As per GetDescriptionForValidNumber(PhoneNumber, Locale) but also considers 79 // the region of the user. If the phone number is from the same region as the 80 // user, only a lower-level description will be returned, if one exists. 81 // Otherwise, the phone number's region will be returned, with optionally some 82 // more detailed information. 83 // 84 // For example, for a user from the region "US" (United States), we would show 85 // "Mountain View, CA" for a particular number, omitting the United States 86 // from the description. For a user from the United Kingdom (region "GB"), for 87 // the same number we may show "Mountain View, CA, United States" or even just 88 // "United States". 89 // 90 // This method assumes the validity of the number passed in has already been 91 // checked, and that the number is suitable for geocoding. We consider 92 // fixed-line and mobile numbers possible candidates for geocoding. 93 // 94 // user_region is the region code for a given user. This region will be 95 // omitted from the description if the phone number comes from this region. It 96 // should be a two-letter uppercase CLDR region code. 97 string GetDescriptionForValidNumber(const PhoneNumber& number, 98 const Locale& language, const string& user_region) const; 99 100 // As per GetDescriptionForValidNumber(PhoneNumber, Locale) but explicitly 101 // checks the validity of the number passed in. 102 string GetDescriptionForNumber(const PhoneNumber& number, 103 const Locale& locale) const; 104 105 // As per GetDescriptionForValidNumber(PhoneNumber, Locale, String) but 106 // explicitly checks the validity of the number passed in. 107 string GetDescriptionForNumber(const PhoneNumber& number, 108 const Locale& language, const string& user_region) const; 109 110 private: 111 void Init(const int* country_calling_codes, 112 int country_calling_codes_size, 113 country_languages_getter get_country_languages, 114 const char** prefix_language_code_pairs, 115 int prefix_language_code_pairs_size, 116 prefix_descriptions_getter get_prefix_descriptions); 117 118 const AreaCodeMap* LoadAreaCodeMapFromFile( 119 const string& filename) const; 120 121 const AreaCodeMap* GetPhonePrefixDescriptions( 122 int prefix, const string& language, const string& script, 123 const string& region) const; 124 125 // Returns the customary display name in the given language for the given 126 // region. 127 string GetRegionDisplayName(const string* region_code, 128 const Locale& language) const; 129 130 // Returns the customary display name in the given language for the given 131 // territory the phone number is from. 132 string GetCountryNameForNumber(const PhoneNumber& number, 133 const Locale& language) const; 134 135 // Returns an area-level text description in the given language for the given 136 // phone number, or an empty string. 137 // lang is a two or three-letter lowercase ISO language code as defined by ISO 138 // 639. Note that where two different language codes exist (e.g. 'he' and 'iw' 139 // for Hebrew) we use the one that Java/Android canonicalized on ('iw' in this 140 // case). 141 // script is a four-letter titlecase (the first letter is uppercase and the 142 // rest of the letters are lowercase) ISO script code as defined in ISO 15924. 143 // region should be a two-letter uppercase ISO country code as defined by ISO 144 // 3166-1. 145 const char* GetAreaDescription(const PhoneNumber& number, const string& lang, 146 const string& script, 147 const string& region) const; 148 149 bool MayFallBackToEnglish(const string& lang) const; 150 151 private: 152 const PhoneNumberUtil* phone_util_; 153 // The MappingFileProvider knows for which combination of country calling code 154 // and language a phone prefix mapping file is available in the file system, 155 // so that a file can be loaded when needed. 156 scoped_ptr<const MappingFileProvider> provider_; 157 158 const char** prefix_language_code_pairs_; 159 int prefix_language_code_pairs_size_; 160 prefix_descriptions_getter get_prefix_descriptions_; 161 162 // A mapping from country calling codes languages pairs to the corresponding 163 // phone prefix map that has been loaded. 164 mutable AreaCodeMaps available_maps_; 165 166 DISALLOW_COPY_AND_ASSIGN(PhoneNumberOfflineGeocoder); 167 }; 168 169 } // namespace phonenumbers 170 } // namespace i18n 171 172 #endif /* I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_ */ 173