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 #include "phonenumbers/phonemetadata.pb.h"
  30
  31 namespace i18n {
  32 namespace phonenumbers {
  33
  34 using std::list;
  35 using std::map;
  36 using std::set;
  37 using std::string;
  38
  39 class PhoneNumber;
  40 class PhoneNumberUtil;
  41
  42 class ShortNumberInfo {
  43  public:
  44   ShortNumberInfo();
  45
  46   // Cost categories of short numbers.
  47   enum ShortNumberCost {
  48     TOLL_FREE,
  49     STANDARD_RATE,
  50     PREMIUM_RATE,
  51     UNKNOWN_COST
  52   };
  53
  54   // Check whether a short number is a possible number when dialled from a
  55   // region, given the number in the form of a string, and the region where the
  56   // number is dialed from.  This provides a more lenient check than
  57   // IsValidShortNumberForRegion.
  58   bool IsPossibleShortNumberForRegion(
  59       const string& short_number,
  60       const string& region_dialing_from) const;
  61
  62   // Check whether a short number is a possible number. If a country calling
  63   // code is shared by multiple regions, this returns true if it's possible in
  64   // any of them. This provides a more lenient check than IsValidShortNumber.
  65   // See IsPossibleShortNumberForRegion for details.
  66   bool IsPossibleShortNumber(const PhoneNumber& number) const;
  67
  68   // Tests whether a short number matches a valid pattern in a region. Note
  69   // that this doesn't verify the number is actually in use, which is
  70   // impossible to tell by just looking at the number itself.
  71   bool IsValidShortNumberForRegion(
  72       const string& short_number,
  73       const string& region_dialing_from) const;
  74
  75   // Tests whether a short number matches a valid pattern. If a country calling
  76   // code is shared by multiple regions, this returns true if it's valid in any
  77   // of them. Note that this doesn't verify the number is actually in use,
  78   // which is impossible to tell by just looking at the number itself. See
  79   // IsValidShortNumberForRegion for details.
  80   bool IsValidShortNumber(const PhoneNumber& number) const;
  81
  82   // Gets the expected cost category of a short number when dialled from a
  83   // region (however, nothing is implied about its validity). If it is
  84   // important that the number is valid, then its validity must first be
  85   // checked using IsValidShortNumberForRegion. Note that emergency numbers are
  86   // always considered toll-free. Example usage:
  87   //
  88   // ShortNumberInfo short_info;
  89   // string short_number("110");
  90   // RegionCode region_code = RegionCode::FR();
  91   // if (short_info.IsValidShortNumberForRegion(short_number, region_code)) {
  92   //   ShortNumberInfo::ShortNumberCost cost =
  93   //       short_info.GetExpectedCostForRegion(short_number, region_code);
  94   //   // Do something with the cost information here.
  95   // }
  96   ShortNumberCost GetExpectedCostForRegion(
  97       const string& short_number,
  98       const string& region_dialing_from) const;
  99
 100   // Gets the expected cost category of a short number (however, nothing is
 101   // implied about its validity). If the country calling code is unique to a
 102   // region, this method behaves exactly the same as GetExpectedCostForRegion.
 103   // However, if the country calling code is shared by multiple regions, then
 104   // it returns the highest cost in the sequence PREMIUM_RATE, UNKNOWN_COST,
 105   // STANDARD_RATE, TOLL_FREE. The reason for the position of UNKNOWN_COST in
 106   // this order is that if a number is UNKNOWN_COST in one region but
 107   // STANDARD_RATE or TOLL_FREE in another, its expected cost cannot be
 108   // estimated as one of the latter since it might be a PREMIUM_RATE number.
 109   //
 110   // For example, if a number is STANDARD_RATE in the US, but TOLL_FREE in
 111   // Canada, the expected cost returned by this method will be STANDARD_RATE,
 112   // since the NANPA countries share the same country calling code.
 113   //
 114   // Note: If the region from which the number is dialed is known, it is highly
 115   // preferable to call GetExpectedCostForRegion instead.
 116   ShortNumberCost GetExpectedCost(const PhoneNumber& number) const;
 117
 118   // Gets a valid short number for the specified region.
 119   string GetExampleShortNumber(const string& region_code) const;
 120
 121   // Gets a valid short number for the specified cost category.
 122   string GetExampleShortNumberForCost(const string& region_code,
 123                                       ShortNumberCost cost) const;
 124
 125   // Returns true if the number might be used to connect to an emergency service
 126   // in the given region.
 127   //
 128   // This method takes into account cases where the number might contain
 129   // formatting, or might have additional digits appended (when it is okay to do
 130   // that in the region specified).
 131   bool ConnectsToEmergencyNumber(const string& number,
 132                                  const string& region_code) const;
 133
 134   // Returns true if the number exactly matches an emergency service number in
 135   // the given region.
 136   //
 137   // This method takes into account cases where the number might contain
 138   // formatting, but doesn't allow additional digits to be appended.
 139   bool IsEmergencyNumber(const string& number,
 140                          const string& region_code) const;
 141
 142   // Given a valid short number, determines whether it is carrier-specific
 143   // (however, nothing is implied about its validity). If it is important that
 144   // the number is valid, then its validity must first be checked using
 145   // IsValidShortNumber or IsValidShortNumberForRegion.
 146   bool IsCarrierSpecific(const PhoneNumber& number) const;
 147
 148  private:
 149   const PhoneNumberUtil& phone_util_;
 150
 151   // A mapping from a RegionCode to the PhoneMetadata for that region.
 152   scoped_ptr<map<string, PhoneMetadata> >
 153       region_to_short_metadata_map_;
 154
 155   // In these countries, if extra digits are added to an emergency number, it no
 156   // longer connects to the emergency service.
 157   scoped_ptr<set<string> >
 158       regions_where_emergency_numbers_must_be_exact_;
 159
 160   const i18n::phonenumbers::PhoneMetadata* GetMetadataForRegion(
 161       const string& region_code) const;
 162
 163   // Helper method to get the region code for a given phone number, from a list
 164   // of possible region codes. If the list contains more than one region, the
 165   // first region for which the number is valid is returned.
 166   void GetRegionCodeForShortNumberFromRegionList(
 167       const PhoneNumber& number,
 168       const list<string>& region_codes,
 169       string* region_code) const;
 170
 171   bool MatchesEmergencyNumberHelper(const string& number,
 172                                     const string& region_code,
 173                                     bool allow_prefix_match) const;
 174
 175   DISALLOW_COPY_AND_ASSIGN(ShortNumberInfo);
 176 };
 177
 178 }  // namespace phonenumbers
 179 }  // namespace i18n
 180
 181 #endif  // I18N_PHONENUMBERS_SHORTNUMBERINFO_H_