toolkit/components/extensions/mozIExtensionAPIRequestHandling.idl

   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/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIPrincipal;
   8
   9 [scriptable, builtinclass, uuid(e6862533-8844-4207-a6ab-04748a29d859)]
  10 interface mozIExtensionServiceWorkerInfo : nsISupports
  11 {
  12   readonly attribute nsIPrincipal principal;
  13   readonly attribute AString scriptURL;
  14   readonly attribute AString clientInfoId;
  15   readonly attribute unsigned long long descriptorId;
  16 };
  17
  18 [scriptable, uuid(876d45db-5c1b-4c9b-9148-1c86b33d120b)]
  19 interface mozIExtensionListenerCallOptions : nsISupports
  20 {
  21   cenum APIObjectType: 8 {
  22     // Default: no api object is prepended to the event listener call arguments.
  23     NONE,
  24
  25     // A runtime.Port instance is prepended to the event listener call arguments.
  26     RUNTIME_PORT,
  27   };
  28
  29   readonly attribute mozIExtensionListenerCallOptions_APIObjectType apiObjectType;
  30
  31   // An optional javascript object that should provide the attributes expected
  32   // by related apiObjectType webidl dictionary type (e.g. ExtensionPortDescriptor
  33   // if apiObjectType is RUNTIME_PORT).
  34   readonly attribute jsval apiObjectDescriptor;
  35
  36   // An optional boolean to be set to true if the api object should be
  37   // prepended to the rest of the call arguments (by default it is appended).
  38   readonly attribute bool apiObjectPrepended;
  39
  40   cenum CallbackType: 8 {
  41     // Default: no callback argument is passed to the call to the event listener.
  42     CALLBACK_NONE,
  43
  44     // The event listener will be called with a function as the last call parameter
  45     // that behaves like the runtime.onMessage's sendResponse parameter:
  46     //
  47     // - if the event listener already returned false, sendResponse calls are ignored
  48     //   (if it has not been called already)
  49     // - if the event listener already returned true, the first sendResponse call
  50     //   resolves the promise returned by the mozIExtensionCallback method call
  51     // - if the event listener already returned a Promise, sendResponse calls
  52     //   are ignored
  53     CALLBACK_SEND_RESPONSE,
  54   };
  55
  56   attribute mozIExtensionListenerCallOptions_CallbackType callbackType;
  57 };
  58
  59 [scriptable, builtinclass, uuid(e68e3c19-1b35-4112-8faa-5c5b84086a5b)]
  60 interface mozIExtensionEventListener : nsISupports
  61 {
  62   [implicit_jscontext, can_run_script]
  63   Promise callListener(
  64     in Array<jsval> args,
  65     [optional] in mozIExtensionListenerCallOptions listenerCallOptions);
  66 };
  67
  68 [scriptable, builtinclass, uuid(0fee1c8f-e363-46a6-bd0c-d3c3338e2534)]
  69 interface mozIExtensionAPIRequest : nsISupports
  70 {
  71   AUTF8String toString();
  72
  73   // Determine what the caller and receiver should expect, e.g. what should
  74   // be provided to the API request handler and what to expect it to return.
  75   cenum RequestType: 8 {
  76     CALL_FUNCTION,
  77     CALL_FUNCTION_NO_RETURN,
  78     CALL_FUNCTION_ASYNC,
  79     ADD_LISTENER,
  80     REMOVE_LISTENER,
  81     GET_PROPERTY,
  82   };
  83
  84   // The type of the request.
  85   readonly attribute AUTF8String requestType;
  86
  87   // WebExtension API namespace (e.g. tabs, runtime, webRequest, ...)
  88   readonly attribute AUTF8String apiNamespace;
  89   // method or event name
  90   readonly attribute AUTF8String apiName;
  91
  92   // API object type (e.g. Port, Panel, ...) and its unique id, this
  93   // properties are used by API requests originated by an API object
  94   // instance (like a runtime Port returned by browser.runtime.connect).
  95   readonly attribute AUTF8String apiObjectType;
  96   readonly attribute AUTF8String apiObjectId;
  97
  98   // An array of API call arguments.
  99   [implicit_jscontext] readonly attribute jsval args;
 100
 101   // A property to store on the request objects the arguments normalized
 102   // based on the API jsonschema, so that they are being propagated along
 103   // with the API request object.
 104   // TODO: change this attribute to a readonly attribute if we moved
 105   // the parameters validation and normalization to the C++ layer.
 106   [implicit_jscontext] attribute jsval normalizedArgs;
 107
 108   // The caller SavedFrame (only set for calls originated off of the main thread
 109   // from a service worker).
 110   [implicit_jscontext] readonly attribute jsval callerSavedFrame;
 111
 112   // Set for requests coming from an extension service worker.
 113   readonly attribute mozIExtensionServiceWorkerInfo serviceWorkerInfo;
 114
 115   // Set for `addListener`/`removeListener` API requests.
 116   readonly attribute mozIExtensionEventListener eventListener;
 117 };
 118
 119 [scriptable, uuid(59fd4097-d88e-40fd-8664-fedd8ab67ab6)]
 120 interface mozIExtensionAPIRequestResult : nsISupports
 121 {
 122   cenum ResultType: 8 {
 123     // The result is a value to be returned as a result for the API request.
 124     // The value attribute can be set to:
 125     // - a structured clonable result value (which may be the result of the
 126     //   API call itself, or be used by the API method webidl implementation
 127     //   to initialize a webidl object to return to the caller, e.g.
 128     //   ExtensionPort returned by a call to browser.runtime.connect())
 129     // - an error object (which also include internally converted to and from
 130     //   ClonedErrorHolder to make it structured clonable).
 131     // - a Promise (which can be resolved to a structured clonable value or
 132     //   an error object).
 133     RETURN_VALUE,
 134
 135     // The result is an error object that should be thrown as an extension error
 136     // to the caller on the thread that originated the request.
 137     EXTENSION_ERROR,
 138   };
 139
 140   readonly attribute mozIExtensionAPIRequestResult_ResultType type;
 141   readonly attribute jsval value;
 142 };
 143
 144 [scriptable, uuid(0c61bd33-0557-43a2-9497-96c449f39e33)]
 145 interface mozIExtensionAPIRequestHandler : nsISupports
 146 {
 147   /**
 148    * Handle an API request originated from the WebExtensions webidl API
 149    * bindings.
 150    *
 151    * @param extension An instance of the WebExtensionPolicy webidl interface.
 152    * @param apiRequest An instance of the mozIExtensionAPIRequest xpcom interface.
 153    *
 154    * @return mozIExtensionAPIRequestResult
 155    *         JS value returned by the API request handler, may contain a value
 156    *         (the result of the API call or a WebIDL dictionary that is used to
 157    *         initialize WebIDL-based API object, e.g. ExtensionPort) or
 158    *         an Error to be throw on the thread that originated the request.
 159    */
 160   void handleAPIRequest(in nsISupports extension,
 161                         in mozIExtensionAPIRequest apiRequest,
 162                         [optional, retval] out mozIExtensionAPIRequestResult apiRequestResult);
 163
 164   /**
 165    * A method called when an extension background service worker is initialized and
 166    * ready to execute its main script.
 167    *
 168    * @param extension An instance of the WebExtensionPolicy webidl interface.
 169    * @param serviceWorkerInfo
 170    */
 171   void initExtensionWorker(in nsISupports extension,
 172                            in mozIExtensionServiceWorkerInfo serviceWorkerInfo);
 173
 174   /**
 175    * A method called when an extension background service worker has loaded its
 176    * main script.
 177    *
 178    * @param extension An instance of the WebExtensionPolicy webidl interface.
 179    * @param serviceWorkerDescriptorId
 180    */
 181    void onExtensionWorkerLoaded(in nsISupports extension,
 182                                 in unsigned long long serviceWorkerDescriptorId);
 183
 184   /**
 185    * A method called when an extension background service worker is destroyed.
 186    *
 187    * @param extension An instance of the WebExtensionPolicy webidl interface.
 188    * @param serviceWorkerDescriptorId
 189    */
 190    void onExtensionWorkerDestroyed(in nsISupports extension,
 191                                    in unsigned long long serviceWorkerDescriptorId);
 192 };