recursal/MDN huggingface dataset:
BrowserSetting.onChange
=======================

The `BrowserSetting.onChange` event is fired when the setting is changed.

On Firefox, it doesn't fire if the change has been made through `about:config`.

Syntax
------


```js
BrowserSetting.onChange.addListener(listener)
BrowserSetting.onChange.removeListener(listener)
BrowserSetting.onChange.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)`

Check whether `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 these arguments:

`details`

An `object` containing details of the change that occurred. Its properties are as follows:

`value`

The new value of the setting. The type of this property is determined by the particular setting.

`levelOfControl`

`string`. This represents the way the setting is currently controlled. You can use it to check whether you can modify the setting. See `BrowserSetting.set()` for details. Its value may be any of the following:


|  |  |
| --- | --- |
| `"not_controllable"` | Extensions are not allowed to modify this setting. |
| `"controlled_by_other_extensions"` | 
 Another extension that was installed after this one has modified this
 setting.
  |
| `"controllable_by_this_extension"` | This extension is allowed to modify the setting. |
| `controlled_by_this_extension"` | This extension has already modified the setting. |


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

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

Examples
--------

**Note:** This API is based on Chromium's `chrome.types` API.
clear()
=======

Use `BrowserSetting.clear()` to clear any changes the extension has made to the browser setting. The browser setting will revert to its previous value.

The extension will also give up control of the setting, allowing an extension with lower precedence (that is, an extension that was installed before this one) to modify the setting. See `BrowserSetting.set()` to learn more about controlling settings.

This is an asynchronous function that returns a `Promise`. If clearing the value failed, the promise resolves to `false`. If clearing the value succeeded it resolves to `true`.

Syntax
------


```js
let clearing = setting.clear(
  details     // object
)
```

### Parameters

`details`

An empty object.

### Return value

A `Promise` that will be fulfilled with a `boolean`: `true` if the setting was cleared, `false` otherwise.

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

See `types.BrowserSetting`.

Example
-------

Clear the `webRTCIPHandlingPolicy` setting:


```js
function onCleared(result) {
  if (result) {
    console.log("Setting was cleared");
  } else {
    console.log("Setting was not cleared");
  }
}

let clearing = browser.privacy.network.webRTCIPHandlingPolicy.clear({});
clearing.then(onCleared);
```


**Note:**

This API is based on Chromium's `chrome.types` API.
set()
=====

Use `BrowserSetting.set()` to change the browser setting to a new value.

There are some rules that can restrict when extensions are able to change settings:

* some settings are locked, so they can't be changed by extensions at all
* if multiple extensions try to modify the same setting, then extensions are given a precedence ordering based on when they were installed. More-recently installed extensions have precedence over less-recently installed extension.

This means that if extension X tries to change a setting:

1. If the setting is locked, then the setting is not changed. However, X's change is remembered, and it is stored in a queue, ordered by X's precedence relative to any other extensions that tried to change the setting. If the setting becomes unlocked later on, the first extension in the queue gets to change the setting.
2. Otherwise, if no other extension has already changed the setting, then X succeeds in changing the setting, and is then said to "control" the setting.
3. Otherwise, if a lower-precedence extension Y has already changed the setting, then X succeeds in changing the setting, and now controls the setting. However, Y's change is remembered, and is stored in a queue in precedence order. If X subsequently clears its value, or if X is disabled or uninstalled, the first extension in the queue gets to make its change to the setting.
4. Otherwise, if a higher-precedence extension Z has already changed the setting, then X does not succeed in changing the setting, but its change is queued. If Z subsequently clears its value, or if Z is disabled or uninstalled, the first extension in the queue gets to make its change to the setting.

An extension can find out which of these scenarios applies by examining the "`levelOfControl`" property returned from a call to `BrowserSetting.get()`.

The `BrowserSetting.set()` method returns a Promise that resolves to a boolean: if an attempt to change a setting actually results in the setting being changed (scenarios 2 and 3 above) the boolean is `true`: otherwise it is `false`.

Syntax
------


```js
let setting = setting.set(
  details     // object
)
```

### Parameters

`details`

An object that must contain the following property:

`value`

`any`. The value you want to change the setting to. Its type depends on the particular setting.


### Return value

A `Promise` that will be fulfilled with a `boolean`: `true` if the setting was modified, `false` otherwise (for example, because the extension did not control the setting).

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

See `types.BrowserSetting`.

Example
-------

Modify the `hyperlinkAuditingEnabled` setting (this requires the "privacy" permission):


```js
function onSet(result) {
  if (result) {
    console.log("Value was updated");
  } else {
    console.log("Value was not updated");
  }
}

browser.browserAction.onClicked.addListener(() => {
  let setting = browser.privacy.websites.hyperlinkAuditingEnabled.set({
    value: false,
  });
  setting.then(onSet);
});
```


**Note:**

This API is based on Chromium's `chrome.types` API.
extension.onRequestExternal
===========================

**Warning:** This is not implemented in Firefox because it has been deprecated since Chrome 33. Please use runtime.onMessageExternal instead.

