summaryrefslogtreecommitdiffstats
path: root/toolkit/components/extensions/mozIExtensionAPIRequestHandling.idl
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--toolkit/components/extensions/mozIExtensionAPIRequestHandling.idl192
1 files changed, 192 insertions, 0 deletions
diff --git a/toolkit/components/extensions/mozIExtensionAPIRequestHandling.idl b/toolkit/components/extensions/mozIExtensionAPIRequestHandling.idl
new file mode 100644
index 0000000000..0a2e3c7a5d
--- /dev/null
+++ b/toolkit/components/extensions/mozIExtensionAPIRequestHandling.idl
@@ -0,0 +1,192 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "nsISupports.idl"
+
+interface nsIPrincipal;
+
+[scriptable, builtinclass, uuid(e6862533-8844-4207-a6ab-04748a29d859)]
+interface mozIExtensionServiceWorkerInfo : nsISupports
+{
+ readonly attribute nsIPrincipal principal;
+ readonly attribute AString scriptURL;
+ readonly attribute AString clientInfoId;
+ readonly attribute unsigned long long descriptorId;
+};
+
+[scriptable, uuid(876d45db-5c1b-4c9b-9148-1c86b33d120b)]
+interface mozIExtensionListenerCallOptions : nsISupports
+{
+ cenum APIObjectType: 8 {
+ // Default: no api object is prepended to the event listener call arguments.
+ NONE,
+
+ // A runtime.Port instance is prepended to the event listener call arguments.
+ RUNTIME_PORT,
+ };
+
+ readonly attribute mozIExtensionListenerCallOptions_APIObjectType apiObjectType;
+
+ // An optional javascript object that should provide the attributes expected
+ // by related apiObjectType webidl dictionary type (e.g. ExtensionPortDescriptor
+ // if apiObjectType is RUNTIME_PORT).
+ readonly attribute jsval apiObjectDescriptor;
+
+ // An optional boolean to be set to true if the api object should be
+ // prepended to the rest of the call arguments (by default it is appended).
+ readonly attribute bool apiObjectPrepended;
+
+ cenum CallbackType: 8 {
+ // Default: no callback argument is passed to the call to the event listener.
+ CALLBACK_NONE,
+
+ // The event listener will be called with a function as the last call parameter
+ // that behaves like the runtime.onMessage's sendResponse parameter:
+ //
+ // - if the event listener already returned false, sendResponse calls are ignored
+ // (if it has not been called already)
+ // - if the event listener already returned true, the first sendResponse call
+ // resolves the promise returned by the mozIExtensionCallback method call
+ // - if the event listener already returned a Promise, sendResponse calls
+ // are ignored
+ CALLBACK_SEND_RESPONSE,
+ };
+
+ attribute mozIExtensionListenerCallOptions_CallbackType callbackType;
+};
+
+[scriptable, builtinclass, uuid(e68e3c19-1b35-4112-8faa-5c5b84086a5b)]
+interface mozIExtensionEventListener : nsISupports
+{
+ [implicit_jscontext, can_run_script]
+ Promise callListener(
+ in Array<jsval> args,
+ [optional] in mozIExtensionListenerCallOptions listenerCallOptions);
+};
+
+[scriptable, builtinclass, uuid(0fee1c8f-e363-46a6-bd0c-d3c3338e2534)]
+interface mozIExtensionAPIRequest : nsISupports
+{
+ AUTF8String toString();
+
+ // Determine what the caller and receiver should expect, e.g. what should
+ // be provided to the API request handler and what to expect it to return.
+ cenum RequestType: 8 {
+ CALL_FUNCTION,
+ CALL_FUNCTION_NO_RETURN,
+ CALL_FUNCTION_ASYNC,
+ ADD_LISTENER,
+ REMOVE_LISTENER,
+ GET_PROPERTY,
+ };
+
+ // The type of the request.
+ readonly attribute AUTF8String requestType;
+
+ // WebExtension API namespace (e.g. tabs, runtime, webRequest, ...)
+ readonly attribute AUTF8String apiNamespace;
+ // method or event name
+ readonly attribute AUTF8String apiName;
+
+ // API object type (e.g. Port, Panel, ...) and its unique id, this
+ // properties are used by API requests originated by an API object
+ // instance (like a runtime Port returned by browser.runtime.connect).
+ readonly attribute AUTF8String apiObjectType;
+ readonly attribute AUTF8String apiObjectId;
+
+ // An array of API call arguments.
+ [implicit_jscontext] readonly attribute jsval args;
+
+ // A property to store on the request objects the arguments normalized
+ // based on the API jsonschema, so that they are being propagated along
+ // with the API request object.
+ // TODO: change this attribute to a readonly attribute if we moved
+ // the parameters validation and normalization to the C++ layer.
+ [implicit_jscontext] attribute jsval normalizedArgs;
+
+ // The caller SavedFrame (only set for calls originated off of the main thread
+ // from a service worker).
+ [implicit_jscontext] readonly attribute jsval callerSavedFrame;
+
+ // Set for requests coming from an extension service worker.
+ readonly attribute mozIExtensionServiceWorkerInfo serviceWorkerInfo;
+
+ // Set for `addListener`/`removeListener` API requests.
+ readonly attribute mozIExtensionEventListener eventListener;
+};
+
+[scriptable, uuid(59fd4097-d88e-40fd-8664-fedd8ab67ab6)]
+interface mozIExtensionAPIRequestResult : nsISupports
+{
+ cenum ResultType: 8 {
+ // The result is a value to be returned as a result for the API request.
+ // The value attribute can be set to:
+ // - a structured clonable result value (which may be the result of the
+ // API call itself, or be used by the API method webidl implementation
+ // to initialize a webidl object to return to the caller, e.g.
+ // ExtensionPort returned by a call to browser.runtime.connect())
+ // - an error object (which also include internally converted to and from
+ // ClonedErrorHolder to make it structured clonable).
+ // - a Promise (which can be resolved to a structured clonable value or
+ // an error object).
+ RETURN_VALUE,
+
+ // The result is an error object that should be thrown as an extension error
+ // to the caller on the thread that originated the request.
+ EXTENSION_ERROR,
+ };
+
+ readonly attribute mozIExtensionAPIRequestResult_ResultType type;
+ readonly attribute jsval value;
+};
+
+[scriptable, uuid(0c61bd33-0557-43a2-9497-96c449f39e33)]
+interface mozIExtensionAPIRequestHandler : nsISupports
+{
+ /**
+ * Handle an API request originated from the WebExtensions webidl API
+ * bindings.
+ *
+ * @param extension An instance of the WebExtensionPolicy webidl interface.
+ * @param apiRequest An instance of the mozIExtensionAPIRequest xpcom interface.
+ *
+ * @return mozIExtensionAPIRequestResult
+ * JS value returned by the API request handler, may contain a value
+ * (the result of the API call or a WebIDL dictionary that is used to
+ * initialize WebIDL-based API object, e.g. ExtensionPort) or
+ * an Error to be throw on the thread that originated the request.
+ */
+ void handleAPIRequest(in nsISupports extension,
+ in mozIExtensionAPIRequest apiRequest,
+ [optional, retval] out mozIExtensionAPIRequestResult apiRequestResult);
+
+ /**
+ * A method called when an extension background service worker is initialized and
+ * ready to execute its main script.
+ *
+ * @param extension An instance of the WebExtensionPolicy webidl interface.
+ * @param serviceWorkerInfo
+ */
+ void initExtensionWorker(in nsISupports extension,
+ in mozIExtensionServiceWorkerInfo serviceWorkerInfo);
+
+ /**
+ * A method called when an extension background service worker has loaded its
+ * main script.
+ *
+ * @param extension An instance of the WebExtensionPolicy webidl interface.
+ * @param serviceWorkerDescriptorId
+ */
+ void onExtensionWorkerLoaded(in nsISupports extension,
+ in unsigned long long serviceWorkerDescriptorId);
+
+ /**
+ * A method called when an extension background service worker is destroyed.
+ *
+ * @param extension An instance of the WebExtensionPolicy webidl interface.
+ * @param serviceWorkerDescriptorId
+ */
+ void onExtensionWorkerDestroyed(in nsISupports extension,
+ in unsigned long long serviceWorkerDescriptorId);
+};