From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- .../extensions/mozIExtensionAPIRequestHandling.idl | 192 +++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 toolkit/components/extensions/mozIExtensionAPIRequestHandling.idl (limited to 'toolkit/components/extensions/mozIExtensionAPIRequestHandling.idl') 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 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); +}; -- cgit v1.2.3