1 // Copyright (C) 2012 The Libphonenumber Authors
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
7 // http://www.apache.org/licenses/LICENSE-2.0
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.
15 // Author: Patrick Mezard
17 #ifndef I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_
18 #define I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_
23 #include <unicode/locid.h> // NOLINT(build/include_order)
25 #include "phonenumbers/base/basictypes.h"
26 #include "phonenumbers/base/memory/scoped_ptr.h"
29 namespace phonenumbers {
35 class MappingFileProvider;
37 class PhoneNumberUtil;
38 struct CountryLanguages;
39 struct PrefixDescriptions;
40 typedef icu::Locale Locale;
42 // An offline geocoder which provides geographical information related to a
44 class PhoneNumberOfflineGeocoder {
46 typedef map<string, const AreaCodeMap*> AreaCodeMaps;
49 typedef const CountryLanguages* (*country_languages_getter)(int index);
50 typedef const PrefixDescriptions* (*prefix_descriptions_getter)(int index);
52 PhoneNumberOfflineGeocoder();
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);
63 virtual ~PhoneNumberOfflineGeocoder();
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.
70 // This method assumes the validity of the number passed in has already been
72 string GetDescriptionForValidNumber(const PhoneNumber& number,
73 const Locale& language) const;
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.
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
87 // This method assumes the validity of the number passed in has already been
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;
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;
101 // As per GetDescriptionForValidNumber(PhoneNumber, Locale, String) but
102 string GetDescriptionForNumber(const PhoneNumber& number,
103 const Locale& language, const string& user_region) const;
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);
113 const AreaCodeMap* GetPhonePrefixDescriptions(int prefix,
114 const string& language, const string& script, const string& region) const;
116 AreaCodeMaps::const_iterator LoadAreaCodeMapFromFile(
117 const string& filename) const;
119 // Returns the customary display name in the given language for the given
121 string GetRegionDisplayName(const string* region_code,
122 const Locale& language) const;
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;
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
135 // region is a two-letter uppercase ISO country codes as defined by ISO
137 const char* GetAreaDescription(const PhoneNumber& number, const string& lang,
138 const string& script,
139 const string& region) const;
141 bool MayFallBackToEnglish(const string& lang) const;
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_;
150 const char** prefix_language_code_pairs_;
151 int prefix_language_code_pairs_size_;
152 prefix_descriptions_getter get_prefix_descriptions_;
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_;
158 DISALLOW_COPY_AND_ASSIGN(PhoneNumberOfflineGeocoder);
161 } // namespace phonenumbers
164 #endif /* I18N_PHONENUMBERS_GEOCODING_PHONENUMBER_OFFLINE_GEOCODER_H_ */