1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/exthelper/extIApplication.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,416 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIVariant;
1.11 +interface extIPreference;
1.12 +interface extISessionStorage;
1.13 +
1.14 +
1.15 +/**
1.16 + * Interface that gives simplified access to the console
1.17 + */
1.18 +[scriptable, uuid(ae8482e0-aa5a-11db-abbd-0800200c9a66)]
1.19 +interface extIConsole : nsISupports
1.20 +{
1.21 + /**
1.22 + * Sends a given string to the console.
1.23 + * @param aMsg
1.24 + * The text to send to the console
1.25 + */
1.26 + void log(in AString aMsg);
1.27 +
1.28 + /**
1.29 + * Opens the error console window. The console window
1.30 + * is focused if already open.
1.31 + */
1.32 + void open();
1.33 +};
1.34 +
1.35 +
1.36 +/**
1.37 + * Interface holds information about an event.
1.38 + */
1.39 +[scriptable, function, uuid(05281820-ab62-11db-abbd-0800200c9a66)]
1.40 +interface extIEventItem : nsISupports
1.41 +{
1.42 + /**
1.43 + * The name of the event
1.44 + */
1.45 + readonly attribute AString type;
1.46 +
1.47 + /**
1.48 + * Can hold extra details and data associated with the event. This
1.49 + * is optional and event specific. If the event does not send extra
1.50 + * details, this is null.
1.51 + */
1.52 + readonly attribute nsIVariant data;
1.53 +
1.54 + /**
1.55 + * Cancels the event if it is cancelable.
1.56 + */
1.57 + void preventDefault();
1.58 +};
1.59 +
1.60 +
1.61 +/**
1.62 + * Interface used as a callback for listening to events.
1.63 + */
1.64 +[scriptable, function, uuid(2dfe3a50-ab2f-11db-abbd-0800200c9a66)]
1.65 +interface extIEventListener : nsISupports
1.66 +{
1.67 + /**
1.68 + * This method is called whenever an event occurs of the type for which
1.69 + * the extIEventListener interface was registered.
1.70 + *
1.71 + * @param aEvent
1.72 + * The extIEventItem associated with the event.
1.73 + */
1.74 + void handleEvent(in extIEventItem aEvent);
1.75 +};
1.76 +
1.77 +
1.78 +/**
1.79 + * Interface for supporting custom events.
1.80 + */
1.81 +[scriptable, uuid(3a8ec9d0-ab19-11db-abbd-0800200c9a66)]
1.82 +interface extIEvents : nsISupports
1.83 +{
1.84 + /**
1.85 + * Adds an event listener to the list. If multiple identical event listeners
1.86 + * are registered on the same event target with the same parameters the
1.87 + * duplicate instances are discarded. They do not cause the EventListener
1.88 + * to be called twice and since they are discarded they do not need to be
1.89 + * removed with the removeListener method.
1.90 + *
1.91 + * @param aEvent
1.92 + * The name of an event
1.93 + * @param aListener
1.94 + * The reference to a listener
1.95 + */
1.96 + void addListener(in AString aEvent, in extIEventListener aListener);
1.97 +
1.98 + /**
1.99 + * Removes an event listener from the list. Calling remove
1.100 + * with arguments which do not identify any currently registered
1.101 + * event listener has no effect.
1.102 + * @param aEvent
1.103 + * The name of an event
1.104 + * @param aListener
1.105 + * The reference to a listener
1.106 + */
1.107 + void removeListener(in AString aEvent, in extIEventListener aListener);
1.108 +};
1.109 +
1.110 +
1.111 +/**
1.112 + * Interface for simplified access to preferences. The interface has a
1.113 + * predefined root preference branch. The root branch is set based on the
1.114 + * context of the owner. For example, an extension's preferences have a root
1.115 + * of "extensions.<extensionid>.", while the application level preferences
1.116 + * have an empty root. All preference "aName" parameters used in this interface
1.117 + * are relative to the root branch.
1.118 + */
1.119 +[scriptable, uuid(ce697d40-aa5a-11db-abbd-0800200c9a66)]
1.120 +interface extIPreferenceBranch : nsISupports
1.121 +{
1.122 + /**
1.123 + * The name of the branch root.
1.124 + */
1.125 + readonly attribute AString root;
1.126 +
1.127 + /**
1.128 + * Array of extIPreference listing all preferences in this branch.
1.129 + */
1.130 + readonly attribute nsIVariant all;
1.131 +
1.132 + /**
1.133 + * The events object for the preferences
1.134 + * supports: "change"
1.135 + */
1.136 + readonly attribute extIEvents events;
1.137 +
1.138 + /**
1.139 + * Check to see if a preference exists.
1.140 + * @param aName
1.141 + * The name of preference
1.142 + * @returns true if the preference exists, false if not
1.143 + */
1.144 + boolean has(in AString aName);
1.145 +
1.146 + /**
1.147 + * Gets an object representing a preference
1.148 + * @param aName
1.149 + * The name of preference
1.150 + * @returns a preference object, or null if the preference does not exist
1.151 + */
1.152 + extIPreference get(in AString aName);
1.153 +
1.154 + /**
1.155 + * Gets the value of a preference. Returns a default value if
1.156 + * the preference does not exist.
1.157 + * @param aName
1.158 + * The name of preference
1.159 + * @param aDefaultValue
1.160 + * The value to return if preference does not exist
1.161 + * @returns value of the preference or the given default value if preference
1.162 + * does not exists.
1.163 + */
1.164 + nsIVariant getValue(in AString aName, in nsIVariant aDefaultValue);
1.165 +
1.166 + /**
1.167 + * Sets the value of a storage item with the given name.
1.168 + * @param aName
1.169 + * The name of an item
1.170 + * @param aValue
1.171 + * The value to assign to the item
1.172 + */
1.173 + void setValue(in AString aName, in nsIVariant aValue);
1.174 +
1.175 + /**
1.176 + * Resets all preferences in a branch back to their default values.
1.177 + */
1.178 + void reset();
1.179 +};
1.180 +
1.181 +/**
1.182 + * Interface for accessing a single preference. The data is not cached.
1.183 + * All reads access the current state of the preference.
1.184 + */
1.185 +[scriptable, uuid(2C7462E2-72C2-4473-9007-0E6AE71E23CA)]
1.186 +interface extIPreference : nsISupports
1.187 +{
1.188 + /**
1.189 + * The name of the preference.
1.190 + */
1.191 + readonly attribute AString name;
1.192 +
1.193 + /**
1.194 + * A string representing the type of preference (String, Boolean, or Number).
1.195 + */
1.196 + readonly attribute AString type;
1.197 +
1.198 + /**
1.199 + * Get/Set the value of the preference.
1.200 + */
1.201 + attribute nsIVariant value;
1.202 +
1.203 + /**
1.204 + * Get the locked state of the preference. Set to a boolean value to (un)lock it.
1.205 + */
1.206 + attribute boolean locked;
1.207 +
1.208 + /**
1.209 + * Check if a preference has been modified by the user, or not.
1.210 + */
1.211 + readonly attribute boolean modified;
1.212 +
1.213 + /**
1.214 + * The preference branch that contains this preference.
1.215 + */
1.216 + readonly attribute extIPreferenceBranch branch;
1.217 +
1.218 + /**
1.219 + * The events object for this preference.
1.220 + * supports: "change"
1.221 + */
1.222 + readonly attribute extIEvents events;
1.223 +
1.224 + /**
1.225 + * Resets a preference back to its default values.
1.226 + */
1.227 + void reset();
1.228 +};
1.229 +
1.230 +
1.231 +/**
1.232 + * Interface representing an extension
1.233 + */
1.234 +[scriptable, uuid(10cee02c-f6e0-4d61-ab27-c16572b18c46)]
1.235 +interface extIExtension : nsISupports
1.236 +{
1.237 + /**
1.238 + * The id of the extension.
1.239 + */
1.240 + readonly attribute AString id;
1.241 +
1.242 + /**
1.243 + * The name of the extension.
1.244 + */
1.245 + readonly attribute AString name;
1.246 +
1.247 + /**
1.248 + * Check if the extension is currently enabled, or not.
1.249 + */
1.250 + readonly attribute boolean enabled;
1.251 +
1.252 + /**
1.253 + * The version number of the extension.
1.254 + */
1.255 + readonly attribute AString version;
1.256 +
1.257 + /**
1.258 + * Indicates whether this is the extension's first run after install
1.259 + */
1.260 + readonly attribute boolean firstRun;
1.261 +
1.262 + /**
1.263 + * The preferences object for the extension. Defaults to the
1.264 + * "extensions.<extensionid>." branch.
1.265 + */
1.266 + readonly attribute extIPreferenceBranch prefs;
1.267 +
1.268 + /**
1.269 + * The storage object for the extension.
1.270 + */
1.271 + readonly attribute extISessionStorage storage;
1.272 +
1.273 + /**
1.274 + * The events object for the extension.
1.275 + * supports: "uninstall"
1.276 + */
1.277 + readonly attribute extIEvents events;
1.278 +};
1.279 +
1.280 +/**
1.281 + * Interface representing a list of all installed extensions
1.282 + */
1.283 +[scriptable, uuid(de281930-aa5a-11db-abbd-0800200c9a66)]
1.284 +interface extIExtensions : nsISupports
1.285 +{
1.286 + /**
1.287 + * Array of extIExtension listing all extensions in the application.
1.288 + */
1.289 + readonly attribute nsIVariant all;
1.290 +
1.291 + /**
1.292 + * Determines if an extension exists with the given id.
1.293 + * @param aId
1.294 + * The id of an extension
1.295 + * @returns true if an extension exists with the given id,
1.296 + * false otherwise.
1.297 + */
1.298 + boolean has(in AString aId);
1.299 +
1.300 + /**
1.301 + * Gets a extIExtension object for an extension.
1.302 + * @param aId
1.303 + * The id of an extension
1.304 + * @returns An extension object or null if no extension exists
1.305 + * with the given id.
1.306 + */
1.307 + extIExtension get(in AString aId);
1.308 +};
1.309 +
1.310 +/**
1.311 + * Interface representing a callback that receives an array of extIExtensions
1.312 + */
1.313 +[scriptable, function, uuid(2571cbb5-550d-4400-8038-75df9b553f98)]
1.314 +interface extIExtensionsCallback : nsISupports
1.315 +{
1.316 + void callback(in nsIVariant extensions);
1.317 +};
1.318 +
1.319 +/**
1.320 + * Interface representing a simple storage system
1.321 + */
1.322 +[scriptable, uuid(0787ac44-29b9-4889-b97f-13573aec6971)]
1.323 +interface extISessionStorage : nsISupports
1.324 +{
1.325 + /**
1.326 + * The events object for the storage
1.327 + * supports: "change"
1.328 + */
1.329 + readonly attribute extIEvents events;
1.330 +
1.331 + /**
1.332 + * Determines if a storage item exists with the given name.
1.333 + * @param aName
1.334 + * The name of an item
1.335 + * @returns true if an item exists with the given name,
1.336 + * false otherwise.
1.337 + */
1.338 + boolean has(in AString aName);
1.339 +
1.340 + /**
1.341 + * Sets the value of a storage item with the given name.
1.342 + * @param aName
1.343 + * The name of an item
1.344 + * @param aValue
1.345 + * The value to assign to the item
1.346 + */
1.347 + void set(in AString aName, in nsIVariant aValue);
1.348 +
1.349 + /**
1.350 + * Gets the value of a storage item with the given name. Returns a
1.351 + * default value if the item does not exist.
1.352 + * @param aName
1.353 + * The name of an item
1.354 + * @param aDefaultValue
1.355 + * The value to return if no item exists with the given name
1.356 + * @returns value of the item or the given default value if no item
1.357 + * exists with the given name.
1.358 + */
1.359 + nsIVariant get(in AString aName, in nsIVariant aDefaultValue);
1.360 +};
1.361 +
1.362 +[scriptable, uuid(2be87909-0817-4292-acfa-fc39be53be3f)]
1.363 +interface extIApplication : nsISupports
1.364 +{
1.365 + /**
1.366 + * The id of the application.
1.367 + */
1.368 + readonly attribute AString id;
1.369 +
1.370 + /**
1.371 + * The name of the application.
1.372 + */
1.373 + readonly attribute AString name;
1.374 +
1.375 + /**
1.376 + * The version number of the application.
1.377 + */
1.378 + readonly attribute AString version;
1.379 +
1.380 + /**
1.381 + * The console object for the application.
1.382 + */
1.383 + readonly attribute extIConsole console;
1.384 +
1.385 + /**
1.386 + * The extensions object for the application. Contains a list
1.387 + * of all installed extensions.
1.388 + */
1.389 + void getExtensions(in extIExtensionsCallback aCallback);
1.390 +
1.391 + /**
1.392 + * The preferences object for the application. Defaults to an empty
1.393 + * root branch.
1.394 + */
1.395 + readonly attribute extIPreferenceBranch prefs;
1.396 +
1.397 + /**
1.398 + * The storage object for the application.
1.399 + */
1.400 + readonly attribute extISessionStorage storage;
1.401 +
1.402 + /**
1.403 + * The events object for the application.
1.404 + * supports: "load", "ready", "quit", "unload"
1.405 + */
1.406 + readonly attribute extIEvents events;
1.407 +
1.408 + /**
1.409 + * Quits the application (if nobody objects to quit-application-requested).
1.410 + * @returns whether quitting will proceed
1.411 + */
1.412 + boolean quit();
1.413 +
1.414 + /**
1.415 + * Restarts the application (if nobody objects to quit-application-requested).
1.416 + * @returns whether restarting will proceed
1.417 + */
1.418 + boolean restart();
1.419 +};
