pref_service.h revision dc0f95d653279beabeb9817299e2902918ba123e
1// Copyright (c) 2011 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#ifndef CHROME_BROWSER_PREFS_PREF_SERVICE_H_ 8#define CHROME_BROWSER_PREFS_PREF_SERVICE_H_ 9#pragma once 10 11#include <set> 12#include <string> 13 14#include "base/ref_counted.h" 15#include "base/scoped_ptr.h" 16#include "base/threading/non_thread_safe.h" 17#include "base/values.h" 18 19class DefaultPrefStore; 20class FilePath; 21class NotificationObserver; 22class PersistentPrefStore; 23class PrefChangeObserver; 24class PrefNotifier; 25class PrefNotifierImpl; 26class PrefStore; 27class PrefValueStore; 28class Profile; 29 30namespace subtle { 31class PrefMemberBase; 32}; 33 34class PrefService : public base::NonThreadSafe { 35 public: 36 // A helper class to store all the information associated with a preference. 37 class Preference { 38 public: 39 40 // The type of the preference is determined by the type with which it is 41 // registered. This type needs to be a boolean, integer, double, string, 42 // dictionary (a branch), or list. You shouldn't need to construct this on 43 // your own; use the PrefService::Register*Pref methods instead. 44 Preference(const PrefService* service, 45 const char* name, 46 Value::ValueType type); 47 ~Preference() {} 48 49 // Returns the name of the Preference (i.e., the key, e.g., 50 // browser.window_placement). 51 const std::string name() const { return name_; } 52 53 // Returns the registered type of the preference. 54 Value::ValueType GetType() const; 55 56 // Returns the value of the Preference, falling back to the registered 57 // default value if no other has been set. 58 const Value* GetValue() const; 59 60 // Returns true if the Preference is managed, i.e. set by an admin policy. 61 // Since managed prefs have the highest priority, this also indicates 62 // whether the pref is actually being controlled by the policy setting. 63 bool IsManaged() const; 64 65 // Returns true if the Preference has a value set by an extension, even if 66 // that value is being overridden by a higher-priority source. 67 bool HasExtensionSetting() const; 68 69 // Returns true if the Preference has a user setting, even if that value is 70 // being overridden by a higher-priority source. 71 bool HasUserSetting() const; 72 73 // Returns true if the Preference value is currently being controlled by an 74 // extension, and not by any higher-priority source. 75 bool IsExtensionControlled() const; 76 77 // Returns true if the Preference value is currently being controlled by a 78 // user setting, and not by any higher-priority source. 79 bool IsUserControlled() const; 80 81 // Returns true if the Preference is currently using its default value, 82 // and has not been set by any higher-priority source (even with the same 83 // value). 84 bool IsDefaultValue() const; 85 86 // Returns true if the user can change the Preference value, which is the 87 // case if no higher-priority source than the user store controls the 88 // Preference. 89 bool IsUserModifiable() const; 90 91 // Returns true if an extension can change the Preference value, which is 92 // the case if no higher-priority source than the extension store controls 93 // the Preference. 94 bool IsExtensionModifiable() const; 95 96 private: 97 friend class PrefService; 98 99 PrefValueStore* pref_value_store() const { 100 return pref_service_->pref_value_store_.get(); 101 } 102 103 std::string name_; 104 105 Value::ValueType type_; 106 107 // Reference to the PrefService in which this pref was created. 108 const PrefService* pref_service_; 109 110 DISALLOW_COPY_AND_ASSIGN(Preference); 111 }; 112 113 // Factory method that creates a new instance of a PrefService with the 114 // applicable PrefStores. The |pref_filename| points to the user preference 115 // file. The |profile| is the one to which these preferences apply; it may be 116 // NULL if we're dealing with the local state. This is the usual way to create 117 // a new PrefService. |extension_pref_store| is used as the source for 118 // extension-controlled preferences and may be NULL. The PrefService takes 119 // ownership of |extension_pref_store|. 120 static PrefService* CreatePrefService(const FilePath& pref_filename, 121 PrefStore* extension_pref_store, 122 Profile* profile); 123 124 // Creates an incognito copy of the pref service that shares most pref stores 125 // but uses a fresh non-persistent overlay for the user pref store and an 126 // individual extension pref store (to cache the effective extension prefs for 127 // incognito windows). 128 PrefService* CreateIncognitoPrefService(PrefStore* incognito_extension_prefs); 129 130 virtual ~PrefService(); 131 132 // Reloads the data from file. This should only be called when the importer 133 // is running during first run, and the main process may not change pref 134 // values while the importer process is running. Returns true on success. 135 bool ReloadPersistentPrefs(); 136 137 // Returns true if the preference for the given preference name is available 138 // and is managed. 139 bool IsManagedPreference(const char* pref_name) const; 140 141 // Writes the data to disk. The return value only reflects whether 142 // serialization was successful; we don't know whether the data actually made 143 // it on disk (since it's on a different thread). This should only be used if 144 // we need to save immediately (basically, during shutdown). Otherwise, you 145 // should use ScheduleSavePersistentPrefs. 146 bool SavePersistentPrefs(); 147 148 // Serializes the data and schedules save using ImportantFileWriter. 149 void ScheduleSavePersistentPrefs(); 150 151 // Make the PrefService aware of a pref. 152 void RegisterBooleanPref(const char* path, bool default_value); 153 void RegisterIntegerPref(const char* path, int default_value); 154 void RegisterDoublePref(const char* path, double default_value); 155 void RegisterStringPref(const char* path, const std::string& default_value); 156 void RegisterFilePathPref(const char* path, const FilePath& default_value); 157 void RegisterListPref(const char* path); 158 void RegisterDictionaryPref(const char* path); 159 // These take ownership of the default_value: 160 void RegisterListPref(const char* path, ListValue* default_value); 161 void RegisterDictionaryPref(const char* path, DictionaryValue* default_value); 162 163 // These variants use a default value from the locale dll instead. 164 void RegisterLocalizedBooleanPref(const char* path, 165 int locale_default_message_id); 166 void RegisterLocalizedIntegerPref(const char* path, 167 int locale_default_message_id); 168 void RegisterLocalizedDoublePref(const char* path, 169 int locale_default_message_id); 170 void RegisterLocalizedStringPref(const char* path, 171 int locale_default_message_id); 172 173 // If the path is valid and the value at the end of the path matches the type 174 // specified, it will return the specified value. Otherwise, the default 175 // value (set when the pref was registered) will be returned. 176 bool GetBoolean(const char* path) const; 177 int GetInteger(const char* path) const; 178 double GetDouble(const char* path) const; 179 std::string GetString(const char* path) const; 180 FilePath GetFilePath(const char* path) const; 181 182 // Returns the branch if it exists, or the registered default value otherwise. 183 // Note that |path| must point to a registered preference. In that case, these 184 // functions will never return NULL. 185 const DictionaryValue* GetDictionary(const char* path) const; 186 const ListValue* GetList(const char* path) const; 187 188 // Removes a user pref and restores the pref to its default value. 189 void ClearPref(const char* path); 190 191 // If the path is valid (i.e., registered), update the pref value in the user 192 // prefs. Seting a null value on a preference of List or Dictionary type is 193 // equivalent to removing the user value for that preference, allowing the 194 // default value to take effect unless another value takes precedence. 195 void Set(const char* path, const Value& value); 196 void SetBoolean(const char* path, bool value); 197 void SetInteger(const char* path, int value); 198 void SetDouble(const char* path, double value); 199 void SetString(const char* path, const std::string& value); 200 void SetFilePath(const char* path, const FilePath& value); 201 202 // Int64 helper methods that actually store the given value as a string. 203 // Note that if obtaining the named value via GetDictionary or GetList, the 204 // Value type will be TYPE_STRING. 205 void SetInt64(const char* path, int64 value); 206 int64 GetInt64(const char* path) const; 207 void RegisterInt64Pref(const char* path, int64 default_value); 208 209 // Used to set the value of dictionary or list values in the pref tree. This 210 // will create a dictionary or list if one does not exist in the pref tree. 211 // This method returns NULL only if you're requesting an unregistered pref or 212 // a non-dict/non-list pref. 213 // WARNING: Changes to the dictionary or list will not automatically notify 214 // pref observers. 215 // Use a ScopedUserPrefUpdate to update observers on changes. 216 // These should really be GetUserMutable... since we will only ever get 217 // a mutable from the user preferences store. 218 DictionaryValue* GetMutableDictionary(const char* path); 219 ListValue* GetMutableList(const char* path); 220 // TODO(battre) remove this function (hack). 221 void ReportValueChanged(const std::string& key); 222 223 // Returns true if a value has been set for the specified path. 224 // NOTE: this is NOT the same as FindPreference. In particular 225 // FindPreference returns whether RegisterXXX has been invoked, where as 226 // this checks if a value exists for the path. 227 bool HasPrefPath(const char* path) const; 228 229 // Returns a dictionary with effective preference values. The ownership 230 // is passed to the caller. 231 DictionaryValue* GetPreferenceValues() const; 232 233 // A helper method to quickly look up a preference. Returns NULL if the 234 // preference is not registered. 235 const Preference* FindPreference(const char* pref_name) const; 236 237 bool ReadOnly() const; 238 239 protected: 240 // Construct a new pref service, specifying the pref sources as explicit 241 // PrefStore pointers. This constructor is what CreatePrefService() ends up 242 // calling. It's also used for unit tests. 243 PrefService(PrefStore* managed_platform_prefs, 244 PrefStore* managed_cloud_prefs, 245 PrefStore* extension_prefs, 246 PrefStore* command_line_prefs, 247 PersistentPrefStore* user_prefs, 248 PrefStore* recommended_platform_prefs, 249 PrefStore* recommended_cloud_prefs, 250 DefaultPrefStore* default_store); 251 252 // The PrefNotifier handles registering and notifying preference observers. 253 // It is created and owned by this PrefService. Subclasses may access it for 254 // unit testing. 255 scoped_ptr<PrefNotifierImpl> pref_notifier_; 256 257 private: 258 class PreferencePathComparator { 259 public: 260 bool operator() (Preference* lhs, Preference* rhs) const { 261 return lhs->name() < rhs->name(); 262 } 263 }; 264 typedef std::set<Preference*, PreferencePathComparator> PreferenceSet; 265 266 friend class PrefServiceMockBuilder; 267 268 // Registration of pref change observers must be done using the 269 // PrefChangeRegistrar, which is declared as a friend here to grant it 270 // access to the otherwise protected members Add/RemovePrefObserver. 271 // PrefMember registers for preferences changes notification directly to 272 // avoid the storage overhead of the registrar, so its base class must be 273 // declared as a friend, too. 274 friend class PrefChangeRegistrar; 275 friend class subtle::PrefMemberBase; 276 277 // Give access to pref_notifier(); 278 friend class ScopedUserPrefUpdate; 279 280 // Construct an incognito version of the pref service. Use 281 // CreateIncognitoPrefService() instead of calling this constructor directly. 282 PrefService(const PrefService& original, 283 PrefStore* incognito_extension_prefs); 284 285 // Returns a PrefNotifier. If you desire access to this, you will probably 286 // want to use a ScopedUserPrefUpdate. 287 PrefNotifier* pref_notifier() const; 288 289 // If the pref at the given path changes, we call the observer's Observe 290 // method with PREF_CHANGED. Note that observers should not call these methods 291 // directly but rather use a PrefChangeRegistrar to make sure the observer 292 // gets cleaned up properly. 293 virtual void AddPrefObserver(const char* path, NotificationObserver* obs); 294 virtual void RemovePrefObserver(const char* path, NotificationObserver* obs); 295 296 // Registers a new preference at |path|. The |default_value| must not be 297 // NULL as it determines the preference value's type. 298 // RegisterPreference must not be called twice for the same path. 299 // This method takes ownership of |default_value|. 300 void RegisterPreference(const char* path, Value* default_value); 301 302 // Sets the value for this pref path in the user pref store and informs the 303 // PrefNotifier of the change. 304 void SetUserPrefValue(const char* path, Value* new_value); 305 306 // Load preferences from storage, attempting to diagnose and handle errors. 307 // This should only be called from the constructor. 308 void InitFromStorage(); 309 310 // The PrefValueStore provides prioritized preference values. It is created 311 // and owned by this PrefService. Subclasses may access it for unit testing. 312 scoped_ptr<PrefValueStore> pref_value_store_; 313 314 // Pref Stores and profile that we passed to the PrefValueStore. 315 scoped_refptr<PersistentPrefStore> user_pref_store_; 316 scoped_refptr<DefaultPrefStore> default_store_; 317 318 // Local cache of registered Preference objects. The default_store_ 319 // is authoritative with respect to what the types and default values 320 // of registered preferences are. 321 mutable PreferenceSet prefs_; 322 323 DISALLOW_COPY_AND_ASSIGN(PrefService); 324}; 325 326#endif // CHROME_BROWSER_PREFS_PREF_SERVICE_H_ 327