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 28namespace i18n { 29namespace phonenumbers { 30 31using std::map; 32using std::string; 33 34class AreaCodeMap; 35class MappingFileProvider; 36class PhoneNumber; 37class PhoneNumberUtil; 38struct CountryLanguages; 39struct PrefixDescriptions; 40typedef icu::Locale Locale; 41 42// An offline geocoder which provides geographical information related to a 43// phone number. 44class 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. 69 // 70 // This method assumes the validity of the number passed in has already been 71 // checked. 72 string GetDescriptionForValidNumber(const PhoneNumber& number, 73 const Locale& language) const; 74 75 // As per GetDescriptionForValidNumber(PhoneNumber, Locale) but also considers 76 // the region of the user. If the phone number is from the same region as the 77 // user, only a lower-level description will be returned, if one exists. 78 // Otherwise, the phone number's region will be returned, with optionally some 79 // more detailed information. 80 // 81 // For example, for a user from the region "US" (United States), we would show 82 // "Mountain View, CA" for a particular number, omitting the United States 83 // from the description. For a user from the United Kingdom (region "GB"), for 84 // the same number we may show "Mountain View, CA, United States" or even just 85 // "United States". 86 // 87 // This method assumes the validity of the number passed in has already been 88 // checked. 89 // 90 // user_region is the region code for a given user. This region will be 91 // omitted from the description if the phone number comes from this region. It 92 // is a two-letter uppercase ISO country code as defined by ISO 3166-1. 93 string GetDescriptionForValidNumber(const PhoneNumber& number, 94 const Locale& language, const string& user_region) const; 95 96 // As per GetDescriptionForValidNumber(PhoneNumber, Locale) but explicitly 97 // checks the validity of the number passed in. 98 string GetDescriptionForNumber(const PhoneNumber& number, 99 const Locale& locale) const; 100 101 // As per GetDescriptionForValidNumber(PhoneNumber, Locale, String) but 102 string GetDescriptionForNumber(const PhoneNumber& number, 103 const Locale& language, const string& user_region) const; 104 105 private: 106 void Init(const int* country_calling_codes, 107 int country_calling_codes_size, 108 country_languages_getter get_country_languages, 109 const char** prefix_language_code_pairs, 110 int prefix_language_code_pairs_size, 111 prefix_descriptions_getter get_prefix_descriptions); 112 113 const AreaCodeMap* GetPhonePrefixDescriptions(int prefix, 114 const string& language, const string& script, const string& region) const; 115 116 AreaCodeMaps::const_iterator LoadAreaCodeMapFromFile( 117 const string& filename) const; 118 119 // Returns the customary display name in the given language for the given 120 // region. 121 string GetRegionDisplayName(const string* region_code, 122 const Locale& language) const; 123 124 // Returns the customary display name in the given language for the given 125 // territory the phone number is from. 126 string GetCountryNameForNumber(const PhoneNumber& number, 127 const Locale& language) const; 128 129 // Returns an area-level text description in the given language for the given 130 // phone number, or an empty string. 131 // lang is a two-letter lowercase ISO language codes as defined by ISO 639-1. 132 // script is a four-letter titlecase (the first letter is uppercase and the 133 // rest of the letters are lowercase) ISO script codes as defined in ISO 134 // 15924. 135 // region is a two-letter uppercase ISO country codes as defined by ISO 136 // 3166-1. 137 const char* GetAreaDescription(const PhoneNumber& number, const string& lang, 138 const string& script, 139 const string& region) const; 140 141 bool MayFallBackToEnglish(const string& lang) const; 142 143 private: 144 const PhoneNumberUtil* phone_util_; 145 // The MappingFileProvider knows for which combination of country calling code 146 // and language a phone prefix mapping file is available in the file system, 147 // so that a file can be loaded when needed. 148 scoped_ptr<const MappingFileProvider> provider_; 149 150 const char** prefix_language_code_pairs_; 151 int prefix_language_code_pairs_size_; 152 prefix_descriptions_getter get_prefix_descriptions_; 153 154 // A mapping from country calling codes languages pairs to the corresponding 155 // phone prefix map that has been loaded. 156 mutable AreaCodeMaps available_maps_; 157 158 DISALLOW_COPY_AND_ASSIGN(PhoneNumberOfflineGeocoder); 159}; 160 161} // namespace phonenumbers 162} // namespace i18n 163 164#endif /* I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_ */ 165