1 /* ***** BEGIN LICENSE BLOCK *****
2 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
3 *
4 * The contents of this file are subject to the Mozilla Public License Version
5 * 1.1 (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
7 * http://www.mozilla.org/MPL/
8 *
9 * Software distributed under the License is distributed on an "AS IS" basis,
10 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
11 * for the specific language governing rights and limitations under the
12 * License.
13 *
14 * The Original Code is FUEL.
15 *
16 * The Initial Developer of the Original Code is Mozilla Corporation.
17 * Portions created by the Initial Developer are Copyright (C) 2006
18 * the Initial Developer. All Rights Reserved.
19 *
20 * Contributor(s):
21 * Joey Minta <jminta@gmail.com> (Original Author)
22 * Mark Finkle <mfinkle@mozilla.com>
23 * John Resig <jresig@mozilla.com>
24 *
25 * Alternatively, the contents of this file may be used under the terms of
26 * either the GNU General Public License Version 2 or later (the "GPL"), or
27 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
28 * in which case the provisions of the GPL or the LGPL are applicable instead
29 * of those above. If you wish to allow use of your version of this file only
30 * under the terms of either the GPL or the LGPL, and not to allow others to
31 * use your version of this file under the terms of the MPL, indicate your
32 * decision by deleting the provisions above and replace them with the notice
33 * and other provisions required by the GPL or the LGPL. If you do not delete
34 * the provisions above, a recipient may use your version of this file under
35 * the terms of any one of the MPL, the GPL or the LGPL.
36 *
37 * ***** END LICENSE BLOCK ***** */
38
39 #include "nsISupports.idl"
40
41 interface nsIVariant;
42 interface extIPreference;
43 interface extISessionStorage;
44
45
46 /**
47 * Interface that gives simplified access to the console
48 */
49 [scriptable, uuid(ae8482e0-aa5a-11db-abbd-0800200c9a66)]
50 interface extIConsole : nsISupports
51 {
52 /**
53 * Sends a given string to the console.
54 * @param aMsg
55 * The text to send to the console
56 */
57 void log(in AString aMsg);
58
59 /**
60 * Opens the error console window. The console window
61 * is focused if already open.
62 */
63 void open();
64 };
65
66
67 /**
68 * Interface holds information about an event.
69 */
70 [scriptable, function, uuid(05281820-ab62-11db-abbd-0800200c9a66)]
71 interface extIEventItem : nsISupports
72 {
73 /**
74 * The name of the event
75 */
76 readonly attribute AString type;
77
78 /**
79 * Can hold extra details and data associated with the event. This
80 * is optional and event specific. If the event does not send extra
81 * details, this is null.
82 */
83 readonly attribute nsIVariant data;
84
85 /**
86 * Cancels the event if it is cancelable.
87 */
88 void preventDefault();
89 };
90
91
92 /**
93 * Interface used as a callback for listening to events.
94 */
95 [scriptable, function, uuid(2dfe3a50-ab2f-11db-abbd-0800200c9a66)]
96 interface extIEventListener : nsISupports
97 {
98 /**
99 * This method is called whenever an event occurs of the type for which
100 * the extIEventListener interface was registered.
101 *
102 * @param aEvent
103 * The extIEventItem associated with the event.
104 */
105 void handleEvent(in extIEventItem aEvent);
106 };
107
108
109 /**
110 * Interface for supporting custom events.
111 */
112 [scriptable, uuid(3a8ec9d0-ab19-11db-abbd-0800200c9a66)]
113 interface extIEvents : nsISupports
114 {
115 /**
116 * Adds an event listener to the list. If multiple identical event listeners
117 * are registered on the same event target with the same parameters the
118 * duplicate instances are discarded. They do not cause the EventListener
119 * to be called twice and since they are discarded they do not need to be
120 * removed with the removeListener method.
121 *
122 * @param aEvent
123 * The name of an event
124 * @param aListener
125 * The reference to a listener
126 */
127 void addListener(in AString aEvent, in extIEventListener aListener);
128
129 /**
130 * Removes an event listener from the list. Calling remove
131 * with arguments which do not identify any currently registered
132 * event listener has no effect.
133 * @param aEvent
134 * The name of an event
135 * @param aListener
136 * The reference to a listener
137 */
138 void removeListener(in AString aEvent, in extIEventListener aListener);
139 };
140
141
142 /**
143 * Interface for simplified access to preferences. The interface has a
144 * predefined root preference branch. The root branch is set based on the
145 * context of the owner. For example, an extension's preferences have a root
146 * of "extensions.<extensionid>.", while the application level preferences
147 * have an empty root. All preference "aName" parameters used in this interface
148 * are relative to the root branch.
149 */
150 [scriptable, uuid(ce697d40-aa5a-11db-abbd-0800200c9a66)]
151 interface extIPreferenceBranch : nsISupports
152 {
153 /**
154 * The name of the branch root.
155 */
156 readonly attribute AString root;
157
158 /**
159 * Array of extIPreference listing all preferences in this branch.
160 */
161 readonly attribute nsIVariant all;
162
163 /**
164 * The events object for the preferences
165 * supports: "change"
166 */
167 readonly attribute extIEvents events;
168
169 /**
170 * Check to see if a preference exists.
171 * @param aName
172 * The name of preference
173 * @returns true if the preference exists, false if not
174 */
175 boolean has(in AString aName);
176
177 /**
178 * Gets an object representing a preference
179 * @param aName
180 * The name of preference
181 * @returns a preference object, or null if the preference does not exist
182 */
183 extIPreference get(in AString aName);
184
185 /**
186 * Gets the value of a preference. Returns a default value if
187 * the preference does not exist.
188 * @param aName
189 * The name of preference
190 * @param aDefaultValue
191 * The value to return if preference does not exist
192 * @returns value of the preference or the given default value if preference
193 * does not exists.
194 */
195 nsIVariant getValue(in AString aName, in nsIVariant aDefaultValue);
196
197 /**
198 * Sets the value of a storage item with the given name.
199 * @param aName
200 * The name of an item
201 * @param aValue
202 * The value to assign to the item
203 */
204 void setValue(in AString aName, in nsIVariant aValue);
205
206 /**
207 * Resets all preferences in a branch back to their default values.
208 */
209 void reset();
210 };
211
212 /**
213 * Interface for accessing a single preference. The data is not cached.
214 * All reads access the current state of the preference.
215 */
216 [scriptable, uuid(2C7462E2-72C2-4473-9007-0E6AE71E23CA)]
217 interface extIPreference : nsISupports
218 {
219 /**
220 * The name of the preference.
221 */
222 readonly attribute AString name;
223
224 /**
225 * A string representing the type of preference (String, Boolean, or Number).
226 */
227 readonly attribute AString type;
228
229 /**
230 * Get/Set the value of the preference.
231 */
232 attribute nsIVariant value;
233
234 /**
235 * Get the locked state of the preference. Set to a boolean value to (un)lock it.
236 */
237 attribute boolean locked;
238
239 /**
240 * Check if a preference has been modified by the user, or not.
241 */
242 readonly attribute boolean modified;
243
244 /**
245 * The preference branch that contains this preference.
246 */
247 readonly attribute extIPreferenceBranch branch;
248
249 /**
250 * The events object for this preference.
251 * supports: "change"
252 */
253 readonly attribute extIEvents events;
254
255 /**
256 * Resets a preference back to its default values.
257 */
258 void reset();
259 };
260
261
262 /**
263 * Interface representing an extension
264 */
265 [scriptable, uuid(10cee02c-f6e0-4d61-ab27-c16572b18c46)]
266 interface extIExtension : nsISupports
267 {
268 /**
269 * The id of the extension.
270 */
271 readonly attribute AString id;
272
273 /**
274 * The name of the extension.
275 */
276 readonly attribute AString name;
277
278 /**
279 * Check if the extension is currently enabled, or not.
280 */
281 readonly attribute boolean enabled;
282
283 /**
284 * The version number of the extension.
285 */
286 readonly attribute AString version;
287
288 /**
289 * Indicates whether this is the extension's first run after install
290 */
291 readonly attribute boolean firstRun;
292
293 /**
294 * The preferences object for the extension. Defaults to the
295 * "extensions.<extensionid>." branch.
296 */
297 readonly attribute extIPreferenceBranch prefs;
298
299 /**
300 * The storage object for the extension.
301 */
302 readonly attribute extISessionStorage storage;
303
304 /**
305 * The events object for the extension.
306 * supports: "uninstall"
307 */
308 readonly attribute extIEvents events;
309 };
310
311
312 /**
313 * Interface representing a list of all installed extensions
314 */
315 [scriptable, uuid(de281930-aa5a-11db-abbd-0800200c9a66)]
316 interface extIExtensions : nsISupports
317 {
318 /**
319 * Array of extIExtension listing all extensions in the application.
320 */
321 readonly attribute nsIVariant all;
322
323 /**
324 * Determines if an extension exists with the given id.
325 * @param aId
326 * The id of an extension
327 * @returns true if an extension exists with the given id,
328 * false otherwise.
329 */
330 boolean has(in AString aId);
331
332 /**
333 * Gets a extIExtension object for an extension.
334 * @param aId
335 * The id of an extension
336 * @returns An extension object or null if no extension exists
337 * with the given id.
338 */
339 extIExtension get(in AString aId);
340 };
341
342 /**
343 * Interface representing a simple storage system
344 */
345 [scriptable, uuid(0787ac44-29b9-4889-b97f-13573aec6971)]
346 interface extISessionStorage : nsISupports
347 {
348 /**
349 * The events object for the storage
350 * supports: "change"
351 */
352 readonly attribute extIEvents events;
353
354 /**
355 * Determines if a storage item exists with the given name.
356 * @param aName
357 * The name of an item
358 * @returns true if an item exists with the given name,
359 * false otherwise.
360 */
361 boolean has(in AString aName);
362
363 /**
364 * Sets the value of a storage item with the given name.
365 * @param aName
366 * The name of an item
367 * @param aValue
368 * The value to assign to the item
369 */
370 void set(in AString aName, in nsIVariant aValue);
371
372 /**
373 * Gets the value of a storage item with the given name. Returns a
374 * default value if the item does not exist.
375 * @param aName
376 * The name of an item
377 * @param aDefaultValue
378 * The value to return if no item exists with the given name
379 * @returns value of the item or the given default value if no item
380 * exists with the given name.
381 */
382 nsIVariant get(in AString aName, in nsIVariant aDefaultValue);
383 };
384
385 [scriptable, uuid(ba9442ee-7070-44fb-8157-c111e1fa70b6)]
386 interface extIApplication : nsISupports
387 {
388 /**
389 * The id of the application.
390 */
391 readonly attribute AString id;
392
393 /**
394 * The name of the application.
395 */
396 readonly attribute AString name;
397
398 /**
399 * The version number of the application.
400 */
401 readonly attribute AString version;
402
403 /**
404 * The console object for the application.
405 */
406 readonly attribute extIConsole console;
407
408 /**
409 * The extensions object for the application. Contains a list
410 * of all installed extensions.
411 */
412 readonly attribute extIExtensions extensions;
413
414 /**
415 * The preferences object for the application. Defaults to an empty
416 * root branch.
417 */
418 readonly attribute extIPreferenceBranch prefs;
419
420 /**
421 * The storage object for the application.
422 */
423 readonly attribute extISessionStorage storage;
424
425 /**
426 * The events object for the application.
427 * supports: "load", "ready", "quit", "unload"
428 */
429 readonly attribute extIEvents events;
430 };