modules/libpref/public/nsIPrefService.idl

   1 /* -*- Mode: IDL; 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  *   Alec Flett <alecf@netscape.com>
  24  *   Brian Nesse <bnesse@netscape.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 #include "nsISupports.idl"
  41 #include "nsIPrefBranch.idl"
  42
  43 interface nsIFile;
  44
  45 /**
  46  * The nsIPrefService interface is the main entry point into the back end
  47  * preferences management library. The preference service is directly
  48  * responsible for the management of the preferences files and also facilitates
  49  * access to the preference branch object which allows the direct manipulation
  50  * of the preferences themselves.
  51  *
  52  * @see nsIPrefBranch
  53  *
  54  * @status FROZEN
  55  */
  56
  57 [scriptable, uuid(decb9cc7-c08f-4ea5-be91-a8fc637ce2d2)]
  58 interface nsIPrefService : nsISupports
  59 {
  60   /**
  61    * Called to read in the preferences specified in a user preference file.
  62    *
  63    * @param aFile The file to be read.
  64    *
  65    * @note
  66    * If nsnull is passed in for the aFile parameter the default preferences
  67    * file(s) [prefs.js, user.js] will be read and processed.
  68    *
  69    * @return NS_OK File was read and processed.
  70    * @return Other File failed to read or contained invalid data.
  71    *
  72    * @see savePrefFile
  73    * @see nsIFile
  74    */
  75   void readUserPrefs(in nsIFile aFile);
  76
  77   /**
  78    * Called to completely flush and re-initialize the preferences system.
  79    *
  80    * @return NS_OK The preference service was re-initialized correctly.
  81    * @return Other The preference service failed to restart correctly.
  82    */
  83   void resetPrefs();
  84
  85   /**
  86    * Called to reset all preferences with user set values back to the
  87    * application default values.
  88    *
  89    * @return NS_OK Always.
  90    */
  91   void resetUserPrefs();
  92
  93   /**
  94    * Called to write current preferences state to a file.
  95    *
  96    * @param aFile The file to be written.
  97    *
  98    * @note
  99    * If nsnull is passed in for the aFile parameter the preference data is
 100    * written out to the current preferences file (usually prefs.js.)
 101    *
 102    * @return NS_OK File was written.
 103    * @return Other File failed to write.
 104    *
 105    * @see readUserPrefs
 106    * @see nsIFile
 107    */
 108   void savePrefFile(in nsIFile aFile);
 109
 110
 111   /**
 112    * Call to get a Preferences "Branch" which accesses user preference data.
 113    * Using a Set method on this object will always create or set a user
 114    * preference value. When using a Get method a user set value will be
 115    * returned if one exists, otherwise a default value will be returned.
 116    *
 117    * @param aPrefRoot The preference "root" on which to base this "branch".
 118    *                  For example, if the root "browser.startup." is used, the
 119    *                  branch will be able to easily access the preferences
 120    *                  "browser.startup.page", "browser.startup.homepage", or
 121    *                  "browser.startup.homepage_override" by simply requesting
 122    *                  "page", "homepage", or "homepage_override". nsnull or ""
 123    *                  may be used to access to the entire preference "tree".
 124    *
 125    * @return nsIPrefBranch The object representing the requested branch.
 126    *
 127    * @see getDefaultBranch
 128    */
 129   nsIPrefBranch getBranch(in string aPrefRoot);
 130
 131   /**
 132    * Call to get a Preferences "Branch" which accesses only the default
 133    * preference data. Using a Set method on this object will always create or
 134    * set a default preference value. When using a Get method a default value
 135    * will always be returned.
 136    *
 137    * @param aPrefRoot The preference "root" on which to base this "branch".
 138    *                  For example, if the root "browser.startup." is used, the
 139    *                  branch will be able to easily access the preferences
 140    *                  "browser.startup.page", "browser.startup.homepage", or
 141    *                  "browser.startup.homepage_override" by simply requesting
 142    *                  "page", "homepage", or "homepage_override". nsnull or ""
 143    *                  may be used to access to the entire preference "tree".
 144    *
 145    * @note
 146    * Few consumers will want to create default branch objects. Many of the
 147    * branch methods do nothing on a default branch because the operations only
 148    * make sense when applied to user set preferences.
 149    *
 150    * @return nsIPrefBranch The object representing the requested default branch.
 151    *
 152    * @see getBranch
 153    */
 154   nsIPrefBranch getDefaultBranch(in string aPrefRoot);
 155
 156 };
 157
 158 %{C++
 159
 160 #define NS_PREFSERVICE_CID                             \
 161   { /* {1cd91b88-1dd2-11b2-92e1-ed22ed298000} */       \
 162     0x1cd91b88,                                        \
 163     0x1dd2,                                            \
 164     0x11b2,                                            \
 165     { 0x92, 0xe1, 0xed, 0x22, 0xed, 0x29, 0x80, 0x00 } \
 166   }
 167
 168 #define NS_PREFSERVICE_CONTRACTID "@mozilla.org/preferences-service;1"
 169 #define NS_PREFSERVICE_CLASSNAME "Preferences Server"
 170
 171 /**
 172  * Notification sent before reading the default user preferences files.
 173  */
 174 #define NS_PREFSERVICE_READ_TOPIC_ID "prefservice:before-read-userprefs"
 175
 176 /**
 177  * Notification sent when resetPrefs has been called, but before the actual
 178  * reset process occurs.
 179  */
 180 #define NS_PREFSERVICE_RESET_TOPIC_ID "prefservice:before-reset"
 181
 182 /**
 183  * Notification sent when after reading app-provided default
 184  * preferences, but before user profile override defaults or extension
 185  * defaults are loaded.
 186  */
 187 #define NS_PREFSERVICE_APPDEFAULTS_TOPIC_ID "prefservice:after-app-defaults"
 188
 189 %}