toolkit/components/exthelper/extIApplication.idl@925c144e1f1f
toolkit/components/exthelper/extIApplication.idl
Fri, 16 Jan 2015 18:13:44 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Fri, 16 Jan 2015 18:13:44 +0100
- branch
- TOR_BUG_9701
- changeset 14
- 925c144e1f1f
- permissions
- -rw-r--r--
Integrate suggestion from review to improve consistency with existing code.
1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5 #include "nsISupports.idl"
7 interface nsIVariant;
8 interface extIPreference;
9 interface extISessionStorage;
12 /**
13 * Interface that gives simplified access to the console
14 */
15 [scriptable, uuid(ae8482e0-aa5a-11db-abbd-0800200c9a66)]
16 interface extIConsole : nsISupports
17 {
18 /**
19 * Sends a given string to the console.
20 * @param aMsg
21 * The text to send to the console
22 */
23 void log(in AString aMsg);
25 /**
26 * Opens the error console window. The console window
27 * is focused if already open.
28 */
29 void open();
30 };
33 /**
34 * Interface holds information about an event.
35 */
36 [scriptable, function, uuid(05281820-ab62-11db-abbd-0800200c9a66)]
37 interface extIEventItem : nsISupports
38 {
39 /**
40 * The name of the event
41 */
42 readonly attribute AString type;
44 /**
45 * Can hold extra details and data associated with the event. This
46 * is optional and event specific. If the event does not send extra
47 * details, this is null.
48 */
49 readonly attribute nsIVariant data;
51 /**
52 * Cancels the event if it is cancelable.
53 */
54 void preventDefault();
55 };
58 /**
59 * Interface used as a callback for listening to events.
60 */
61 [scriptable, function, uuid(2dfe3a50-ab2f-11db-abbd-0800200c9a66)]
62 interface extIEventListener : nsISupports
63 {
64 /**
65 * This method is called whenever an event occurs of the type for which
66 * the extIEventListener interface was registered.
67 *
68 * @param aEvent
69 * The extIEventItem associated with the event.
70 */
71 void handleEvent(in extIEventItem aEvent);
72 };
75 /**
76 * Interface for supporting custom events.
77 */
78 [scriptable, uuid(3a8ec9d0-ab19-11db-abbd-0800200c9a66)]
79 interface extIEvents : nsISupports
80 {
81 /**
82 * Adds an event listener to the list. If multiple identical event listeners
83 * are registered on the same event target with the same parameters the
84 * duplicate instances are discarded. They do not cause the EventListener
85 * to be called twice and since they are discarded they do not need to be
86 * removed with the removeListener method.
87 *
88 * @param aEvent
89 * The name of an event
90 * @param aListener
91 * The reference to a listener
92 */
93 void addListener(in AString aEvent, in extIEventListener aListener);
95 /**
96 * Removes an event listener from the list. Calling remove
97 * with arguments which do not identify any currently registered
98 * event listener has no effect.
99 * @param aEvent
100 * The name of an event
101 * @param aListener
102 * The reference to a listener
103 */
104 void removeListener(in AString aEvent, in extIEventListener aListener);
105 };
108 /**
109 * Interface for simplified access to preferences. The interface has a
110 * predefined root preference branch. The root branch is set based on the
111 * context of the owner. For example, an extension's preferences have a root
112 * of "extensions.<extensionid>.", while the application level preferences
113 * have an empty root. All preference "aName" parameters used in this interface
114 * are relative to the root branch.
115 */
116 [scriptable, uuid(ce697d40-aa5a-11db-abbd-0800200c9a66)]
117 interface extIPreferenceBranch : nsISupports
118 {
119 /**
120 * The name of the branch root.
121 */
122 readonly attribute AString root;
124 /**
125 * Array of extIPreference listing all preferences in this branch.
126 */
127 readonly attribute nsIVariant all;
129 /**
130 * The events object for the preferences
131 * supports: "change"
132 */
133 readonly attribute extIEvents events;
135 /**
136 * Check to see if a preference exists.
137 * @param aName
138 * The name of preference
139 * @returns true if the preference exists, false if not
140 */
141 boolean has(in AString aName);
143 /**
144 * Gets an object representing a preference
145 * @param aName
146 * The name of preference
147 * @returns a preference object, or null if the preference does not exist
148 */
149 extIPreference get(in AString aName);
151 /**
152 * Gets the value of a preference. Returns a default value if
153 * the preference does not exist.
154 * @param aName
155 * The name of preference
156 * @param aDefaultValue
157 * The value to return if preference does not exist
158 * @returns value of the preference or the given default value if preference
159 * does not exists.
160 */
161 nsIVariant getValue(in AString aName, in nsIVariant aDefaultValue);
163 /**
164 * Sets the value of a storage item with the given name.
165 * @param aName
166 * The name of an item
167 * @param aValue
168 * The value to assign to the item
169 */
170 void setValue(in AString aName, in nsIVariant aValue);
172 /**
173 * Resets all preferences in a branch back to their default values.
174 */
175 void reset();
176 };
178 /**
179 * Interface for accessing a single preference. The data is not cached.
180 * All reads access the current state of the preference.
181 */
182 [scriptable, uuid(2C7462E2-72C2-4473-9007-0E6AE71E23CA)]
183 interface extIPreference : nsISupports
184 {
185 /**
186 * The name of the preference.
187 */
188 readonly attribute AString name;
190 /**
191 * A string representing the type of preference (String, Boolean, or Number).
192 */
193 readonly attribute AString type;
195 /**
196 * Get/Set the value of the preference.
197 */
198 attribute nsIVariant value;
200 /**
201 * Get the locked state of the preference. Set to a boolean value to (un)lock it.
202 */
203 attribute boolean locked;
205 /**
206 * Check if a preference has been modified by the user, or not.
207 */
208 readonly attribute boolean modified;
210 /**
211 * The preference branch that contains this preference.
212 */
213 readonly attribute extIPreferenceBranch branch;
215 /**
216 * The events object for this preference.
217 * supports: "change"
218 */
219 readonly attribute extIEvents events;
221 /**
222 * Resets a preference back to its default values.
223 */
224 void reset();
225 };
228 /**
229 * Interface representing an extension
230 */
231 [scriptable, uuid(10cee02c-f6e0-4d61-ab27-c16572b18c46)]
232 interface extIExtension : nsISupports
233 {
234 /**
235 * The id of the extension.
236 */
237 readonly attribute AString id;
239 /**
240 * The name of the extension.
241 */
242 readonly attribute AString name;
244 /**
245 * Check if the extension is currently enabled, or not.
246 */
247 readonly attribute boolean enabled;
249 /**
250 * The version number of the extension.
251 */
252 readonly attribute AString version;
254 /**
255 * Indicates whether this is the extension's first run after install
256 */
257 readonly attribute boolean firstRun;
259 /**
260 * The preferences object for the extension. Defaults to the
261 * "extensions.<extensionid>." branch.
262 */
263 readonly attribute extIPreferenceBranch prefs;
265 /**
266 * The storage object for the extension.
267 */
268 readonly attribute extISessionStorage storage;
270 /**
271 * The events object for the extension.
272 * supports: "uninstall"
273 */
274 readonly attribute extIEvents events;
275 };
277 /**
278 * Interface representing a list of all installed extensions
279 */
280 [scriptable, uuid(de281930-aa5a-11db-abbd-0800200c9a66)]
281 interface extIExtensions : nsISupports
282 {
283 /**
284 * Array of extIExtension listing all extensions in the application.
285 */
286 readonly attribute nsIVariant all;
288 /**
289 * Determines if an extension exists with the given id.
290 * @param aId
291 * The id of an extension
292 * @returns true if an extension exists with the given id,
293 * false otherwise.
294 */
295 boolean has(in AString aId);
297 /**
298 * Gets a extIExtension object for an extension.
299 * @param aId
300 * The id of an extension
301 * @returns An extension object or null if no extension exists
302 * with the given id.
303 */
304 extIExtension get(in AString aId);
305 };
307 /**
308 * Interface representing a callback that receives an array of extIExtensions
309 */
310 [scriptable, function, uuid(2571cbb5-550d-4400-8038-75df9b553f98)]
311 interface extIExtensionsCallback : nsISupports
312 {
313 void callback(in nsIVariant extensions);
314 };
316 /**
317 * Interface representing a simple storage system
318 */
319 [scriptable, uuid(0787ac44-29b9-4889-b97f-13573aec6971)]
320 interface extISessionStorage : nsISupports
321 {
322 /**
323 * The events object for the storage
324 * supports: "change"
325 */
326 readonly attribute extIEvents events;
328 /**
329 * Determines if a storage item exists with the given name.
330 * @param aName
331 * The name of an item
332 * @returns true if an item exists with the given name,
333 * false otherwise.
334 */
335 boolean has(in AString aName);
337 /**
338 * Sets the value of a storage item with the given name.
339 * @param aName
340 * The name of an item
341 * @param aValue
342 * The value to assign to the item
343 */
344 void set(in AString aName, in nsIVariant aValue);
346 /**
347 * Gets the value of a storage item with the given name. Returns a
348 * default value if the item does not exist.
349 * @param aName
350 * The name of an item
351 * @param aDefaultValue
352 * The value to return if no item exists with the given name
353 * @returns value of the item or the given default value if no item
354 * exists with the given name.
355 */
356 nsIVariant get(in AString aName, in nsIVariant aDefaultValue);
357 };
359 [scriptable, uuid(2be87909-0817-4292-acfa-fc39be53be3f)]
360 interface extIApplication : nsISupports
361 {
362 /**
363 * The id of the application.
364 */
365 readonly attribute AString id;
367 /**
368 * The name of the application.
369 */
370 readonly attribute AString name;
372 /**
373 * The version number of the application.
374 */
375 readonly attribute AString version;
377 /**
378 * The console object for the application.
379 */
380 readonly attribute extIConsole console;
382 /**
383 * The extensions object for the application. Contains a list
384 * of all installed extensions.
385 */
386 void getExtensions(in extIExtensionsCallback aCallback);
388 /**
389 * The preferences object for the application. Defaults to an empty
390 * root branch.
391 */
392 readonly attribute extIPreferenceBranch prefs;
394 /**
395 * The storage object for the application.
396 */
397 readonly attribute extISessionStorage storage;
399 /**
400 * The events object for the application.
401 * supports: "load", "ready", "quit", "unload"
402 */
403 readonly attribute extIEvents events;
405 /**
406 * Quits the application (if nobody objects to quit-application-requested).
407 * @returns whether quitting will proceed
408 */
409 boolean quit();
411 /**
412 * Restarts the application (if nobody objects to quit-application-requested).
413 * @returns whether restarting will proceed
414 */
415 boolean restart();
416 };
