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