1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/modules/libpref/public/Preferences.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,387 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef mozilla_Preferences_h
1.10 +#define mozilla_Preferences_h
1.11 +
1.12 +#ifndef MOZILLA_INTERNAL_API
1.13 +#error "This header is only usable from within libxul (MOZILLA_INTERNAL_API)."
1.14 +#endif
1.15 +
1.16 +#include "nsIPrefService.h"
1.17 +#include "nsIPrefBranch.h"
1.18 +#include "nsIPrefBranchInternal.h"
1.19 +#include "nsIObserver.h"
1.20 +#include "nsCOMPtr.h"
1.21 +#include "nsTArray.h"
1.22 +#include "nsWeakReference.h"
1.23 +#include "mozilla/MemoryReporting.h"
1.24 +
1.25 +class nsIFile;
1.26 +class nsCString;
1.27 +class nsString;
1.28 +class nsAdoptingString;
1.29 +class nsAdoptingCString;
1.30 +
1.31 +#ifndef have_PrefChangedFunc_typedef
1.32 +typedef void (*PrefChangedFunc)(const char *, void *);
1.33 +#define have_PrefChangedFunc_typedef
1.34 +#endif
1.35 +
1.36 +namespace mozilla {
1.37 +
1.38 +namespace dom {
1.39 +class PrefSetting;
1.40 +}
1.41 +
1.42 +class Preferences : public nsIPrefService,
1.43 + public nsIObserver,
1.44 + public nsIPrefBranchInternal,
1.45 + public nsSupportsWeakReference
1.46 +{
1.47 +public:
1.48 + typedef mozilla::dom::PrefSetting PrefSetting;
1.49 +
1.50 + NS_DECL_THREADSAFE_ISUPPORTS
1.51 + NS_DECL_NSIPREFSERVICE
1.52 + NS_FORWARD_NSIPREFBRANCH(sRootBranch->)
1.53 + NS_DECL_NSIOBSERVER
1.54 +
1.55 + Preferences();
1.56 + virtual ~Preferences();
1.57 +
1.58 + nsresult Init();
1.59 +
1.60 + /**
1.61 + * Reset loaded user prefs then read them
1.62 + */
1.63 + static nsresult ResetAndReadUserPrefs();
1.64 +
1.65 + /**
1.66 + * Returns the singleton instance which is addreffed.
1.67 + */
1.68 + static Preferences* GetInstanceForService();
1.69 +
1.70 + /**
1.71 + * Finallizes global members.
1.72 + */
1.73 + static void Shutdown();
1.74 +
1.75 + /**
1.76 + * Returns shared pref service instance
1.77 + * NOTE: not addreffed.
1.78 + */
1.79 + static nsIPrefService* GetService()
1.80 + {
1.81 + NS_ENSURE_TRUE(InitStaticMembers(), nullptr);
1.82 + return sPreferences;
1.83 + }
1.84 +
1.85 + /**
1.86 + * Returns shared pref branch instance.
1.87 + * NOTE: not addreffed.
1.88 + */
1.89 + static nsIPrefBranch* GetRootBranch()
1.90 + {
1.91 + NS_ENSURE_TRUE(InitStaticMembers(), nullptr);
1.92 + return sRootBranch;
1.93 + }
1.94 +
1.95 + /**
1.96 + * Returns shared default pref branch instance.
1.97 + * NOTE: not addreffed.
1.98 + */
1.99 + static nsIPrefBranch* GetDefaultRootBranch()
1.100 + {
1.101 + NS_ENSURE_TRUE(InitStaticMembers(), nullptr);
1.102 + return sDefaultRootBranch;
1.103 + }
1.104 +
1.105 + /**
1.106 + * Gets int or bool type pref value with default value if failed to get
1.107 + * the pref.
1.108 + */
1.109 + static bool GetBool(const char* aPref, bool aDefault = false)
1.110 + {
1.111 + bool result = aDefault;
1.112 + GetBool(aPref, &result);
1.113 + return result;
1.114 + }
1.115 +
1.116 + static int32_t GetInt(const char* aPref, int32_t aDefault = 0)
1.117 + {
1.118 + int32_t result = aDefault;
1.119 + GetInt(aPref, &result);
1.120 + return result;
1.121 + }
1.122 +
1.123 + static uint32_t GetUint(const char* aPref, uint32_t aDefault = 0)
1.124 + {
1.125 + uint32_t result = aDefault;
1.126 + GetUint(aPref, &result);
1.127 + return result;
1.128 + }
1.129 +
1.130 + static float GetFloat(const char* aPref, float aDefault = 0)
1.131 + {
1.132 + float result = aDefault;
1.133 + GetFloat(aPref, &result);
1.134 + return result;
1.135 + }
1.136 +
1.137 + /**
1.138 + * Gets char type pref value directly. If failed, the get() of result
1.139 + * returns nullptr. Even if succeeded but the result was empty string, the
1.140 + * get() does NOT return nullptr. So, you can check whether the method
1.141 + * succeeded or not by:
1.142 + *
1.143 + * nsAdoptingString value = Prefereces::GetString("foo.bar");
1.144 + * if (!value) {
1.145 + * // failed
1.146 + * }
1.147 + *
1.148 + * Be aware. If you wrote as:
1.149 + *
1.150 + * nsAutoString value = Preferences::GetString("foo.bar");
1.151 + * if (!value.get()) {
1.152 + * // the condition is always FALSE!!
1.153 + * }
1.154 + *
1.155 + * The value.get() doesn't return nullptr. You must use nsAdoptingString
1.156 + * when you need to check whether it was failure or not.
1.157 + */
1.158 + static nsAdoptingCString GetCString(const char* aPref);
1.159 + static nsAdoptingString GetString(const char* aPref);
1.160 + static nsAdoptingCString GetLocalizedCString(const char* aPref);
1.161 + static nsAdoptingString GetLocalizedString(const char* aPref);
1.162 +
1.163 + /**
1.164 + * Gets int, float, or bool type pref value with raw return value of
1.165 + * nsIPrefBranch.
1.166 + *
1.167 + * @param aPref A pref name.
1.168 + * @param aResult Must not be nullptr. The value is never modified
1.169 + * when these methods fail.
1.170 + */
1.171 + static nsresult GetBool(const char* aPref, bool* aResult);
1.172 + static nsresult GetInt(const char* aPref, int32_t* aResult);
1.173 + static nsresult GetFloat(const char* aPref, float* aResult);
1.174 + static nsresult GetUint(const char* aPref, uint32_t* aResult)
1.175 + {
1.176 + int32_t result;
1.177 + nsresult rv = GetInt(aPref, &result);
1.178 + if (NS_SUCCEEDED(rv)) {
1.179 + *aResult = static_cast<uint32_t>(result);
1.180 + }
1.181 + return rv;
1.182 + }
1.183 +
1.184 + /**
1.185 + * Gets string type pref value with raw return value of nsIPrefBranch.
1.186 + *
1.187 + * @param aPref A pref name.
1.188 + * @param aResult Must not be nullptr. The value is never modified
1.189 + * when these methods fail.
1.190 + */
1.191 + static nsresult GetCString(const char* aPref, nsACString* aResult);
1.192 + static nsresult GetString(const char* aPref, nsAString* aResult);
1.193 + static nsresult GetLocalizedCString(const char* aPref, nsACString* aResult);
1.194 + static nsresult GetLocalizedString(const char* aPref, nsAString* aResult);
1.195 +
1.196 + static nsresult GetComplex(const char* aPref, const nsIID &aType,
1.197 + void** aResult);
1.198 +
1.199 + /**
1.200 + * Sets various type pref values.
1.201 + */
1.202 + static nsresult SetBool(const char* aPref, bool aValue);
1.203 + static nsresult SetInt(const char* aPref, int32_t aValue);
1.204 + static nsresult SetUint(const char* aPref, uint32_t aValue)
1.205 + {
1.206 + return SetInt(aPref, static_cast<int32_t>(aValue));
1.207 + }
1.208 + static nsresult SetCString(const char* aPref, const char* aValue);
1.209 + static nsresult SetCString(const char* aPref, const nsACString &aValue);
1.210 + static nsresult SetString(const char* aPref, const char16_t* aValue);
1.211 + static nsresult SetString(const char* aPref, const nsAString &aValue);
1.212 +
1.213 + static nsresult SetComplex(const char* aPref, const nsIID &aType,
1.214 + nsISupports* aValue);
1.215 +
1.216 + /**
1.217 + * Clears user set pref.
1.218 + */
1.219 + static nsresult ClearUser(const char* aPref);
1.220 +
1.221 + /**
1.222 + * Whether the pref has a user value or not.
1.223 + */
1.224 + static bool HasUserValue(const char* aPref);
1.225 +
1.226 + /**
1.227 + * Gets the type of the pref.
1.228 + */
1.229 + static int32_t GetType(const char* aPref);
1.230 +
1.231 + /**
1.232 + * Adds/Removes the observer for the root pref branch.
1.233 + * The observer is referenced strongly if AddStrongObserver is used. On the
1.234 + * other hand, it is referenced weakly, if AddWeakObserver is used.
1.235 + * See nsIPrefBranch.idl for details.
1.236 + */
1.237 + static nsresult AddStrongObserver(nsIObserver* aObserver, const char* aPref);
1.238 + static nsresult AddWeakObserver(nsIObserver* aObserver, const char* aPref);
1.239 + static nsresult RemoveObserver(nsIObserver* aObserver, const char* aPref);
1.240 +
1.241 + /**
1.242 + * Adds/Removes two or more observers for the root pref branch.
1.243 + * Pass to aPrefs an array of const char* whose last item is nullptr.
1.244 + */
1.245 + static nsresult AddStrongObservers(nsIObserver* aObserver,
1.246 + const char** aPrefs);
1.247 + static nsresult AddWeakObservers(nsIObserver* aObserver,
1.248 + const char** aPrefs);
1.249 + static nsresult RemoveObservers(nsIObserver* aObserver,
1.250 + const char** aPrefs);
1.251 +
1.252 + /**
1.253 + * Registers/Unregisters the callback function for the aPref.
1.254 + */
1.255 + static nsresult RegisterCallback(PrefChangedFunc aCallback,
1.256 + const char* aPref,
1.257 + void* aClosure = nullptr);
1.258 + static nsresult UnregisterCallback(PrefChangedFunc aCallback,
1.259 + const char* aPref,
1.260 + void* aClosure = nullptr);
1.261 + // Like RegisterCallback, but also calls the callback immediately for
1.262 + // initialization.
1.263 + static nsresult RegisterCallbackAndCall(PrefChangedFunc aCallback,
1.264 + const char* aPref,
1.265 + void* aClosure = nullptr);
1.266 +
1.267 + /**
1.268 + * Adds the aVariable to cache table. aVariable must be a pointer for a
1.269 + * static variable. The value will be modified when the pref value is
1.270 + * changed but note that even if you modified it, the value isn't assigned to
1.271 + * the pref.
1.272 + */
1.273 + static nsresult AddBoolVarCache(bool* aVariable,
1.274 + const char* aPref,
1.275 + bool aDefault = false);
1.276 + static nsresult AddIntVarCache(int32_t* aVariable,
1.277 + const char* aPref,
1.278 + int32_t aDefault = 0);
1.279 + static nsresult AddUintVarCache(uint32_t* aVariable,
1.280 + const char* aPref,
1.281 + uint32_t aDefault = 0);
1.282 + static nsresult AddFloatVarCache(float* aVariable,
1.283 + const char* aPref,
1.284 + float aDefault = 0.0f);
1.285 +
1.286 + /**
1.287 + * Gets the default bool, int or uint value of the pref.
1.288 + * The result is raw result of nsIPrefBranch::Get*Pref().
1.289 + * If the pref could have any value, you needed to use these methods.
1.290 + * If not so, you could use below methods.
1.291 + */
1.292 + static nsresult GetDefaultBool(const char* aPref, bool* aResult);
1.293 + static nsresult GetDefaultInt(const char* aPref, int32_t* aResult);
1.294 + static nsresult GetDefaultUint(const char* aPref, uint32_t* aResult)
1.295 + {
1.296 + return GetDefaultInt(aPref, reinterpret_cast<int32_t*>(aResult));
1.297 + }
1.298 +
1.299 + /**
1.300 + * Gets the default bool, int or uint value of the pref directly.
1.301 + * You can set an invalid value of the pref to aFailedResult. If these
1.302 + * methods failed to get the default value, they would return the
1.303 + * aFailedResult value.
1.304 + */
1.305 + static bool GetDefaultBool(const char* aPref, bool aFailedResult)
1.306 + {
1.307 + bool result;
1.308 + return NS_SUCCEEDED(GetDefaultBool(aPref, &result)) ? result :
1.309 + aFailedResult;
1.310 + }
1.311 + static int32_t GetDefaultInt(const char* aPref, int32_t aFailedResult)
1.312 + {
1.313 + int32_t result;
1.314 + return NS_SUCCEEDED(GetDefaultInt(aPref, &result)) ? result : aFailedResult;
1.315 + }
1.316 + static uint32_t GetDefaultUint(const char* aPref, uint32_t aFailedResult)
1.317 + {
1.318 + return static_cast<uint32_t>(
1.319 + GetDefaultInt(aPref, static_cast<int32_t>(aFailedResult)));
1.320 + }
1.321 +
1.322 + /**
1.323 + * Gets the default value of the char type pref.
1.324 + * If the get() of the result returned nullptr, that meant the value didn't
1.325 + * have default value.
1.326 + *
1.327 + * See the comment at definition at GetString() and GetCString() for more
1.328 + * details of the result.
1.329 + */
1.330 + static nsAdoptingString GetDefaultString(const char* aPref);
1.331 + static nsAdoptingCString GetDefaultCString(const char* aPref);
1.332 + static nsAdoptingString GetDefaultLocalizedString(const char* aPref);
1.333 + static nsAdoptingCString GetDefaultLocalizedCString(const char* aPref);
1.334 +
1.335 + static nsresult GetDefaultCString(const char* aPref, nsACString* aResult);
1.336 + static nsresult GetDefaultString(const char* aPref, nsAString* aResult);
1.337 + static nsresult GetDefaultLocalizedCString(const char* aPref,
1.338 + nsACString* aResult);
1.339 + static nsresult GetDefaultLocalizedString(const char* aPref,
1.340 + nsAString* aResult);
1.341 +
1.342 + static nsresult GetDefaultComplex(const char* aPref, const nsIID &aType,
1.343 + void** aResult);
1.344 +
1.345 + /**
1.346 + * Gets the type of the pref.
1.347 + */
1.348 + static int32_t GetDefaultType(const char* aPref);
1.349 +
1.350 + // Used to synchronise preferences between chrome and content processes.
1.351 + static void GetPreferences(InfallibleTArray<PrefSetting>* aPrefs);
1.352 + static void GetPreference(PrefSetting* aPref);
1.353 + static void SetPreference(const PrefSetting& aPref);
1.354 +
1.355 + static int64_t SizeOfIncludingThisAndOtherStuff(mozilla::MallocSizeOf aMallocSizeOf);
1.356 + static nsresult SetFloat(const char* aPref, float aValue);
1.357 +
1.358 +protected:
1.359 + nsresult NotifyServiceObservers(const char *aSubject);
1.360 + /**
1.361 + * Reads the default pref file or, if that failed, try to save a new one.
1.362 + *
1.363 + * @return NS_OK if either action succeeded,
1.364 + * or the error code related to the read attempt.
1.365 + */
1.366 + nsresult UseDefaultPrefFile();
1.367 + nsresult UseUserPrefFile();
1.368 + nsresult ReadAndOwnUserPrefFile(nsIFile *aFile);
1.369 + nsresult ReadAndOwnSharedUserPrefFile(nsIFile *aFile);
1.370 + nsresult SavePrefFileInternal(nsIFile* aFile);
1.371 + nsresult WritePrefFile(nsIFile* aFile);
1.372 + nsresult MakeBackupPrefFile(nsIFile *aFile);
1.373 +
1.374 +private:
1.375 + nsCOMPtr<nsIFile> mCurrentFile;
1.376 +
1.377 + static Preferences* sPreferences;
1.378 + static nsIPrefBranch* sRootBranch;
1.379 + static nsIPrefBranch* sDefaultRootBranch;
1.380 + static bool sShutdown;
1.381 +
1.382 + /**
1.383 + * Init static members. TRUE if it succeeded. Otherwise, FALSE.
1.384 + */
1.385 + static bool InitStaticMembers();
1.386 +};
1.387 +
1.388 +} // namespace mozilla
1.389 +
1.390 +#endif // mozilla_Preferences_h
