cpp/src/phonenumbers/shortnumberinfo.h

   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 // Library for obtaining information about international short phone numbers,
  16 // such as short codes and emergency numbers. Note most commercial short
  17 // numbers are not handled here, but by the phonenumberutil.
  18
  19 #ifndef I18N_PHONENUMBERS_SHORTNUMBERINFO_H_
  20 #define I18N_PHONENUMBERS_SHORTNUMBERINFO_H_
  21
  22 #include <list>
  23 #include <map>
  24 #include <set>
  25 #include <string>
  26
  27 #include "phonenumbers/base/basictypes.h"
  28 #include "phonenumbers/base/memory/scoped_ptr.h"
  29
  30 namespace i18n {
  31 namespace phonenumbers {
  32
  33 using std::list;
  34 using std::map;
  35 using std::set;
  36 using std::string;
  37
  38 class MatcherApi;
  39 class PhoneMetadata;
  40 class PhoneNumber;
  41 class PhoneNumberUtil;
  42
  43 class ShortNumberInfo {
  44  public:
  45   ShortNumberInfo();
  46   ~ShortNumberInfo();
  47
  48   // Cost categories of short numbers.
  49   enum ShortNumberCost {
  50     TOLL_FREE,
  51     STANDARD_RATE,
  52     PREMIUM_RATE,
  53     UNKNOWN_COST
  54   };
  55
  56   // DEPRECATED: Anyone who was using it and passing in a string with whitespace
  57   // (or other formatting characters) would have been getting the wrong result.
  58   // You should parse the string to PhoneNumber and use the method
  59   // IsPossibleShortNumberForRegion(PhoneNumber, String). This method will be
  60   // removed in the next release.
  61   //
  62   // Check whether a short number is a possible number when dialled from a
  63   // region, given the number in the form of a string, and the region where the
  64   // number is dialed from.  This provides a more lenient check than
  65   // IsValidShortNumberForRegion.
  66   bool IsPossibleShortNumberForRegion(
  67       const string& short_number,
  68       const string& region_dialing_from) const;
  69
  70   // Check whether a short number is a possible number when dialled from a
  71   // region, given the number in the form of a string, and the region where the
  72   // number is dialed from.  This provides a more lenient check than
  73   // IsValidShortNumberForRegion.
  74   bool IsPossibleShortNumberForRegion(
  75       const PhoneNumber& short_number,
  76       const string& region_dialing_from) const;
  77
  78   // Check whether a short number is a possible number. If a country calling
  79   // code is shared by multiple regions, this returns true if it's possible in
  80   // any of them. This provides a more lenient check than IsValidShortNumber.
  81   // See IsPossibleShortNumberForRegion for details.
  82   bool IsPossibleShortNumber(const PhoneNumber& number) const;
  83
  84   // DEPRECATED: Anyone who was using it and passing in a string with whitespace
  85   // (or other formatting characters) would have been getting the wrong result.
  86   // You should parse the string to PhoneNumber and use the method
  87   // IsValidShortNumberForRegion(PhoneNumber, String). This method will be
  88   // removed in the next release.
  89   //
  90   // Tests whether a short number matches a valid pattern in a region. Note
  91   // that this doesn't verify the number is actually in use, which is
  92   // impossible to tell by just looking at the number itself.
  93   bool IsValidShortNumberForRegion(
  94       const string& short_number,
  95       const string& region_dialing_from) const;
  96
  97   // Tests whether a short number matches a valid pattern in a region. Note
  98   // that this doesn't verify the number is actually in use, which is
  99   // impossible to tell by just looking at the number itself.
 100   bool IsValidShortNumberForRegion(
 101       const PhoneNumber& short_number,
 102       const string& region_dialing_from) const;
 103
 104   // Tests whether a short number matches a valid pattern. If a country calling
 105   // code is shared by multiple regions, this returns true if it's valid in any
 106   // of them. Note that this doesn't verify the number is actually in use,
 107   // which is impossible to tell by just looking at the number itself. See
 108   // IsValidShortNumberForRegion for details.
 109   bool IsValidShortNumber(const PhoneNumber& number) const;
 110
 111   // DEPRECATED: Anyone who was using it and passing in a string with whitespace
 112   // (or other formatting characters) would have been getting the wrong result.
 113   // You should parse the string to PhoneNumber and use the method
 114   // GetExpectedCostForRegion(PhoneNumber, String). This method will be
 115   // removed in the next release.
 116   //
 117   // Gets the expected cost category of a short number when dialled from a
 118   // region (however, nothing is implied about its validity). If it is
 119   // important that the number is valid, then its validity must first be
 120   // checked using IsValidShortNumberForRegion. Note that emergency numbers are
 121   // always considered toll-free. Example usage:
 122   //
 123   // ShortNumberInfo short_info;
 124   // string short_number("110");
 125   // RegionCode region_code = RegionCode::FR();
 126   // if (short_info.IsValidShortNumberForRegion(short_number, region_code)) {
 127   //   ShortNumberInfo::ShortNumberCost cost =
 128   //       short_info.GetExpectedCostForRegion(short_number, region_code);
 129   //   // Do something with the cost information here.
 130   // }
 131   ShortNumberCost GetExpectedCostForRegion(
 132       const string& short_number,
 133       const string& region_dialing_from) const;
 134
 135   // Gets the expected cost category of a short number when dialled from a
 136   // region (however, nothing is implied about its validity). If it is
 137   // important that the number is valid, then its validity must first be
 138   // checked using IsValidShortNumberForRegion. Note that emergency numbers are
 139   // always considered toll-free. Example usage:
 140   //
 141   // PhoneNumber number;
 142   // phone_util.Parse("110", "US", &number);
 143   // ...
 144   // string region_code("CA");
 145   // ShortNumberInfo short_info;
 146   // if (short_info.IsValidShortNumberForRegion(number, region_code)) {
 147   //   ShortNumberInfo::ShortNumberCost cost =
 148   //       short_info.GetExpectedCostForRegion(number, region_code);
 149   //   // Do something with the cost information here.
 150   // }
 151   ShortNumberCost GetExpectedCostForRegion(
 152       const PhoneNumber& short_number,
 153       const string& region_dialing_from) const;
 154
 155   // Gets the expected cost category of a short number (however, nothing is
 156   // implied about its validity). If the country calling code is unique to a
 157   // region, this method behaves exactly the same as GetExpectedCostForRegion.
 158   // However, if the country calling code is shared by multiple regions, then
 159   // it returns the highest cost in the sequence PREMIUM_RATE, UNKNOWN_COST,
 160   // STANDARD_RATE, TOLL_FREE. The reason for the position of UNKNOWN_COST in
 161   // this order is that if a number is UNKNOWN_COST in one region but
 162   // STANDARD_RATE or TOLL_FREE in another, its expected cost cannot be
 163   // estimated as one of the latter since it might be a PREMIUM_RATE number.
 164   //
 165   // For example, if a number is STANDARD_RATE in the US, but TOLL_FREE in
 166   // Canada, the expected cost returned by this method will be STANDARD_RATE,
 167   // since the NANPA countries share the same country calling code.
 168   //
 169   // Note: If the region from which the number is dialed is known, it is highly
 170   // preferable to call GetExpectedCostForRegion instead.
 171   ShortNumberCost GetExpectedCost(const PhoneNumber& number) const;
 172
 173   // Gets a valid short number for the specified region.
 174   string GetExampleShortNumber(const string& region_code) const;
 175
 176   // Gets a valid short number for the specified cost category.
 177   string GetExampleShortNumberForCost(const string& region_code,
 178                                       ShortNumberCost cost) const;
 179
 180   // Returns true if the number might be used to connect to an emergency service
 181   // in the given region.
 182   //
 183   // This method takes into account cases where the number might contain
 184   // formatting, or might have additional digits appended (when it is okay to do
 185   // that in the region specified).
 186   bool ConnectsToEmergencyNumber(const string& number,
 187                                  const string& region_code) const;
 188
 189   // Returns true if the number exactly matches an emergency service number in
 190   // the given region.
 191   //
 192   // This method takes into account cases where the number might contain
 193   // formatting, but doesn't allow additional digits to be appended.
 194   bool IsEmergencyNumber(const string& number,
 195                          const string& region_code) const;
 196
 197   // Given a valid short number, determines whether it is carrier-specific
 198   // (however, nothing is implied about its validity). If it is important that
 199   // the number is valid, then its validity must first be checked using
 200   // IsValidShortNumber or IsValidShortNumberForRegion.
 201   bool IsCarrierSpecific(const PhoneNumber& number) const;
 202
 203  private:
 204   const PhoneNumberUtil& phone_util_;
 205   const scoped_ptr<const MatcherApi> matcher_api_;
 206
 207   // A mapping from a RegionCode to the PhoneMetadata for that region.
 208   scoped_ptr<map<string, PhoneMetadata> >
 209       region_to_short_metadata_map_;
 210
 211   // In these countries, if extra digits are added to an emergency number, it no
 212   // longer connects to the emergency service.
 213   scoped_ptr<set<string> >
 214       regions_where_emergency_numbers_must_be_exact_;
 215
 216   const i18n::phonenumbers::PhoneMetadata* GetMetadataForRegion(
 217       const string& region_code) const;
 218
 219   // Helper method to get the region code for a given phone number, from a list
 220   // of possible region codes. If the list contains more than one region, the
 221   // first region for which the number is valid is returned.
 222   void GetRegionCodeForShortNumberFromRegionList(
 223       const PhoneNumber& number,
 224       const list<string>& region_codes,
 225       string* region_code) const;
 226
 227   bool MatchesEmergencyNumberHelper(const string& number,
 228                                     const string& region_code,
 229                                     bool allow_prefix_match) const;
 230
 231   DISALLOW_COPY_AND_ASSIGN(ShortNumberInfo);
 232 };
 233
 234 }  // namespace phonenumbers
 235 }  // namespace i18n
 236
 237 #endif  // I18N_PHONENUMBERS_SHORTNUMBERINFO_H_