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_ 164
