src/third_party/libaddressinput/chromium/cpp/include/libaddressinput/address_validator.h

   1 // Copyright (C) 2013 Google Inc.
   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 #ifndef I18N_ADDRESSINPUT_ADDRESS_VALIDATOR_H_
  16 #define I18N_ADDRESSINPUT_ADDRESS_VALIDATOR_H_
  17
  18 #include <libaddressinput/address_field.h>
  19 #include <libaddressinput/address_problem.h>
  20 #include <libaddressinput/util/scoped_ptr.h>
  21
  22 #include <map>
  23 #include <string>
  24 #include <vector>
  25
  26 namespace i18n {
  27 namespace addressinput {
  28
  29 class Downloader;
  30 class LoadRulesDelegate;
  31 class Storage;
  32 struct AddressData;
  33
  34 typedef std::vector<AddressProblem> AddressProblems;
  35 typedef std::multimap<AddressField, AddressProblem::Type> AddressProblemFilter;
  36
  37 // Validates an AddressData structure. Sample usage:
  38 //    class MyClass : public LoadRulesDelegate {
  39 //     public:
  40 //      MyClass() : validator_(AddressValidator::Build(
  41 //                      scoped_ptr<Downloader>(new MyDownloader),
  42 //                      scoped_ptr<Storage>(new MyStorage),
  43 //                      this)) {
  44 //        validator_->LoadRules("US");
  45 //      }
  46 //
  47 //      virtual ~MyClass() {}
  48 //
  49 //      virtual void OnAddressValidationRulesLoaded(
  50 //          const std::string& country_code,
  51 //          bool success) {
  52 //        ...
  53 //      }
  54 //
  55 //      void ValidateAddress() {
  56 //        AddressData address;
  57 //        address.country_code = "US";
  58 //        address.administrative_area = "CA";
  59 //        AddressProblems problems;
  60 //        AddressProblemFilter filter;
  61 //        AddressValidator::Status status =
  62 //            validator_->ValidateAddress(address, filter, &problems);
  63 //        if (status == AddressValidator::SUCCESS) {
  64 //          Process(problems);
  65 //        }
  66 //      }
  67 //
  68 //     private:
  69 //      scoped_ptr<AddressValidator> validator_;
  70 //    };
  71 class AddressValidator {
  72  public:
  73   // The status of address validation.
  74   enum Status {
  75     // Address validation completed successfully. Check |problems| to see if any
  76     // problems were found.
  77     SUCCESS,
  78
  79     // The validation rules are not available, because LoadRules() was not
  80     // called or failed. Reload the rules.
  81     RULES_UNAVAILABLE,
  82
  83     // The validation rules are being loaded. Try again later.
  84     RULES_NOT_READY
  85   };
  86
  87   virtual ~AddressValidator();
  88
  89   // Builds an address validator. Takes ownership of |downloader| and |storage|,
  90   // which cannot be NULL. Does not take ownership of |load_rules_delegate|,
  91   // which can be NULL. The caller owns the result.
  92   static scoped_ptr<AddressValidator> Build(
  93       scoped_ptr<Downloader> downloader,
  94       scoped_ptr<Storage> storage,
  95       LoadRulesDelegate* load_rules_delegate);
  96
  97   // Loads the generic validation rules for |country_code| and specific rules
  98   // for the country's administrative areas, localities, and dependent
  99   // localities. A typical data size is 10KB. The largest is 250KB. If a country
 100   // has language-specific validation rules, then these are also loaded.
 101   //
 102   // Example rule:
 103   // https://i18napis.appspot.com/ssl-aggregate-address/data/US
 104   //
 105   // If the rules were loaded successfully before or are still being loaded,
 106   // then does nothing. Notifies |load_rules_delegate| when the loading
 107   // finishes.
 108   virtual void LoadRules(const std::string& country_code) = 0;
 109
 110   // Validates the |address| and populates |problems| with the validation
 111   // problems, filtered according to the |filter| parameter.
 112   //
 113   // If the |filter| is empty, then all discovered validation problems are
 114   // returned. If the |filter| contains problem elements, then only the problems
 115   // in the |filter| may be returned.
 116   //
 117   // If the |problems| parameter is NULL, then checks whether the validation
 118   // rules are available, but does not validate the |address|.
 119   virtual Status ValidateAddress(const AddressData& address,
 120                                  const AddressProblemFilter& filter,
 121                                  AddressProblems* problems) const = 0;
 122
 123   // Fills in |suggestions| for the partially typed in |user_input|, assuming
 124   // the user is typing in the |focused_field|. If the number of |suggestions|
 125   // is over the |suggestion_limit|, then returns no |suggestions| at all.
 126   //
 127   // If the |solutions| parameter is NULL, the checks whether the validation
 128   // rules are available, but does not fill in suggestions.
 129   //
 130   // Sample user input 1:
 131   //   country code = "US"
 132   //   postal code = "90066"
 133   //   focused field = POSTAL_CODE
 134   //   suggestions limit = 1
 135   // Suggestion:
 136   //   [{administrative_area: "CA"}]
 137   //
 138   // Sample user input 2:
 139   //   country code = "CN"
 140   //   dependent locality = "Zongyang"
 141   //   focused field = DEPENDENT_LOCALITY
 142   //   suggestions limit = 10
 143   // Suggestion:
 144   //   [{dependent_locality: "Zongyang Xian",
 145   //     locality: "Anqing Shi",
 146   //     administrative_area: "Anhui Sheng"}]
 147   virtual Status GetSuggestions(
 148       const AddressData& user_input,
 149       AddressField focused_field,
 150       size_t suggestion_limit,
 151       std::vector<AddressData>* suggestions) const = 0;
 152
 153   // Canonicalizes the administrative area in |address_data|. For example,
 154   // "texas" changes to "TX". Returns true on success, otherwise leaves
 155   // |address_data| alone and returns false.
 156   virtual bool CanonicalizeAdministrativeArea(AddressData* address_data)
 157       const = 0;
 158 };
 159
 160 }  // namespace addressinput
 161 }  // namespace i18n
 162
 163 #endif  // I18N_ADDRESSINPUT_ADDRESS_VALIDATOR_H_