recursal/MDN huggingface dataset:
pkcs11.installModule()
======================

Installs the named PKCS #11 module, making it available to Firefox.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let installing = browser.pkcs11.installModule(
  name,              // string
  flags              // integer
)
```

### Parameters

`name`

`string`. Name of the module to install. This must match the `name` property in the PKCS #11 manifest for the module.

`flags` Optional

`integer`. Flags to pass to the module.

### Return value

A `Promise` that will be fulfilled with no arguments once the module is installed.

If the module could not be found or some other error occurs, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Installs a module, then lists its slots and list the tokens they contain:


```js
function onInstalled() {
  return browser.pkcs11.getModuleSlots("my\_module");
}

function onGotSlots(slots) {
  for (const slot of slots) {
    console.log(`Slot: ${slot.name}`);
    if (slot.token) {
      console.log(`Contains token: ${slot.token.name}`);
    } else {
      console.log("Is empty");
    }
  }
}

browser.pkcs11.installModule("my\_module").then(onInstalled).then(onGotSlots);
```
runtime.OnInstalledReason
=========================

The reason that the `runtime.onInstalled` event is being dispatched.

Type
----

Values of this type are strings. Possible values are:

`"install"`

The extension was installed.

`"update"`

The extension was updated to a new version.

`"browser_update"` or, for Chrome, `"chrome_update"`

The browser was updated to a new version.

`"shared_module_update"`

Another extension, which contains a module used by this extension, was updated.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.onSuspend
=================

Sent to the event page just before it is unloaded. This gives the extension an opportunity to do some cleanup. Note that since the page is unloading, any asynchronous operations started while handling this event are not guaranteed to complete.

**Note:** If something prevents the event page from being unloaded, the `runtime.onSuspendCanceled` event will be sent and the page won't be unloaded.

Syntax
------


```js
browser.runtime.onSuspend.addListener(listener)
browser.runtime.onSuspend.removeListener(listener)
browser.runtime.onSuspend.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Listen for suspend events:


```js
function handleSuspend() {
  console.log("Suspending event page");
  // handle cleanup
}

browser.runtime.onSuspend.addListener(handleSuspend);
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.onUpdateAvailable
=========================

Fired when an update to the extension is available. This event enables an extension to delay an update: for example, because it is in the middle of some operation which should not be interrupted.

If the extension is not listening for this event when an update becomes available, the extension is reloaded immediately and the update is applied. If the extension is listening, then the update will be applied the next time the extension is reloaded. This happens if:

* the browser is restarted
* the extension is disabled and re-enabled
* the extension explicitly reloads itself by calling `runtime.reload()`.
Syntax
------


```js
browser.runtime.onUpdateAvailable.addListener()
browser.runtime.onUpdateAvailable.removeListener(listener)
browser.runtime.onUpdateAvailable.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`details`

`object`. Contains a single property, a string named `version`, which represents the version number of the update.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Listen for `UpdateAvailable` events:


```js
function handleUpdateAvailable(details) {
  console.log(details.version);
  // Proceed to upgrade the add-on
  browser.runtime.reload();
}

browser.runtime.onUpdateAvailable.addListener(handleUpdateAvailable);
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.id
==========

The ID of the extension.

Syntax
------


```js
let myAddonId = browser.runtime.id;
```

### Value

A `string` representing the add-on ID. If the extension specifies an ID in its `browser_specific_settings` manifest.json key, `runtime.id` contains that value. Otherwise, `runtime.id` contains the ID that was generated for the extension.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.requestUpdateCheck()
============================

Checks to see if an update for the extension is available.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let requestingCheck = browser.runtime.requestUpdateCheck()
```

### Parameters

None.

### Return value

A `Promise` that is fulfilled with an object with the result of the update request.

`result`

An object with the following properties:

`status`

`runtime.RequestUpdateCheckStatus`. The result of the update check.

`version` Optional

`string`. The update's version, if `status` is `update_available`.


Examples
--------

Request an update and log the new version if one is available:


```js
function onRequested(result) {
  console.log(result.status);
  if (result.status === "update\_available") {
    console.log(result.version);
  }
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let requestingCheck = browser.runtime.requestUpdateCheck();
requestingCheck.then(onRequested, onError);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.RequestUpdateCheckStatus
================================

Result of a call to `runtime.requestUpdateCheck()`.

Type
----

Values of this type are strings. Possible values are:

`"throttled"`

Update is throttled.

`"no_update"`

No update is available.

`"update_available"`

An update of the extension is available.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.getManifest()
=====================

Get the complete manifest.json file, deserialized from JSON to an object.

Syntax
------


```js
browser.runtime.getManifest()
```

### Parameters

None.

### Return value

An `object` representing the manifest.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Get the manifest and log the "name" property:


```js
let manifest = browser.runtime.getManifest();
console.log(manifest.name);
```

### Example extensions

* runtime-examples

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.getPlatformInfo()
=========================

Returns information about the current platform. This can only be called in the background script context.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let getting = browser.runtime.getPlatformInfo()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with a `runtime.PlatformInfo` value representing the current platform.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Get and log the platform OS:


```js
function gotPlatformInfo(info) {
  console.log(info.os);
}

