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   // This type is neither copyable nor movable.
64   PhoneNumberOfflineGeocoder(const PhoneNumberOfflineGeocoder&) = delete;
65   PhoneNumberOfflineGeocoder& operator=(const PhoneNumberOfflineGeocoder&) =
66       delete;
67 
68   virtual ~PhoneNumberOfflineGeocoder();
69 
70   // Returns a text description for the given phone number, in the language
71   // provided. The description might consist of the name of the country where
72   // the phone number is from, or the name of the geographical area the phone
73   // number is from if more detailed information is available. Returns an empty
74   // string if the number could come from multiple countries, or the country
75   // code is in fact invalid.
76   //
77   // This method assumes the validity of the number passed in has already been
78   // checked, and that the number is suitable for geocoding. We consider
79   // fixed-line and mobile numbers possible candidates for geocoding.
80   string GetDescriptionForValidNumber(const PhoneNumber& number,
81                                       const Locale& language) const;
82 
83   // As per GetDescriptionForValidNumber(PhoneNumber, Locale) but also considers
84   // the region of the user. If the phone number is from the same region as the
85   // user, only a lower-level description will be returned, if one exists.
86   // Otherwise, the phone number's region will be returned, with optionally some
87   // more detailed information.
88   //
89   // For example, for a user from the region "US" (United States), we would show
90   // "Mountain View, CA" for a particular number, omitting the United States
91   // from the description. For a user from the United Kingdom (region "GB"), for
92   // the same number we may show "Mountain View, CA, United States" or even just
93   // "United States".
94   //
95   // This method assumes the validity of the number passed in has already been
96   // checked, and that the number is suitable for geocoding. We consider
97   // fixed-line and mobile numbers possible candidates for geocoding.
98   //
99   // user_region is the region code for a given user. This region will be
100   // omitted from the description if the phone number comes from this region. It
101   // should be a two-letter uppercase CLDR region code.
102   string GetDescriptionForValidNumber(const PhoneNumber& number,
103       const Locale& language, const string& user_region) const;
104 
105   // As per GetDescriptionForValidNumber(PhoneNumber, Locale) but explicitly
106   // checks the validity of the number passed in.
107   string GetDescriptionForNumber(const PhoneNumber& number,
108                                  const Locale& locale) const;
109 
110   // As per GetDescriptionForValidNumber(PhoneNumber, Locale, String) but
111   // explicitly checks the validity of the number passed in.
112   string GetDescriptionForNumber(const PhoneNumber& number,
113       const Locale& language, const string& user_region) const;
114 
115  private:
116   void Init(const int* country_calling_codes,
117             int country_calling_codes_size,
118             country_languages_getter get_country_languages,
119             const char** prefix_language_code_pairs,
120             int prefix_language_code_pairs_size,
121             prefix_descriptions_getter get_prefix_descriptions);
122 
123   const AreaCodeMap* LoadAreaCodeMapFromFile(
124       const string& filename) const;
125 
126   const AreaCodeMap* GetPhonePrefixDescriptions(
127       int prefix, const string& language, const string& script,
128       const string& region) const;
129 
130   // Returns the customary display name in the given language for the given
131   // region.
132   string GetRegionDisplayName(const string* region_code,
133                               const Locale& language) const;
134 
135   // Returns the customary display name in the given language for the given
136   // territory the phone number is from.
137   string GetCountryNameForNumber(const PhoneNumber& number,
138                                  const Locale& language) const;
139 
140   // Returns an area-level text description in the given language for the given
141   // phone number, or an empty string.
142   // lang is a two or three-letter lowercase ISO language code as defined by ISO
143   // 639. Note that where two different language codes exist (e.g. 'he' and 'iw'
144   // for Hebrew) we use the one that Java/Android canonicalized on ('iw' in this
145   // case).
146   // script is a four-letter titlecase (the first letter is uppercase and the
147   // rest of the letters are lowercase) ISO script code as defined in ISO 15924.
148   // region should be a two-letter uppercase ISO country code as defined by ISO
149   // 3166-1.
150   const char* GetAreaDescription(const PhoneNumber& number, const string& lang,
151                                  const string& script,
152                                  const string& region) const;
153 
154   bool MayFallBackToEnglish(const string& lang) const;
155 
156  private:
157   const PhoneNumberUtil* phone_util_;
158   // The MappingFileProvider knows for which combination of country calling code
159   // and language a phone prefix mapping file is available in the file system,
160   // so that a file can be loaded when needed.
161   scoped_ptr<const MappingFileProvider> provider_;
162 
163   const char** prefix_language_code_pairs_;
164   int prefix_language_code_pairs_size_;
165   prefix_descriptions_getter get_prefix_descriptions_;
166 
167   // A mapping from country calling codes languages pairs to the corresponding
168   // phone prefix map that has been loaded.
169   mutable AreaCodeMaps available_maps_;
170 };
171 
172 }  // namespace phonenumbers
173 }  // namespace i18n
174 
175 #endif /* I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_ */
176