Fired when a request is sent from another extension.

Syntax
------


```js
chrome.extension.onRequestExternal.addListener(function(
  request,      // optional any
  sender,       // runtime.MessageSender
  sendResponse, // function
) { })
chrome.extension.onRequestExternal.removeListener(listener)
chrome.extension.onRequestExternal.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)`

Check whether `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 these arguments:

`request`

`any`. The request sent by the calling script.

`sender`

`runtime.MessageSender`.

`sendResponse`

`function`. Function to call when you have a response. The argument should be any JSON-ifiable object, or undefined if there is no response.


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.extension` API. This documentation is derived from `extension.json` in the Chromium code.
extension.lastError
===================

**Warning:** This function is deprecated, use `runtime.lastError` instead.

An alias for `runtime.lastError`.

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.extension` API. This documentation is derived from `extension.json` in the Chromium code.
extension.ViewType
==================

The type of extension view.

Type
----

Values of this type are strings. Possible values are: `"tab"`, `"popup"`, `"sidebar"`.

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.extension` API. This documentation is derived from `extension.json` in the Chromium code.
extension.setUpdateUrlData()
============================

Sets parameters for the extension's update URL. This value is ignored for extensions that are hosted in the browser vendor's store.

Syntax
------


```js
browser.extension.setUpdateUrlData(
  data // string
)
```

### Parameters

`data`

`string`.

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

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

Examples
--------

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

Returns an array of the Window objects for each of the pages running inside the current extension. This includes, for example:

* the background page, if one is defined
* any popup pages, if defined and loaded
* any options pages, if defined and loaded
* any browser tabs that host content packaged with the extension

In Firefox, if this method is called from a page that is part of a private browsing window, such as a sidebar in a private window or a popup opened from a private window, then its return value will not include the extension's background page.

Syntax
------


```js
let windows = browser.extension.getViews(
  fetchProperties // optional object
)
```

### Parameters

`fetchProperties` Optional

An object with the following properties:

`type` Optional

`string`. An `extension.ViewType` indicating the type of view to get. If omitted, this function returns all views.

`windowId` Optional

`integer`. The window to restrict the search to. If omitted, this function returns all views. In Firefox version 92 and earlier, sidebar views are not matched and, therefore, not returned.


### Return value

`array` of `object`. Array of Window objects.

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

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

Examples
--------

Get all windows belonging to this extension, and log their URLs:


```js
const windows = browser.extension.getViews();

for (const extensionWindow of windows) {
  console.log(extensionWindow.location.href);
}
```


Get only windows in browser tabs hosting content packaged with the extension:


```js
const windows = browser.extension.getViews({ type: "tab" });
```


Get only windows in popups:


```js
const windows = browser.extension.getViews({ type: "popup" });
```


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

Returns `true` if the extension can access the "file://" scheme, `false` otherwise.

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

Syntax
------


```js
let isAllowed = browser.extension.isAllowedFileSchemeAccess()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with a boolean: `true` if the extension is allowed access to "file://" URLs, `false` otherwise.

Firefox will always return `false`.

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

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

Examples
--------


```js
function logIsAllowed(answer) {
  console.log(`Is allowed: ${answer}`);
}

let isAllowed = browser.extension.isAllowedFileSchemeAccess();
isAllowed.then(logIsAllowed);
```


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

Returns the Window of the background page if the background script is running. If the script is not running, null is returned.

This a synchronous function.

**Note:** This method cannot be used in Private Browsing mode — it always returns null. Consider using `runtime.sendMessage()` or `runtime.connect()`. See Firefox bug 1329304 for more information.

Syntax
------


```js
let page = browser.extension.getBackgroundPage()
```

### Parameters

None.

### Return value

`object`. Window of the background page or null.

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

let page = browser.extension.getBackgroundPage();
page.foo(); // -> "I'm defined in background.js"
```

### Example extensions

* find-across-tabs
* user-agent-rewriter
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.extension` API. This documentation is derived from `extension.json` in the Chromium code.
extension.isAllowedIncognitoAccess()
====================================

Check whether the extension is allowed access to tabs opened in "private browsing" mode.

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

Syntax
------


```js
let isAllowed = browser.extension.isAllowedIncognitoAccess()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with a boolean: `true` if the extension is allowed access to private tabs, `false` otherwise.

Examples
--------


```js
function logIsAllowed(answer) {
  console.log(`Is allowed: ${answer}`);
}

let isAllowed = browser.extension.isAllowedIncognitoAccess();
isAllowed.then(logIsAllowed);
```

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.extension` API. This documentation is derived from `extension.json` in the Chromium code.
extension.getExtensionTabs()
============================

**Warning:** This method has been deprecated. Use `extension.getViews()` instead.

Returns an array of the JavaScript Window objects for each of the tabs running inside the current extension. If `windowId` is specified, returns only the Window objects of tabs attached to the specified window.

Syntax
------


```js
chrome.extension.getExtensionTabs(
  windowId // optional integer
)
```


This API is also available as `browser.extension.getExtensionTabs()`.

### Parameters

`windowId` Optional

`integer`.

### Return value

`array` of `object`. Array of global window objects

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.extension` API. This documentation is derived from `extension.json` in the Chromium code.
extension.onRequest
===================