let gettingInfo = browser.runtime.getPlatformInfo();
gettingInfo.then(gotPlatformInfo);
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.getURL()
================

Given a relative path from the manifest.json to a resource packaged with the extension, return a fully-qualified URL.

This function does *not* check that the resource actually exists at that URL.

Syntax
------


```js
browser.runtime.getURL(
  path // string
)
```

### Parameters

`path`

`string`. A relative path from the manifest.json to a resource packaged with the extension.

### Return value

`string`. The fully-qualified URL to the resource.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Given a file packaged with the extension at "beasts/frog.html", get the full URL like this:


```js
let fullURL = browser.runtime.getURL("beasts/frog.html");
console.log(fullURL);
// Returns something like:
// moz-extension://2c127fa4-62c7-7e4f-90e5-472b45eecfdc/beasts/frog.html
```

### Example extensions

* devtools-panels
* find-across-tabs
* permissions

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.sendNativeMessage()
===========================

Sends a single message from an extension to a native application.

This takes two mandatory parameters: the name of the native application and a JSON object which is the message to send it. The browser will launch the native application and deliver the message.

This is an asynchronous function that returns a `Promise`. The first message sent by the native application is treated as a response to the `sendNativeMessage()` call, and the promise will be fulfilled with this message as a parameter. Note that you can't use `runtime.onMessage` to get responses from the application: you must use the callback function instead.

A new instance of the application is launched for call to `runtime.sendNativeMessage()`. The browser will terminate the native application after getting a reply. To terminate a native application, the browser will close the pipe, give the process a few seconds to exit gracefully, and then kill it if it has not exited.

For more information, see Native messaging.

Syntax
------


```js
let sending = browser.runtime.sendNativeMessage(
  application,             // string
  message                  // object
)
```

### Parameters

`application`

`string`. The name of the native application. This must match the "name" property in the native application's manifest file.

`message`

`object`. A JSON object that will be sent to the native application.

### Return value

A `Promise`. If the sender sent a response, this will be fulfilled with the response as a JSON object. Otherwise it will be fulfilled with no arguments. If an error occurs while connecting to the native application, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Here's a background script that sends a "ping" message to the "ping\_pong" app and logs the response, whenever the user clicks the browser action:


```js
function onResponse(response) {
  console.log(`Received ${response}`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

/\*
On a click on the browser action, send the app a message.
\*/
browser.browserAction.onClicked.addListener(() => {
  console.log("Sending: ping");
  let sending = browser.runtime.sendNativeMessage("ping\_pong", "ping");
  sending.then(onResponse, onError);
});
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.connectNative()
=======================

Connects the extension to a native application on the user's computer. This takes the name of a native application as a parameter. It starts the native application and returns a `runtime.Port` object to the caller. The caller can then use the `Port` to exchange messages with the native application using `Port.postMessage()` and `port.onMessage`. The native application will run until it exits itself, or the caller calls `Port.disconnect()`, or the page that created the `Port` is destroyed. Once the `Port` is disconnected the browser will give the process a few seconds to exit gracefully, and then kill it if it has not exited.

For more information, see Native messaging.

Syntax
------


```js
let port = browser.runtime.connectNative(
  application // string
)
```

### Parameters

`application`

`string`. The name of the native application to connect to. This must match the "name" property in the native application's manifest file.

### Return value

A `runtime.Port` object. The port which the caller can use to exchange messages with the native application.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This example connects to the native application "ping\_pong" and starts listening for messages from it. It also sends the native application a message when the user clicks a browser action icon:


```js
/\*
On startup, connect to the "ping\_pong" app.
\*/
let port = browser.runtime.connectNative("ping\_pong");

/\*
Listen for messages from the app.
\*/
port.onMessage.addListener((response) => {
  console.log(`Received: ${response}`);
});

