modules/libpref/public/nsIPrefService.idl@6474c204b198
modules/libpref/public/nsIPrefService.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "nsISupports.idl"
7 #include "nsIPrefBranch.idl"
9 %{C++
10 struct PrefTuple;
11 #include "nsTArrayForwardDeclare.h"
12 %}
14 [ptr] native nsPreferencesArrayPtr(nsTArray<PrefTuple>);
15 [ptr] native nsPreferencePtr(PrefTuple);
16 [ptr] native nsPreferencePtrConst(const PrefTuple);
18 interface nsIFile;
20 /**
21 * The nsIPrefService interface is the main entry point into the back end
22 * preferences management library. The preference service is directly
23 * responsible for the management of the preferences files and also facilitates
24 * access to the preference branch object which allows the direct manipulation
25 * of the preferences themselves.
26 *
27 * @see nsIPrefBranch
28 */
30 [scriptable, uuid(decb9cc7-c08f-4ea5-be91-a8fc637ce2d2)]
31 interface nsIPrefService : nsISupports
32 {
33 /**
34 * Called to read in the preferences specified in a user preference file.
35 *
36 * @param aFile The file to be read.
37 *
38 * @note
39 * If nullptr is passed in for the aFile parameter the default preferences
40 * file(s) [prefs.js, user.js] will be read and processed.
41 *
42 * @throws Error File failed to read or contained invalid data.
43 *
44 * @see savePrefFile
45 * @see nsIFile
46 */
47 void readUserPrefs(in nsIFile aFile);
49 /**
50 * Called to completely flush and re-initialize the preferences system.
51 *
52 * @throws Error The preference service failed to restart correctly.
53 */
54 void resetPrefs();
56 /**
57 * Called to reset all preferences with user set values back to the
58 * application default values.
59 */
60 void resetUserPrefs();
62 /**
63 * Called to write current preferences state to a file.
64 *
65 * @param aFile The file to be written.
66 *
67 * @note
68 * If nullptr is passed in for the aFile parameter the preference data is
69 * written out to the current preferences file (usually prefs.js.)
70 *
71 * @throws Error File failed to write.
72 *
73 * @see readUserPrefs
74 * @see nsIFile
75 */
76 void savePrefFile(in nsIFile aFile);
78 /**
79 * Call to get a Preferences "Branch" which accesses user preference data.
80 * Using a Set method on this object will always create or set a user
81 * preference value. When using a Get method a user set value will be
82 * returned if one exists, otherwise a default value will be returned.
83 *
84 * @param aPrefRoot The preference "root" on which to base this "branch".
85 * For example, if the root "browser.startup." is used, the
86 * branch will be able to easily access the preferences
87 * "browser.startup.page", "browser.startup.homepage", or
88 * "browser.startup.homepage_override" by simply requesting
89 * "page", "homepage", or "homepage_override". nullptr or ""
90 * may be used to access to the entire preference "tree".
91 *
92 * @return nsIPrefBranch The object representing the requested branch.
93 *
94 * @see getDefaultBranch
95 */
96 nsIPrefBranch getBranch(in string aPrefRoot);
98 /**
99 * Call to get a Preferences "Branch" which accesses only the default
100 * preference data. Using a Set method on this object will always create or
101 * set a default preference value. When using a Get method a default value
102 * will always be returned.
103 *
104 * @param aPrefRoot The preference "root" on which to base this "branch".
105 * For example, if the root "browser.startup." is used, the
106 * branch will be able to easily access the preferences
107 * "browser.startup.page", "browser.startup.homepage", or
108 * "browser.startup.homepage_override" by simply requesting
109 * "page", "homepage", or "homepage_override". nullptr or ""
110 * may be used to access to the entire preference "tree".
111 *
112 * @note
113 * Few consumers will want to create default branch objects. Many of the
114 * branch methods do nothing on a default branch because the operations only
115 * make sense when applied to user set preferences.
116 *
117 * @return nsIPrefBranch The object representing the requested default branch.
118 *
119 * @see getBranch
120 */
121 nsIPrefBranch getDefaultBranch(in string aPrefRoot);
123 };
125 %{C++
127 #define NS_PREFSERVICE_CID \
128 { /* {1cd91b88-1dd2-11b2-92e1-ed22ed298000} */ \
129 0x91ca2441, \
130 0x050f, \
131 0x4f7c, \
132 { 0x9d, 0xf8, 0x75, 0xb4, 0x0e, 0xa4, 0x01, 0x56 } \
133 }
135 #define NS_PREFSERVICE_CONTRACTID "@mozilla.org/preferences-service;1"
137 /**
138 * Notification sent before reading the default user preferences files.
139 */
140 #define NS_PREFSERVICE_READ_TOPIC_ID "prefservice:before-read-userprefs"
142 /**
143 * Notification sent when resetPrefs has been called, but before the actual
144 * reset process occurs.
145 */
146 #define NS_PREFSERVICE_RESET_TOPIC_ID "prefservice:before-reset"
148 /**
149 * Notification sent when after reading app-provided default
150 * preferences, but before user profile override defaults or extension
151 * defaults are loaded.
152 */
153 #define NS_PREFSERVICE_APPDEFAULTS_TOPIC_ID "prefservice:after-app-defaults"
155 %}
