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* GetPhonePrefixDescriptions(int prefix, 119 const string& language, const string& script, const string& region) const; 120 121 AreaCodeMaps::const_iterator LoadAreaCodeMapFromFile( 122 const string& filename) const; 123 124 // Returns the customary display name in the given language for the given 125 // region. 126 string GetRegionDisplayName(const string* region_code, 127 const Locale& language) const; 128 129 // Returns the customary display name in the given language for the given 130 // territory the phone number is from. 131 string GetCountryNameForNumber(const PhoneNumber& number, 132 const Locale& language) const; 133 134 // Returns an area-level text description in the given language for the given 135 // phone number, or an empty string. 136 // lang is a two or three-letter lowercase ISO language code as defined by ISO 137 // 639. Note that where two different language codes exist (e.g. 'he' and 'iw' 138 // for Hebrew) we use the one that Java/Android canonicalized on ('iw' in this 139 // case). 140 // script is a four-letter titlecase (the first letter is uppercase and the 141 // rest of the letters are lowercase) ISO script code as defined in ISO 15924. 142 // region should be a two-letter uppercase ISO country code as defined by ISO 143 // 3166-1. 144 const char* GetAreaDescription(const PhoneNumber& number, const string& lang, 145 const string& script, 146 const string& region) const; 147 148 bool MayFallBackToEnglish(const string& lang) const; 149 150 private: 151 const PhoneNumberUtil* phone_util_; 152 // The MappingFileProvider knows for which combination of country calling code 153 // and language a phone prefix mapping file is available in the file system, 154 // so that a file can be loaded when needed. 155 scoped_ptr<const MappingFileProvider> provider_; 156 157 const char** prefix_language_code_pairs_; 158 int prefix_language_code_pairs_size_; 159 prefix_descriptions_getter get_prefix_descriptions_; 160 161 // A mapping from country calling codes languages pairs to the corresponding 162 // phone prefix map that has been loaded. 163 mutable AreaCodeMaps available_maps_; 164 165 DISALLOW_COPY_AND_ASSIGN(PhoneNumberOfflineGeocoder); 166 }; 167 168 } // namespace phonenumbers 169 } // namespace i18n 170 171 #endif /* I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_ */ 172