/\*
On a click on the browser action, send the app a message.
\*/
browser.browserAction.onClicked.addListener(() => {
  console.log("Sending: ping");
  port.postMessage("ping");
});
```

### Example extensions

* native-messaging

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.getBackgroundPage()
===========================

Retrieves the `Window` object for the background page running inside the current extension. If the background page is non-persistent (an event page) and it is not running, the background page is started.

This provides a convenient way for other privileged extension scripts to get direct access to the background script's scope. This enables them to access variables or call functions defined in that scope. "Privileged script" here includes scripts running in options pages, or scripts running in browser action or page action popups, but does *not* include content scripts.

Note that variables that were declared using `const` or `let` do not appear in the `Window` object returned by this function.

**Also note that this method cannot be used in a private window in Firefox**—it always returns `null`. For more info see related bug at bugzilla.

If the background page is an event page, the system will ensure it is loaded before resolving the promise.

This is an asynchronous function that returns a `Promise`.

**Note:** In Firefox, this method cannot be used in Private Browsing mode — it always returns `null`. For more info see Firefox bug 1329304.

In Chrome, this method is available only with persistent background pages, which are not available in Manifest V3, so consider using Manifest V2. See the this for details.

Consider using `runtime.sendMessage()` or `runtime.connect()`, which work correctly in both scenarios above.

Syntax
------


```js
let gettingPage = browser.runtime.getBackgroundPage()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with the `Window` object for the background page, if there is one. If the extension does not include a background page, the promise is rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Suppose a background script defines a function `foo()`:


```js
// background.js

function foo() {
  console.log("I'm defined in background.js");
}
```


A script running in a popup can call this function directly like this:


```js
// popup.js

function onGot(page) {
  page.foo();
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let getting = browser.runtime.getBackgroundPage();
getting.then(onGot, onError);
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.PlatformOs
==================

The operating system the browser is running on.

Type
----

Values of this type are strings. Possible values are:

`"mac"`

The underlying operating system is macOS.

`"ios"`

The underlying operating system is iOS/iPadOS.

`"win"`

The underlying operating system is Windows.

`"android"`

The underlying operating system is Android.

`"cros"`

The underlying operating system is ChromeOS.

`"linux"`

The underlying operating system is Linux.

`"openbsd"`

The underlying operating system is Open/FreeBSD.

`"fuchsia"`

The underlying operating system is Fuchsia.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.getFrameId()
====================

Returns the frame ID of any window global or frame element when called from a content script or extension page, including background pages.

Syntax
------


```js
let gettingInfo = browser.runtime.getFrameId(
  target               // object
)
```

### Parameters

`target`

A WindowProxy or a browsing context container Element (iframe, frame, embed, or object) for the target frame.

### Return value

Returns the frame ID of the target frame, or -1 if the frame doesn't exist.

Examples
--------

This code recursively walks descendant frames and gets parent frame IDs.


```js
const parents = {};

function visit(win) {
  const frameId = browser.runtime.getFrameId(win);
  const parentId = browser.runtime.getFrameId(win.parent);
  parents[frameId] = win.parent !== win ? parentId : -1;

  try {
    const frameEl = browser.runtime.getFrameId(win.frameElement);
    browser.test.assertEq(frameId, frameEl, "frameElement id correct");
  } catch (e) {
    // Can't access a cross-origin .frameElement.
  }

  for (const frame of win.frames) {
    visit(frame);
  }
}
visit(window);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.
runtime.getBrowserInfo()
========================

Returns information about the browser in which the extension is installed.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingInfo = browser.runtime.getBrowserInfo()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with an object which has the following properties:

`name`

string value representing the browser name, for example "Firefox".

`vendor`

string value representing the browser's vendor, for example "Mozilla".

`version`

string representing the browser's version, for example "51.0" or "51.0a2".

`buildID`

string representing the specific build of the browser, for example "20161018004015".

Examples
--------

Get and log the browser's name:


```js
function gotBrowserInfo(info) {
  console.log(info.name);
}

let gettingInfo = browser.runtime.getBrowserInfo();
gettingInfo.then(gotBrowserInfo);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.
runtime.onStartup
=================

Fired when a profile that has this extension installed first starts up. This event is not fired when a private browsing (incognito) profile is started, even if this extension is operating in 'split' incognito mode.

**Note:**
 When using an event page or background service worker, the extension must add a listener to `runtime.onStartup` on the event page for the event page to be executed at least once per browser session.


Syntax
------


```js
browser.runtime.onStartup.addListener(listener)
browser.runtime.onStartup.removeListener(listener)
browser.runtime.onStartup.hasListener(listener)
```

### Event Functions

All events have three functions:

`addListener(listener)`

Adds a `listener` to the calling event.

`removeListener(listener)`

Stop listening to the calling event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for the calling event. Returns `true` if it is listening, `false` otherwise.

### Parameters

The only parameter is `listener`, used for any of the above functions.

`listener`

The function called when this event occurs.

Examples
--------

Open https://giphy.com/explore/cat when the browser starts up:


```js
function handleStartup() {
  browser.tabs.create({
    url: "https://giphy.com/explore/cat",
  });
}

browser.runtime.onStartup.addListener(handleStartup);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.