dom/chrome-webidl/UniFFI.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 // Interface for making UniFFI scaffolding calls
   7 //
   8 // Gecko uses UniFFI to generate privileged JS bindings for Rust components.
   9 // UniFFI defines a C-ABI FFI layer for calling into Rust, called the
  10 // scaffolding. This interface is a bridge that allows the JS code to make
  11 // scaffolding calls
  12 //
  13 // See https://mozilla.github.io/uniffi-rs/ for details.
  14
  15 // Define some ID types to identify various parts of the UDL interfaces.  Using
  16 // these IDs, allow this .webidl file to remain static, but support new
  17 // interfaces.  Using IDs is that the C++ and JS code need to agree on their
  18 // meaning, which is handled by
  19 // toolkit/components/uniffi-bindgen-gecko-js/src/ci_list.rs.
  20
  21 // Identifies a scaffolding function.
  22 typedef unsigned long long UniFFIFunctionId;
  23
  24 // Identifies a pointer type
  25 typedef unsigned long long UniFFIPointerId;
  26
  27 // Identifies a callback interface
  28 typedef unsigned long UniFFICallbackInterfaceId;
  29
  30 // Identifies a method of a callback interface
  31 typedef unsigned long UniFFICallbackMethodId;
  32
  33 // Handle for a callback interface instance
  34 typedef unsigned long long UniFFICallbackObjectHandle;
  35
  36 // Opaque type used to represent a pointer from Rust
  37 [ChromeOnly, Exposed=Window]
  38 interface UniFFIPointer {};
  39
  40 // Types that can be passed or returned from scaffolding functions
  41 //
  42 // - double is used for all numeric types and types which the JS code coerces
  43 //   to an int including Boolean and CallbackInterface.
  44 // - ArrayBuffer is used for RustBuffer
  45 // - UniFFIPointer is used for Arc pointers
  46 typedef (double or ArrayBuffer or UniFFIPointer) UniFFIScaffoldingType;
  47
  48 // The result of a call into UniFFI scaffolding call
  49 enum UniFFIScaffoldingCallCode {
  50    "success",         // Successful return
  51    "error",           // Rust Err return
  52    "internal-error",  // Internal/unexpected error
  53 };
  54
  55 dictionary UniFFIScaffoldingCallResult {
  56     required UniFFIScaffoldingCallCode code;
  57     // For success, this will be the return value for non-void returns
  58     // For error, this will be an ArrayBuffer storing the serialized error value
  59     UniFFIScaffoldingType data;
  60     // For internal-error, this will be a utf-8 string describing the error
  61     ByteString internalErrorMessage;
  62 };
  63
  64 // JS handler for calling a CallbackInterface method.
  65 // The arguments and return value are always packed into an ArrayBuffer
  66 callback UniFFICallbackHandler = undefined (UniFFICallbackObjectHandle objectId, UniFFICallbackMethodId methodId, ArrayBuffer aArgs);
  67
  68 // Functions to facilitate UniFFI scaffolding calls
  69 [ChromeOnly, Exposed=Window]
  70 namespace UniFFIScaffolding {
  71   // Call a scaffolding function on the worker thread.
  72   //
  73   // id is a unique identifier for the function, known to both the C++ and JS code
  74   [Throws]
  75   Promise<UniFFIScaffoldingCallResult> callAsync(UniFFIFunctionId id, UniFFIScaffoldingType... args);
  76
  77   // Call a scaffolding function on the main thread
  78   //
  79   // id is a unique identifier for the function, known to both the C++ and JS code
  80   [Throws]
  81   UniFFIScaffoldingCallResult callSync(UniFFIFunctionId id, UniFFIScaffoldingType... args);
  82
  83   // Read a UniFFIPointer from an ArrayBuffer
  84   //
  85   // id is a unique identifier for the pointer type, known to both the C++ and JS code
  86   [Throws]
  87   UniFFIPointer readPointer(UniFFIPointerId id, ArrayBuffer buff, long position);
  88
  89   // Write a UniFFIPointer to an ArrayBuffer
  90   //
  91   // id is a unique identifier for the pointer type, known to both the C++ and JS code
  92   [Throws]
  93   undefined writePointer(UniFFIPointerId id, UniFFIPointer ptr, ArrayBuffer buff, long position);
  94
  95   // Register the global calblack handler
  96   //
  97   // This will be used to invoke all calls for a CallbackInterface.
  98   // interfaceId is a unique identifier for the callback interface, known to both the C++ and JS code
  99   [Throws]
 100   undefined registerCallbackHandler(UniFFICallbackInterfaceId interfaceId, UniFFICallbackHandler handler);
 101
 102   // Deregister the global calblack handler
 103   //
 104   // This is called at shutdown to clear out the reference to the JS function.
 105   [Throws]
 106   undefined deregisterCallbackHandler(UniFFICallbackInterfaceId interfaceId);
 107 };