| OLD | NEW |
|---|
| (Empty) |
| 1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | |
| 2 // Use of this source code is governed by a BSD-style license that can be | |
| 3 // found in the LICENSE file. | |
| 4 | |
| 5 // This provides a way to access the application's current preferences. | |
| 6 | |
| 7 // Chromium settings and storage represent user-selected preferences and | |
| 8 // information and MUST not be extracted, overwritten or modified except | |
| 9 // through Chromium defined APIs. | |
| 10 | |
| 11 #ifndef BASE_PREFS_PREF_SERVICE_H_ | |
| 12 #define BASE_PREFS_PREF_SERVICE_H_ | |
| 13 | |
| 14 #include <set> | |
| 15 #include <string> | |
| 16 | |
| 17 #include "base/callback.h" | |
| 18 #include "base/compiler_specific.h" | |
| 19 #include "base/containers/hash_tables.h" | |
| 20 #include "base/memory/ref_counted.h" | |
| 21 #include "base/memory/scoped_ptr.h" | |
| 22 #include "base/observer_list.h" | |
| 23 #include "base/prefs/base_prefs_export.h" | |
| 24 #include "base/prefs/persistent_pref_store.h" | |
| 25 #include "base/threading/non_thread_safe.h" | |
| 26 #include "base/values.h" | |
| 27 | |
| 28 class PrefNotifier; | |
| 29 class PrefNotifierImpl; | |
| 30 class PrefObserver; | |
| 31 class PrefRegistry; | |
| 32 class PrefValueStore; | |
| 33 class PrefStore; | |
| 34 | |
| 35 namespace base { | |
| 36 class FilePath; | |
| 37 } | |
| 38 | |
| 39 namespace subtle { | |
| 40 class PrefMemberBase; | |
| 41 class ScopedUserPrefUpdateBase; | |
| 42 } | |
| 43 | |
| 44 // Base class for PrefServices. You can use the base class to read and | |
| 45 // interact with preferences, but not to register new preferences; for | |
| 46 // that see e.g. PrefRegistrySimple. | |
| 47 // | |
| 48 // Settings and storage accessed through this class represent | |
| 49 // user-selected preferences and information and MUST not be | |
| 50 // extracted, overwritten or modified except through the defined APIs. | |
| 51 class BASE_PREFS_EXPORT PrefService : public base::NonThreadSafe { | |
| 52 public: | |
| 53 enum PrefInitializationStatus { | |
| 54 INITIALIZATION_STATUS_WAITING, | |
| 55 INITIALIZATION_STATUS_SUCCESS, | |
| 56 INITIALIZATION_STATUS_CREATED_NEW_PREF_STORE, | |
| 57 INITIALIZATION_STATUS_ERROR | |
| 58 }; | |
| 59 | |
| 60 // A helper class to store all the information associated with a preference. | |
| 61 class BASE_PREFS_EXPORT Preference { | |
| 62 public: | |
| 63 // The type of the preference is determined by the type with which it is | |
| 64 // registered. This type needs to be a boolean, integer, double, string, | |
| 65 // dictionary (a branch), or list. You shouldn't need to construct this on | |
| 66 // your own; use the PrefService::Register*Pref methods instead. | |
| 67 Preference(const PrefService* service, | |
| 68 const std::string& name, | |
| 69 base::Value::Type type); | |
| 70 ~Preference() {} | |
| 71 | |
| 72 // Returns the name of the Preference (i.e., the key, e.g., | |
| 73 // browser.window_placement). | |
| 74 const std::string name() const; | |
| 75 | |
| 76 // Returns the registered type of the preference. | |
| 77 base::Value::Type GetType() const; | |
| 78 | |
| 79 // Returns the value of the Preference, falling back to the registered | |
| 80 // default value if no other has been set. | |
| 81 const base::Value* GetValue() const; | |
| 82 | |
| 83 // Returns the value recommended by the admin, if any. | |
| 84 const base::Value* GetRecommendedValue() const; | |
| 85 | |
| 86 // Returns true if the Preference is managed, i.e. set by an admin policy. | |
| 87 // Since managed prefs have the highest priority, this also indicates | |
| 88 // whether the pref is actually being controlled by the policy setting. | |
| 89 bool IsManaged() const; | |
| 90 | |
| 91 // Returns true if the Preference is controlled by the custodian of the | |
| 92 // supervised user. Since a supervised user is not expected to have an admin | |
| 93 // policy, this is the controlling pref if set. | |
| 94 bool IsManagedByCustodian() const; | |
| 95 | |
| 96 // Returns true if the Preference is recommended, i.e. set by an admin | |
| 97 // policy but the user is allowed to change it. | |
| 98 bool IsRecommended() const; | |
| 99 | |
| 100 // Returns true if the Preference has a value set by an extension, even if | |
| 101 // that value is being overridden by a higher-priority source. | |
| 102 bool HasExtensionSetting() const; | |
| 103 | |
| 104 // Returns true if the Preference has a user setting, even if that value is | |
| 105 // being overridden by a higher-priority source. | |
| 106 bool HasUserSetting() const; | |
| 107 | |
| 108 // Returns true if the Preference value is currently being controlled by an | |
| 109 // extension, and not by any higher-priority source. | |
| 110 bool IsExtensionControlled() const; | |
| 111 | |
| 112 // Returns true if the Preference value is currently being controlled by a | |
| 113 // user setting, and not by any higher-priority source. | |
| 114 bool IsUserControlled() const; | |
| 115 | |
| 116 // Returns true if the Preference is currently using its default value, | |
| 117 // and has not been set by any higher-priority source (even with the same | |
| 118 // value). | |
| 119 bool IsDefaultValue() const; | |
| 120 | |
| 121 // Returns true if the user can change the Preference value, which is the | |
| 122 // case if no higher-priority source than the user store controls the | |
| 123 // Preference. | |
| 124 bool IsUserModifiable() const; | |
| 125 | |
| 126 // Returns true if an extension can change the Preference value, which is | |
| 127 // the case if no higher-priority source than the extension store controls | |
| 128 // the Preference. | |
| 129 bool IsExtensionModifiable() const; | |
| 130 | |
| 131 // Return the registration flags for this pref as a bitmask of | |
| 132 // PrefRegistry::PrefRegistrationFlags. | |
| 133 uint32 registration_flags() const { return registration_flags_; } | |
| 134 | |
| 135 private: | |
| 136 friend class PrefService; | |
| 137 | |
| 138 PrefValueStore* pref_value_store() const { | |
| 139 return pref_service_->pref_value_store_.get(); | |
| 140 } | |
| 141 | |
| 142 const std::string name_; | |
| 143 | |
| 144 const base::Value::Type type_; | |
| 145 | |
| 146 uint32 registration_flags_; | |
| 147 | |
| 148 // Reference to the PrefService in which this pref was created. | |
| 149 const PrefService* pref_service_; | |
| 150 }; | |
| 151 | |
| 152 // You may wish to use PrefServiceFactory or one of its subclasses | |
| 153 // for simplified construction. | |
| 154 PrefService( | |
| 155 PrefNotifierImpl* pref_notifier, | |
| 156 PrefValueStore* pref_value_store, | |
| 157 PersistentPrefStore* user_prefs, | |
| 158 PrefRegistry* pref_registry, | |
| 159 base::Callback<void(PersistentPrefStore::PrefReadError)> | |
| 160 read_error_callback, | |
| 161 bool async); | |
| 162 virtual ~PrefService(); | |
| 163 | |
| 164 // Lands pending writes to disk. This should only be used if we need to save | |
| 165 // immediately (basically, during shutdown). | |
| 166 void CommitPendingWrite(); | |
| 167 | |
| 168 // Schedule a write if there is any lossy data pending. Unlike | |
| 169 // CommitPendingWrite() this does not immediately sync to disk, instead it | |
| 170 // triggers an eventual write if there is lossy data pending and if there | |
| 171 // isn't one scheduled already. | |
| 172 void SchedulePendingLossyWrites(); | |
| 173 | |
| 174 // Returns true if the preference for the given preference name is available | |
| 175 // and is managed. | |
| 176 bool IsManagedPreference(const std::string& pref_name) const; | |
| 177 | |
| 178 // Returns true if the preference for the given preference name is available | |
| 179 // and is controlled by the parent/guardian of the child Account. | |
| 180 bool IsPreferenceManagedByCustodian(const std::string& pref_name) const; | |
| 181 | |
| 182 // Returns |true| if a preference with the given name is available and its | |
| 183 // value can be changed by the user. | |
| 184 bool IsUserModifiablePreference(const std::string& pref_name) const; | |
| 185 | |
| 186 // Look up a preference. Returns NULL if the preference is not | |
| 187 // registered. | |
| 188 const PrefService::Preference* FindPreference(const std::string& path) const; | |
| 189 | |
| 190 // If the path is valid and the value at the end of the path matches the type | |
| 191 // specified, it will return the specified value. Otherwise, the default | |
| 192 // value (set when the pref was registered) will be returned. | |
| 193 bool GetBoolean(const std::string& path) const; | |
| 194 int GetInteger(const std::string& path) const; | |
| 195 double GetDouble(const std::string& path) const; | |
| 196 std::string GetString(const std::string& path) const; | |
| 197 base::FilePath GetFilePath(const std::string& path) const; | |
| 198 | |
| 199 // Returns the branch if it exists, or the registered default value otherwise. | |
| 200 // Note that |path| must point to a registered preference. In that case, these | |
| 201 // functions will never return NULL. | |
| 202 const base::DictionaryValue* GetDictionary(const std::string& path) const; | |
| 203 const base::ListValue* GetList(const std::string& path) const; | |
| 204 | |
| 205 // Removes a user pref and restores the pref to its default value. | |
| 206 void ClearPref(const std::string& path); | |
| 207 | |
| 208 // If the path is valid (i.e., registered), update the pref value in the user | |
| 209 // prefs. | |
| 210 // To set the value of dictionary or list values in the pref tree use | |
| 211 // Set(), but to modify the value of a dictionary or list use either | |
| 212 // ListPrefUpdate or DictionaryPrefUpdate from scoped_user_pref_update.h. | |
| 213 void Set(const std::string& path, const base::Value& value); | |
| 214 void SetBoolean(const std::string& path, bool value); | |
| 215 void SetInteger(const std::string& path, int value); | |
| 216 void SetDouble(const std::string& path, double value); | |
| 217 void SetString(const std::string& path, const std::string& value); | |
| 218 void SetFilePath(const std::string& path, const base::FilePath& value); | |
| 219 | |
| 220 // Int64 helper methods that actually store the given value as a string. | |
| 221 // Note that if obtaining the named value via GetDictionary or GetList, the | |
| 222 // Value type will be TYPE_STRING. | |
| 223 void SetInt64(const std::string& path, int64 value); | |
| 224 int64 GetInt64(const std::string& path) const; | |
| 225 | |
| 226 // As above, but for unsigned values. | |
| 227 void SetUint64(const std::string& path, uint64 value); | |
| 228 uint64 GetUint64(const std::string& path) const; | |
| 229 | |
| 230 // Returns the value of the given preference, from the user pref store. If | |
| 231 // the preference is not set in the user pref store, returns NULL. | |
| 232 const base::Value* GetUserPrefValue(const std::string& path) const; | |
| 233 | |
| 234 // Changes the default value for a preference. Takes ownership of |value|. | |
| 235 // | |
| 236 // Will cause a pref change notification to be fired if this causes | |
| 237 // the effective value to change. | |
| 238 void SetDefaultPrefValue(const std::string& path, base::Value* value); | |
| 239 | |
| 240 // Returns the default value of the given preference. |path| must point to a | |
| 241 // registered preference. In that case, will never return NULL. | |
| 242 const base::Value* GetDefaultPrefValue(const std::string& path) const; | |
| 243 | |
| 244 // Returns true if a value has been set for the specified path. | |
| 245 // NOTE: this is NOT the same as FindPreference. In particular | |
| 246 // FindPreference returns whether RegisterXXX has been invoked, where as | |
| 247 // this checks if a value exists for the path. | |
| 248 bool HasPrefPath(const std::string& path) const; | |
| 249 | |
| 250 // Returns a dictionary with effective preference values. | |
| 251 scoped_ptr<base::DictionaryValue> GetPreferenceValues() const; | |
| 252 | |
| 253 // Returns a dictionary with effective preference values, omitting prefs that | |
| 254 // are at their default values. | |
| 255 scoped_ptr<base::DictionaryValue> GetPreferenceValuesOmitDefaults() const; | |
| 256 | |
| 257 // Returns a dictionary with effective preference values. Contrary to | |
| 258 // GetPreferenceValues(), the paths of registered preferences are not split on | |
| 259 // '.' characters. If a registered preference stores a dictionary, however, | |
| 260 // the hierarchical structure inside the preference will be preserved. | |
| 261 // For example, if "foo.bar" is a registered preference, the result could look | |
| 262 // like this: | |
| 263 // {"foo.bar": {"a": {"b": true}}}. | |
| 264 scoped_ptr<base::DictionaryValue> GetPreferenceValuesWithoutPathExpansion() | |
| 265 const; | |
| 266 | |
| 267 bool ReadOnly() const; | |
| 268 | |
| 269 PrefInitializationStatus GetInitializationStatus() const; | |
| 270 | |
| 271 // Tell our PrefValueStore to update itself to |command_line_store|. | |
| 272 // Takes ownership of the store. | |
| 273 virtual void UpdateCommandLinePrefStore(PrefStore* command_line_store); | |
| 274 | |
| 275 // We run the callback once, when initialization completes. The bool | |
| 276 // parameter will be set to true for successful initialization, | |
| 277 // false for unsuccessful. | |
| 278 void AddPrefInitObserver(base::Callback<void(bool)> callback); | |
| 279 | |
| 280 // Returns the PrefRegistry object for this service. You should not | |
| 281 // use this; the intent is for no registrations to take place after | |
| 282 // PrefService has been constructed. | |
| 283 // | |
| 284 // Instead of using this method, the recommended approach is to | |
| 285 // register all preferences for a class Xyz up front in a static | |
| 286 // Xyz::RegisterPrefs function, which gets invoked early in the | |
| 287 // application's start-up, before a PrefService is created. | |
| 288 // | |
| 289 // As an example, prefs registration in Chrome is triggered by the | |
| 290 // functions chrome::RegisterPrefs (for global preferences) and | |
| 291 // chrome::RegisterProfilePrefs (for user-specific preferences) | |
| 292 // implemented in chrome/browser/prefs/browser_prefs.cc. | |
| 293 PrefRegistry* DeprecatedGetPrefRegistry(); | |
| 294 | |
| 295 protected: | |
| 296 // The PrefNotifier handles registering and notifying preference observers. | |
| 297 // It is created and owned by this PrefService. Subclasses may access it for | |
| 298 // unit testing. | |
| 299 scoped_ptr<PrefNotifierImpl> pref_notifier_; | |
| 300 | |
| 301 // The PrefValueStore provides prioritized preference values. It is owned by | |
| 302 // this PrefService. Subclasses may access it for unit testing. | |
| 303 scoped_ptr<PrefValueStore> pref_value_store_; | |
| 304 | |
| 305 scoped_refptr<PrefRegistry> pref_registry_; | |
| 306 | |
| 307 // Pref Stores and profile that we passed to the PrefValueStore. | |
| 308 scoped_refptr<PersistentPrefStore> user_pref_store_; | |
| 309 | |
| 310 // Callback to call when a read error occurs. | |
| 311 base::Callback<void(PersistentPrefStore::PrefReadError)> read_error_callback_; | |
| 312 | |
| 313 private: | |
| 314 // Hash map expected to be fastest here since it minimises expensive | |
| 315 // string comparisons. Order is unimportant, and deletions are rare. | |
| 316 // Confirmed on Android where this speeded Chrome startup by roughly 50ms | |
| 317 // vs. std::map, and by roughly 180ms vs. std::set of Preference pointers. | |
| 318 typedef base::hash_map<std::string, Preference> PreferenceMap; | |
| 319 | |
| 320 // Give access to ReportUserPrefChanged() and GetMutableUserPref(). | |
| 321 friend class subtle::ScopedUserPrefUpdateBase; | |
| 322 friend class PrefServiceTest_WriteablePrefStoreFlags_Test; | |
| 323 | |
| 324 // Registration of pref change observers must be done using the | |
| 325 // PrefChangeRegistrar, which is declared as a friend here to grant it | |
| 326 // access to the otherwise protected members Add/RemovePrefObserver. | |
| 327 // PrefMember registers for preferences changes notification directly to | |
| 328 // avoid the storage overhead of the registrar, so its base class must be | |
| 329 // declared as a friend, too. | |
| 330 friend class PrefChangeRegistrar; | |
| 331 friend class subtle::PrefMemberBase; | |
| 332 | |
| 333 // These are protected so they can only be accessed by the friend | |
| 334 // classes listed above. | |
| 335 // | |
| 336 // If the pref at the given path changes, we call the observer's | |
| 337 // OnPreferenceChanged method. Note that observers should not call | |
| 338 // these methods directly but rather use a PrefChangeRegistrar to | |
| 339 // make sure the observer gets cleaned up properly. | |
| 340 // | |
| 341 // Virtual for testing. | |
| 342 virtual void AddPrefObserver(const std::string& path, PrefObserver* obs); | |
| 343 virtual void RemovePrefObserver(const std::string& path, PrefObserver* obs); | |
| 344 | |
| 345 // Sends notification of a changed preference. This needs to be called by | |
| 346 // a ScopedUserPrefUpdate if a DictionaryValue or ListValue is changed. | |
| 347 void ReportUserPrefChanged(const std::string& key); | |
| 348 | |
| 349 // Sets the value for this pref path in the user pref store and informs the | |
| 350 // PrefNotifier of the change. | |
| 351 void SetUserPrefValue(const std::string& path, base::Value* new_value); | |
| 352 | |
| 353 // Load preferences from storage, attempting to diagnose and handle errors. | |
| 354 // This should only be called from the constructor. | |
| 355 void InitFromStorage(bool async); | |
| 356 | |
| 357 // Used to set the value of dictionary or list values in the user pref store. | |
| 358 // This will create a dictionary or list if one does not exist in the user | |
| 359 // pref store. This method returns NULL only if you're requesting an | |
| 360 // unregistered pref or a non-dict/non-list pref. | |
| 361 // |type| may only be Values::TYPE_DICTIONARY or Values::TYPE_LIST and | |
| 362 // |path| must point to a registered preference of type |type|. | |
| 363 // Ownership of the returned value remains at the user pref store. | |
| 364 base::Value* GetMutableUserPref(const std::string& path, | |
| 365 base::Value::Type type); | |
| 366 | |
| 367 // GetPreferenceValue is the equivalent of FindPreference(path)->GetValue(), | |
| 368 // it has been added for performance. If is faster because it does | |
| 369 // not need to find or create a Preference object to get the | |
| 370 // value (GetValue() calls back though the preference service to | |
| 371 // actually get the value.). | |
| 372 const base::Value* GetPreferenceValue(const std::string& path) const; | |
| 373 | |
| 374 // Local cache of registered Preference objects. The pref_registry_ | |
| 375 // is authoritative with respect to what the types and default values | |
| 376 // of registered preferences are. | |
| 377 mutable PreferenceMap prefs_map_; | |
| 378 | |
| 379 DISALLOW_COPY_AND_ASSIGN(PrefService); | |
| 380 }; | |
| 381 | |
| 382 #endif // BASE_PREFS_PREF_SERVICE_H_ | |
| OLD | NEW |
|---|
Chromium Code Reviews
