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