LCOV - code coverage report
Current view: directory - objdir/dist/include/mozilla - Preferences.h (source / functions) Found Hit Coverage
Test: app.info Lines: 29 29 100.0 %
Date: 2012-06-02 Functions: 28 27 96.4 %

       1                 : /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
       2                 : /* ***** BEGIN LICENSE BLOCK *****
       3                 :  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
       4                 :  *
       5                 :  * The contents of this file are subject to the Mozilla Public License Version
       6                 :  * 1.1 (the "License"); you may not use this file except in compliance with
       7                 :  * the License. You may obtain a copy of the License at
       8                 :  * http://www.mozilla.org/MPL/
       9                 :  *
      10                 :  * Software distributed under the License is distributed on an "AS IS" basis,
      11                 :  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
      12                 :  * for the specific language governing rights and limitations under the
      13                 :  * License.
      14                 :  *
      15                 :  * The Original Code is Mozilla Communicator client code.
      16                 :  *
      17                 :  * The Initial Developer of the Original Code is
      18                 :  * Netscape Communications Corporation.
      19                 :  * Portions created by the Initial Developer are Copyright (C) 1998
      20                 :  * the Initial Developer. All Rights Reserved.
      21                 :  *
      22                 :  * Contributor(s):
      23                 :  *   Brian Nesse <bnesse@netscape.com>
      24                 :  *   Mats Palmgren <matspal@gmail.com>
      25                 :  *
      26                 :  * Alternatively, the contents of this file may be used under the terms of
      27                 :  * either the GNU General Public License Version 2 or later (the "GPL"), or
      28                 :  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
      29                 :  * in which case the provisions of the GPL or the LGPL are applicable instead
      30                 :  * of those above. If you wish to allow use of your version of this file only
      31                 :  * under the terms of either the GPL or the LGPL, and not to allow others to
      32                 :  * use your version of this file under the terms of the MPL, indicate your
      33                 :  * decision by deleting the provisions above and replace them with the notice
      34                 :  * and other provisions required by the GPL or the LGPL. If you do not delete
      35                 :  * the provisions above, a recipient may use your version of this file under
      36                 :  * the terms of any one of the MPL, the GPL or the LGPL.
      37                 :  *
      38                 :  * ***** END LICENSE BLOCK ***** */
      39                 : 
      40                 : #ifndef mozilla_Preferences_h
      41                 : #define mozilla_Preferences_h
      42                 : 
      43                 : #ifndef MOZILLA_INTERNAL_API
      44                 : #error "This header is only usable from within libxul (MOZILLA_INTERNAL_API)."
      45                 : #endif
      46                 : 
      47                 : #include "nsIPrefService.h"
      48                 : #include "nsIPrefBranch.h"
      49                 : #include "nsIPrefBranchInternal.h"
      50                 : #include "nsIObserver.h"
      51                 : #include "nsCOMPtr.h"
      52                 : #include "nsWeakReference.h"
      53                 : 
      54                 : class nsIFile;
      55                 : class nsCString;
      56                 : class nsString;
      57                 : class nsAdoptingString;
      58                 : class nsAdoptingCString;
      59                 : 
      60                 : #ifndef have_PrefChangedFunc_typedef
      61                 : typedef int (*PR_CALLBACK PrefChangedFunc)(const char *, void *);
      62                 : #define have_PrefChangedFunc_typedef
      63                 : #endif
      64                 : 
      65                 : namespace mozilla {
      66                 : 
      67                 : class Preferences : public nsIPrefService,
      68                 :                     public nsIObserver,
      69                 :                     public nsIPrefBranchInternal,
      70                 :                     public nsSupportsWeakReference
      71                 : {
      72                 : public:
      73                 :   NS_DECL_ISUPPORTS
      74                 :   NS_DECL_NSIPREFSERVICE
      75          240993 :   NS_FORWARD_NSIPREFBRANCH(sRootBranch->)
      76                 :   NS_DECL_NSIOBSERVER
      77                 : 
      78                 :   Preferences();
      79                 :   virtual ~Preferences();
      80                 : 
      81                 :   nsresult Init();
      82                 : 
      83                 :   /**
      84                 :    * Reset loaded user prefs then read them
      85                 :    */
      86                 :   static nsresult ResetAndReadUserPrefs();
      87                 : 
      88                 :   /**
      89                 :    * Returns the singleton instance which is addreffed.
      90                 :    */
      91                 :   static Preferences* GetInstanceForService();
      92                 : 
      93                 :   /**
      94                 :    * Finallizes global members.
      95                 :    */
      96                 :   static void Shutdown();
      97                 : 
      98                 :   /**
      99                 :    * Returns shared pref service instance
     100                 :    * NOTE: not addreffed.
     101                 :    */
     102              15 :   static nsIPrefService* GetService()
     103                 :   {
     104              15 :     NS_ENSURE_TRUE(InitStaticMembers(), nsnull);
     105              15 :     return sPreferences;
     106                 :   }
     107                 : 
     108                 :   /**
     109                 :    * Returns shared pref branch instance.
     110                 :    * NOTE: not addreffed.
     111                 :    */
     112            1653 :   static nsIPrefBranch* GetRootBranch()
     113                 :   {
     114            1653 :     NS_ENSURE_TRUE(InitStaticMembers(), nsnull);
     115            1653 :     return sRootBranch;
     116                 :   }
     117                 : 
     118                 :   /**
     119                 :    * Returns shared default pref branch instance.
     120                 :    * NOTE: not addreffed.
     121                 :    */
     122               1 :   static nsIPrefBranch* GetDefaultRootBranch()
     123                 :   {
     124               1 :     NS_ENSURE_TRUE(InitStaticMembers(), nsnull);
     125               1 :     return sDefaultRootBranch;
     126                 :   }
     127                 : 
     128                 :   /**
     129                 :    * Gets int or bool type pref value with default value if failed to get
     130                 :    * the pref.
     131                 :    */
     132           33709 :   static bool GetBool(const char* aPref, bool aDefault = false)
     133                 :   {
     134           33709 :     bool result = aDefault;
     135           33709 :     GetBool(aPref, &result);
     136           33709 :     return result;
     137                 :   }
     138                 : 
     139           26774 :   static PRInt32 GetInt(const char* aPref, PRInt32 aDefault = 0)
     140                 :   {
     141           26774 :     PRInt32 result = aDefault;
     142           26774 :     GetInt(aPref, &result);
     143           26774 :     return result;
     144                 :   }
     145                 : 
     146            7046 :   static PRUint32 GetUint(const char* aPref, PRUint32 aDefault = 0)
     147                 :   {
     148            7046 :     PRUint32 result = aDefault;
     149            7046 :     GetUint(aPref, &result);
     150            7046 :     return result;
     151                 :   }
     152                 : 
     153                 :   /**
     154                 :    * Gets char type pref value directly.  If failed, the get() of result
     155                 :    * returns NULL.  Even if succeeded but the result was empty string, the
     156                 :    * get() does NOT return NULL.  So, you can check whether the method
     157                 :    * succeeded or not by:
     158                 :    *
     159                 :    * nsAdoptingString value = Prefereces::GetString("foo.bar");
     160                 :    * if (!value) {
     161                 :    *   // failed
     162                 :    * }
     163                 :    *
     164                 :    * Be aware.  If you wrote as:
     165                 :    *
     166                 :    * nsAutoString value = Preferences::GetString("foo.bar");
     167                 :    * if (!value.get()) {
     168                 :    *   // the condition is always FALSE!!
     169                 :    * }
     170                 :    *
     171                 :    * The value.get() doesn't return NULL. You must use nsAdoptingString when
     172                 :    * you need to check whether it was failure or not.
     173                 :    */
     174                 :   static nsAdoptingCString GetCString(const char* aPref);
     175                 :   static nsAdoptingString GetString(const char* aPref);
     176                 :   static nsAdoptingCString GetLocalizedCString(const char* aPref);
     177                 :   static nsAdoptingString GetLocalizedString(const char* aPref);
     178                 : 
     179                 :   /**
     180                 :    * Gets int or bool type pref value with raw return value of nsIPrefBranch.
     181                 :    *
     182                 :    * @param aPref       A pref name.
     183                 :    * @param aResult     Must not be NULL.  The value is never modified when
     184                 :    *                    these methods fail.
     185                 :    */
     186                 :   static nsresult GetBool(const char* aPref, bool* aResult);
     187                 :   static nsresult GetInt(const char* aPref, PRInt32* aResult);
     188            7046 :   static nsresult GetUint(const char* aPref, PRUint32* aResult)
     189                 :   {
     190                 :     PRInt32 result;
     191            7046 :     nsresult rv = GetInt(aPref, &result);
     192            7046 :     if (NS_SUCCEEDED(rv)) {
     193            7046 :       *aResult = static_cast<PRUint32>(result);
     194                 :     }
     195            7046 :     return rv;
     196                 :   }
     197                 : 
     198                 :   /**
     199                 :    * Gets string type pref value with raw return value of nsIPrefBranch.
     200                 :    *
     201                 :    * @param aPref       A pref name.
     202                 :    * @param aResult     Must not be NULL.  The value is never modified when
     203                 :    *                    these methods fail.
     204                 :    */
     205                 :   static nsresult GetCString(const char* aPref, nsACString* aResult);
     206                 :   static nsresult GetString(const char* aPref, nsAString* aResult);
     207                 :   static nsresult GetLocalizedCString(const char* aPref, nsACString* aResult);
     208                 :   static nsresult GetLocalizedString(const char* aPref, nsAString* aResult);
     209                 : 
     210                 :   static nsresult GetComplex(const char* aPref, const nsIID &aType,
     211                 :                              void** aResult);
     212                 : 
     213                 :   /**
     214                 :    * Sets various type pref values.
     215                 :    */
     216                 :   static nsresult SetBool(const char* aPref, bool aValue);
     217                 :   static nsresult SetInt(const char* aPref, PRInt32 aValue);
     218                 :   static nsresult SetUint(const char* aPref, PRUint32 aValue)
     219                 :   {
     220                 :     return SetInt(aPref, static_cast<PRInt32>(aValue));
     221                 :   }
     222                 :   static nsresult SetCString(const char* aPref, const char* aValue);
     223                 :   static nsresult SetCString(const char* aPref, const nsACString &aValue);
     224                 :   static nsresult SetString(const char* aPref, const PRUnichar* aValue);
     225                 :   static nsresult SetString(const char* aPref, const nsAString &aValue);
     226                 : 
     227                 :   static nsresult SetComplex(const char* aPref, const nsIID &aType,
     228                 :                              nsISupports* aValue);
     229                 : 
     230                 :   /**
     231                 :    * Clears user set pref.
     232                 :    */
     233                 :   static nsresult ClearUser(const char* aPref);
     234                 : 
     235                 :   /**
     236                 :    * Whether the pref has a user value or not.
     237                 :    */
     238                 :   static bool HasUserValue(const char* aPref);
     239                 : 
     240                 :   /**
     241                 :    * Adds/Removes the observer for the root pref branch.
     242                 :    * The observer is referenced strongly if AddStrongObserver is used.  On the
     243                 :    * other hand, it is referenced weakly, if AddWeakObserver is used.
     244                 :    * See nsIPrefBran2.idl for the detail.
     245                 :    */
     246                 :   static nsresult AddStrongObserver(nsIObserver* aObserver, const char* aPref);
     247                 :   static nsresult AddWeakObserver(nsIObserver* aObserver, const char* aPref);
     248                 :   static nsresult RemoveObserver(nsIObserver* aObserver, const char* aPref);
     249                 : 
     250                 :   /**
     251                 :    * Adds/Removes two or more observers for the root pref branch.
     252                 :    * Pass to aPrefs an array of const char* whose last item is NULL.
     253                 :    */
     254                 :   static nsresult AddStrongObservers(nsIObserver* aObserver,
     255                 :                                      const char** aPrefs);
     256                 :   static nsresult AddWeakObservers(nsIObserver* aObserver,
     257                 :                                    const char** aPrefs);
     258                 :   static nsresult RemoveObservers(nsIObserver* aObserver,
     259                 :                                   const char** aPrefs);
     260                 : 
     261                 :   /**
     262                 :    * Registers/Unregisters the callback function for the aPref.
     263                 :    */
     264                 :   static nsresult RegisterCallback(PrefChangedFunc aCallback,
     265                 :                                    const char* aPref,
     266                 :                                    void* aClosure = nsnull);
     267                 :   static nsresult UnregisterCallback(PrefChangedFunc aCallback,
     268                 :                                      const char* aPref,
     269                 :                                      void* aClosure = nsnull);
     270                 : 
     271                 :   /**
     272                 :    * Adds the aVariable to cache table.  aVariable must be a pointer for a
     273                 :    * static variable.  The value will be modified when the pref value is
     274                 :    * changed but note that even if you modified it, the value isn't assigned to
     275                 :    * the pref.
     276                 :    */
     277                 :   static nsresult AddBoolVarCache(bool* aVariable,
     278                 :                                   const char* aPref,
     279                 :                                   bool aDefault = false);
     280                 :   static nsresult AddIntVarCache(PRInt32* aVariable,
     281                 :                                  const char* aPref,
     282                 :                                  PRInt32 aDefault = 0);
     283                 :   static nsresult AddUintVarCache(PRUint32* aVariable,
     284                 :                                   const char* aPref,
     285                 :                                   PRUint32 aDefault = 0);
     286                 : 
     287                 :   /**
     288                 :    * Gets the default bool, int or uint value of the pref.
     289                 :    * The result is raw result of nsIPrefBranch::Get*Pref().
     290                 :    * If the pref could have any value, you needed to use these methods.
     291                 :    * If not so, you could use below methods.
     292                 :    */
     293                 :   static nsresult GetDefaultBool(const char* aPref, bool* aResult);
     294                 :   static nsresult GetDefaultInt(const char* aPref, PRInt32* aResult);
     295                 :   static nsresult GetDefaultUint(const char* aPref, PRUint32* aResult)
     296                 :   {
     297                 :     return GetDefaultInt(aPref, reinterpret_cast<PRInt32*>(aResult));
     298                 :   }
     299                 : 
     300                 :   /**
     301                 :    * Gets the default bool, int or uint value of the pref directly.
     302                 :    * You can set an invalid value of the pref to aFailedResult.  If these
     303                 :    * methods failed to get the default value, they would return the
     304                 :    * aFailedResult value.
     305                 :    */
     306                 :   static bool GetDefaultBool(const char* aPref, bool aFailedResult)
     307                 :   {
     308                 :     bool result;
     309                 :     return NS_SUCCEEDED(GetDefaultBool(aPref, &result)) ? result :
     310                 :                                                           aFailedResult;
     311                 :   }
     312            1404 :   static PRInt32 GetDefaultInt(const char* aPref, PRInt32 aFailedResult)
     313                 :   {
     314                 :     PRInt32 result;
     315            1404 :     return NS_SUCCEEDED(GetDefaultInt(aPref, &result)) ? result : aFailedResult;
     316                 :   }
     317                 :   static PRUint32 GetDefaultUint(const char* aPref, PRUint32 aFailedResult)
     318                 :   {
     319                 :    return static_cast<PRUint32>(
     320                 :      GetDefaultInt(aPref, static_cast<PRInt32>(aFailedResult)));
     321                 :   }
     322                 : 
     323                 :   /**
     324                 :    * Gets the default value of the char type pref.
     325                 :    * If the get() of the result returned NULL, that meant the value didn't
     326                 :    * have default value.
     327                 :    *
     328                 :    * See the comment at definition at GetString() and GetCString() for more
     329                 :    * details of the result.
     330                 :    */
     331                 :   static nsAdoptingString GetDefaultString(const char* aPref);
     332                 :   static nsAdoptingCString GetDefaultCString(const char* aPref);
     333                 :   static nsAdoptingString GetDefaultLocalizedString(const char* aPref);
     334                 :   static nsAdoptingCString GetDefaultLocalizedCString(const char* aPref);
     335                 : 
     336                 :   static nsresult GetDefaultCString(const char* aPref, nsACString* aResult);
     337                 :   static nsresult GetDefaultString(const char* aPref, nsAString* aResult);
     338                 :   static nsresult GetDefaultLocalizedCString(const char* aPref,
     339                 :                                              nsACString* aResult);
     340                 :   static nsresult GetDefaultLocalizedString(const char* aPref,
     341                 :                                             nsAString* aResult);
     342                 : 
     343                 :   static nsresult GetDefaultComplex(const char* aPref, const nsIID &aType,
     344                 :                                     void** aResult);
     345                 : 
     346                 :   // Used to synchronise preferences between chrome and content processes.
     347                 :   static void MirrorPreferences(nsTArray<PrefTuple,
     348                 :                                 nsTArrayInfallibleAllocator> *aArray);
     349                 :   static bool MirrorPreference(const char *aPref, PrefTuple *aTuple);
     350                 :   static void ClearContentPref(const char *aPref);
     351                 :   static void SetPreference(const PrefTuple *aTuple);
     352                 : 
     353                 : protected:
     354                 :   nsresult NotifyServiceObservers(const char *aSubject);
     355                 :   nsresult UseDefaultPrefFile();
     356                 :   nsresult UseUserPrefFile();
     357                 :   nsresult ReadAndOwnUserPrefFile(nsIFile *aFile);
     358                 :   nsresult ReadAndOwnSharedUserPrefFile(nsIFile *aFile);
     359                 :   nsresult SavePrefFileInternal(nsIFile* aFile);
     360                 :   nsresult WritePrefFile(nsIFile* aFile);
     361                 :   nsresult MakeBackupPrefFile(nsIFile *aFile);
     362                 : 
     363                 : private:
     364                 :   nsCOMPtr<nsIFile>        mCurrentFile;
     365                 : 
     366                 :   static Preferences*      sPreferences;
     367                 :   static nsIPrefBranch*    sRootBranch;
     368                 :   static nsIPrefBranch*    sDefaultRootBranch;
     369                 :   static bool              sShutdown;
     370                 : 
     371                 :   /**
     372                 :    * Init static members.  TRUE if it succeeded.  Otherwise, FALSE.
     373                 :    */
     374                 :   static bool InitStaticMembers();
     375                 : };
     376                 : 
     377                 : } // namespace mozilla
     378                 : 
     379                 : #endif // mozilla_Preferences_h

Generated by: LCOV version 1.7