**Warning:** This is not implemented in Firefox because it has been deprecated since Chrome 33. Please use runtime.onMessage instead.

Fired when a request is sent from either an extension process or a content script.

Syntax
------


```js
chrome.extension.onRequest.addListener(function(
  request,         // optional any
  sender,          // runtime.MessageSender
  () => {/\* … \*/}  // function
) {/\* … \*/})
chrome.extension.onRequest.removeListener(listener)
chrome.extension.onRequest.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)`

Check whether `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 these arguments:

`request`

`any`. The request sent by the calling script.

`sender`

`runtime.MessageSender`.

`sendResponse`

`function`. Function to call (at most once) when you have a response. The argument should be any JSON-ifiable object, or undefined if there is no response. If you have more than one `onRequest` listener in the same document, then only one may send a response.


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.extension` API. This documentation is derived from `extension.json` in the Chromium code.
extension.getURL()
==================

**Warning:** This function is deprecated. Please use `runtime.getURL`.

Converts a relative path within an extension's install directory to a fully-qualified URL.

Syntax
------


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

### Parameters

`path`

`string`. A path to a resource within an extension expressed relative to its install directory.

### 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 add-on at "beasts/frog.html", get the full URL like this:


```js
let fullURL = browser.extension.getURL("beasts/frog.html");

// -> something like:
// moz-extension://2c127fa4-62c7-7e4f-90e5-472b45eecfdc/beasts/frog.html
```

### Example extensions

* beastify
* cookie-bg-picker
* imagify
* notify-link-clicks-i18n
* proxy-blocker

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

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

**Warning:** This method has been deprecated. Use `runtime.sendMessage` instead.

Sends a request to other listeners within the extension. Similar to `runtime.connect`, but only sends a request with an optional response. The `extension.onRequest` event fires in each page of the extension.

Syntax
------


```js
chrome.extension.sendRequest(
  extensionId,             // optional string
  request,                 // any
  (response) => {/\* … \*/}  // optional function
)
```


This API is also available as `browser.extension.sendRequest()` in a version that returns a promise.

### Parameters

`extensionId` Optional

`string`. The extension ID of the extension you want to connect to. If omitted, default is your own extension.

`request`

`any`.

`responseCallback` Optional

`function`. The function is passed these arguments:

`response`

`any`. The JSON response object sent by the handler of the request. If an error occurs while connecting to the extension, the callback will be called with no arguments and `runtime.lastError` will be set to the error message.


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.extension` API. This documentation is derived from `extension.json` in the Chromium code.
extension.inIncognitoContext
============================

Boolean value, `true` for content scripts running inside private browsing tabs and for extension pages running inside a private browsing process.

Syntax
------


```js
let isPrivate = browser.extension.inIncognitoContext;  // true or false
```

### Value

A *boolean* value indicate if the current script is running in a private tab or process.

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.extension` API. This documentation is derived from `extension.json` in the Chromium code.
contextualIdentities.onUpdated
==============================

Fired when the properties of a contextual identity, such as its name, icon, or color, are changed. Contextual identities may be updated by extensions using the `contextualIdentities` API, or directly by the user, using the browser's user interface.

Syntax
------


```js
browser.contextualIdentities.onUpdated.addListener(listener)
browser.contextualIdentities.onUpdated.removeListener(listener)
browser.contextualIdentities.onUpdated.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)`

Check whether `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:

`changeInfo`

`object`. An object that contains a single property, `contextualIdentity`, which is a `contextualIdentities.ContextualIdentity` object representing the identity whose properties were updated.


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

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

Examples
--------


```js
function handleUpdated(changeInfo) {
  console.log(`Updated: ${changeInfo.contextualIdentity.name}`);
}

browser.contextualIdentities.onUpdated.addListener(handleUpdated);
```
contextualIdentities.get()
==========================

Gets information about a contextual identity, given its cookie store ID.

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

Syntax
------


```js
let getContext = browser.contextualIdentities.get(
  cookieStoreId                  // string
)
```

### Parameters

`cookieStoreId`

`string`. The ID of this contextual identity's cookie store. Because contextual identities each have their own cookie store, this serves as an identifier for the contextual identity itself.

### Return value

A `Promise` that will be fulfilled with a `ContextualIdentity` that describes the identity. If the identity could not be found or the contextual identities feature is not enabled, the promise is rejected.

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

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

Examples
--------

This example tries to retrieve the contextual identity whose ID is "firefox-container-1":


```js
function onGot(context) {
  if (!context) {
    console.error("Context not found");
  } else {
    console.log(`Name: ${context.name}`);
  }
}

function onError(e) {
  console.error(e);
}

browser.contextualIdentities.get("firefox-container-1").then(onGot, onError);
```