recursal/MDN huggingface dataset:
webRequest.RequestFilter
========================

Un objet décrivant les filtres à appliquer aux événements webRequest.

Type
----

Les valeurs de ce type sont des objets. Ils contiennent les propriétés suivantes :

`urls`

`array` de `string`. Un tableau de motifs (Match patterns). L'auditeur ne sera appelé que pour les demandes dont les cibles correspondent à l'un des modèles donnés. Seules les requêtes faites en utilisant HTTP ou HTTPS déclencheront des événements, même si les modèles de correspondance peuvent correspondre à d'autres protocoles.

`types`Facultatif

`array` de ``webRequest.ResourceType``. Une liste des types de ressources (par exemple, feuilles de style, images, scripts). L'auditeur ne sera appelé que pour les demandes de ressources qui sont de l'un des types donnés.

`tabId`Facultatif

`integer`. L'auditeur ne sera appelé que pour les requêtes provenant du `tab` identifié par cet ID.

`windowId`Facultatif

`integer`. L'auditeur ne sera appelé que pour les requêtes provenant du `window` identifié par cet ID.

incognito Facultatif

`boolean`. Si elles sont fournies, les demandes qui ne correspondent pas à l'état incognito (`true` ou `false`) seront filtrées.

Compatibilité des navigateurs
-----------------------------

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

**Note :**

Cette API est basée sur l'API Chromium `chrome.webRequest`. Cette documentation est dérivée de `web_request.json` dans le code Chromium.

Les données de compatibilité relatives à Microsoft Edge sont fournies par Microsoft Corporation et incluses ici sous la licence Creative Commons Attribution 3.0 pour les États-Unis.
webRequest.HttpHeaders
======================

Un tableau d'en-tetes HTTP. Chaque en-tête est représenté comme un objet avec deux propriétés : `name` et `valeur` ou `binaryValue`.

Type
----

Un `tableau` d'`objet`s. Chaque objet a les propriétés suivantes :

`name`

`string`. Nom de l'en-tête HTTP.

`value`Facultatif

`string`. Valeur de l'en-tete HTTP si elle peut être représentée par UTF-8. Cette propriété ou valeur binaire doit être présente.

`binaryValue`Facultatif

`array` d'`integer`. Valeur de l'en-tête HTTP s'il ne peut pas être représenté par UTF-8, représenté par en octets (0..255). Soit cette propriété ou cette `valeur` doit être présente.

Compatibilité des navigateurs
-----------------------------

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

**Note :**

Cette API est basée sur l'API Chromium `chrome.webRequest`. Cette documentation est dérivée de `web_request.json` dans le code Chromium.

Les données de compatibilité relatives à Microsoft Edge sont fournies par Microsoft Corporation et incluses ici sous la licence Creative Commons Attribution 3.0 pour les États-Unis.
webRequest.UploadData
=====================

Contient les données téléchargées dans une requête URL..

Type
----

Les valeurs de ce type sont des objets. Ils contiennent les propriétés suivantes :

`bytes`Facultatif

`any`. Un ArrayBuffer avec une copie des données.

`file`Facultatif

`string`. Une chaîne de caractères avec le chemin et le nom du fichier.

Compatibilité des navigateurs
-----------------------------

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

**Note :**

Cette API est basée sur l'API Chromium `chrome.webRequest`. Cette documentation est dérivée de `web_request.json` dans le code Chromium.

Les données de compatibilité relatives à Microsoft Edge sont fournies par Microsoft Corporation et incluses ici sous la licence Creative Commons Attribution 3.0 pour les États-Unis.
webRequest.handlerBehaviorChanged()
===================================

Cette fonction peut être utilisée pour s'assurer que les auditeurs d'événements sont appliqués correctement lorsque les pages se trouvent dans le cache en mémoire du navigateur.Si le navigateur a chargé une page et que la page est rechargée, le navigateur peut recharger la page à partir de son cache en mémoire, et dans ce cas, les événements ne seront pas déclenchés pour la demande.
Supposons que le travail d'une extension consiste à bloquer les requêtes Web par rapport à un modèle, et le scénario suivant se produit :

* L'utilisateur charge une page qui inclut une requête particulière, et le modèle permet la requête.
* La ressource est chargée et mise en cache en mémoire.
* Les modèles de l'extension sont mis à jour, de telle sorte que la ressource ne serait plus autorisée.
* L'utilisateur recharge la page.

Comme la page sera rechargée à partir du cache mémoire, il se peut que l'auditeur ne soit plus appelé et que la requête soit chargée malgré la nouvelle stratégie de l'extension.

La fonction `handlerBehaviorChanged()` est conçue pour résoudre ce problème. Il vide le cache en mémoire, de sorte que les rechargements de page déclenchent les auditeurs d'événements.

Parce que `handlerBehaviorChanged()` nettoie le cache, cela peut être coûteux et mauvais pour la performance. Le module webRequest définit une propriété en lecture seule `MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES` : faire plus d'appels que ce nombre en 10 minutes n'aura aucun effet.

L'implémentation de la mise en cache, d'où la nécessité de cette fonction, varie d'un navigateur à l'autre, de sorte que dans certains navigateurs, cette fonction ne fait rien.

Il s'agit d'une fonction asynchrone qui renvoie une `Promise`.

Syntaxe
-------


```js
var flushingCache = browser.webRequest.handlerBehaviorChanged();
```

### Paramètres

None.

### Valeur retournée

Une `Promise` qui sera remplie sans arguments, lorsque l'opération sera terminée.

Compatibilité des navigateurs
-----------------------------

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

Exemples
--------

Dans le snippet suivant, nous vidons le cache en mémoire via un appel à `handlerBehaviorChanged()`, et signalons cette action en enregistrant un message approprié à la console.


```js
function onFlushed() {
  console.log(`In-memory cache flushed`);
}

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

var flushingCache = browser.webRequest.handlerBehaviorChanged();
flushingCache.then(onFlushed, onError);
```


**Note :**

Cette API est basée sur l'API Chromium `chrome.webRequest`. Cette documentation est dérivée de `web_request.json` dans le code Chromium.

Les données de compatibilité relatives à Microsoft Edge sont fournies par Microsoft Corporation et incluses ici sous la licence Creative Commons Attribution 3.0 pour les États-Unis.
webRequest.MAX\_HANDLER\_BEHAVIOR\_CHANGED\_CALLS\_PER\_10\_MINUTES
===================================================================

Le nombre maximum de fois que ``handlerBehaviorChanged()`` peut être appelé dans une période de 10 minutes.

Cette propriété est en lecture seule.

Compatibilité des navigateurs
-----------------------------

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

**Note :**

Cette API est basée sur l'API Chromium `chrome.webRequest`. Cette documentation est dérivée de `web_request.json` dans le code Chromium.

Les données de compatibilité relatives à Microsoft Edge sont fournies par Microsoft Corporation et incluses ici sous la licence Creative Commons Attribution 3.0 pour les États-Unis.
webRequest.filterResponseData()
===============================

 Utilisez cette fonction pour créer un objet `webRequest.StreamFilter` pour une requête particulière.
 Vous pouvez ensuite utiliser le filtre de flux pour surveiller et modifier la réponse. Vous appelez typiquement cette fonction à partir d'un écouteur d'événements `webRequest`.

Pour utiliser cette API, vous devez avoir la permission de l'API "webRequestBlocking", ainsi que les permissions normales nécessaires à l'auditeur de l'événement (la permission "webRequest" et la permission hôtepour l'hôte).

Syntaxe
-------


```js
var filter = browser.webRequest.filterResponseData(
  requestId, // string
);
```

### Paramètres

`requestId`

`string`. ID de la requête à filtrer. Vous pouvez l'obtenir à partir de l'objet de `details` qui est passé dans n'importe quel écouteur d'événement `webRequest`.

### Valeur retournée

Un objet `webRequest.StreamFilter` que vous pouvez utiliser pour surveiller et modifier la réponse.

Exemples
--------

Cet exemple, tiré de l'extension http-response, crée un filtre dans `webRequest.onBeforeRequest` et l'utilise pour modifier la réponse :


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);
  let decoder = new TextDecoder("utf-8");
  let encoder = new TextEncoder();

  filter.ondata = (event) => {
    let str = decoder.decode(event.data, { stream: true });
    // Just change any instance of Example in the HTTP response
    // to WebExtension Example.
    str = str.replace(/Example/g, "WebExtension Example");
    filter.write(encoder.encode(str));
    filter.disconnect();
  };

  return {};
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.com/\*"], types: ["main\_frame"] },
  ["blocking"],
);
```

### Example extensions

* http-response
Compatibilité des navigateurs
-----------------------------

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

Un objet décrivant un seul certificat X.509.

L'objet `SecurityInfo` retourné par l'objet `webRequest.getSecurityInfo()` API inclut une propriété de `certificats` qui est un tableau de ces objets.

Type
----

Les valeurs de ce type sont des objets. Ils contiennent les propriétés suivantes :

`fingerprint`

`Object`. Un objet avec les propriétés suivantes :

`sha1`

`String`. SHA-1 hash de l'encodage DER du certificat.

`sha256`

`String`. SHA-256 hash de l'encodage DER du certificat.


`isBuiltInRoot`

`Boolean`. `true` si le certificat est l'une des racines de confiance installées dans le navigateur, sinon `false`.

`issuer`

`String`. Nom de l'organisation qui a délivré ce certificat, représenté par un nom distinctif et formaté sous la forme d'une liste de noms distinctifs relatifs séparés par des virgules, chacun de la forme "type=value".

Par exemple: "CN=DigiCert SHA2 Secure Server CA,O=DigiCert Inc,C=US".

`rawDER`

`Array` de `Number`. Si `webRequest.getSecurityInfo()` a été appelé avec l'option `rawDER` présent et mis à `true`, ceci contiendra l'encodage DER du certificat.

`serialNumber`

`String`. Le numéro de série du certificat.

`subject`

`String`. Nom de l'organisation qui a délivré ce certificat, représenté par un nom distinctif et formaté sous la forme d'une liste de noms distinctifs relatifs séparés par des virgules, chacun de la forme "type=value".

Par exemple: "CN=\*.cdn.mozilla.net,O=Mozilla Corporation,L=Mountain View,ST=California,C=US".

`subjectPublicKeyInfoDigest`

`Object`. Un objet contenant les propriétés suivantes :

`sha256`

`String`. Base64 encodé SHA-256 hash de l'information de clé publique codée DER.


`validity`

`Object`. Période de validité du certificat. Un objet contenant les propriétés suivantes :

`start`

`Number`. Le début de la période de validité du certificat, en millisecondes depuis l'époque.

`end`

`Number`. La fin de la période de validité du certificat, en millisecondes depuis l'époque.


Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
webRequest.Streamfilter.error
=============================

Une chaîne de caractères qui contiendra un message d'erreur après le déclenchement de l'événement `onerror`.

Compatibilité des navigateurs
-----------------------------

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

Exemples
--------

Cet exemple ajoute un écouteur `onerror` qui enregistre la valeur de `error`.


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData("12345");

  filter.onerror = (event) => {
    console.log(`Error: ${filter.error}`);
  };

  //return {}; // not needed
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["<all\_urls>"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.onerror
===============================

Un gestionnaire d'événements qui sera appelé lorsqu'une erreur se produit. C'est le plus souvent parce qu'un ID de requête invalide a été passé dans `webRequest.filterResponseData()`.

Après le déclenchement de cet événement, la propriété `webRequest.StreamFilter.error` contiendra un message donnant plus d'informations sur l'erreur.

Notez que cet événement n'est *pas* déclenché pour les erreurs réseau.

Compatibilité des navigateurs
-----------------------------

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

Exemples
--------

Cet exemple ajoute un écouteur `onerror` qui enregistre la valeur de `webRequest.StreamFilter.error`.


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData("12345");

  filter.onerror = (event) => {
    console.log(`Error: ${filter.error}`);
  };

  //return {}; // not needed
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["<all\_urls>"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.onstop
==============================

Un gestionnaire d'événements qui sera appelé lorsque le flux n'a plus de données à livrer. IDans le gestionnaire d'événements, vous pouvez toujours appeler des fonctions de filtrage telles que `write()`, `disconnect()`, ou `close()`.

Compatibilité des navigateurs
-----------------------------

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

Exemples
--------

Cet exemple ajoutera des "extra stuff" à la réponse :


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);
  let encoder = new TextEncoder();

  filter.ondata = (event) => {
    // pass through all the response data
    filter.write(event.data);
  };

  filter.onstop = (event) => {
    filter.write(encoder.encode("extra stuff"));
    filter.disconnect();
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.com/\*"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.status
==============================

Une chaîne de caractères qui décrit l'état actuel de la demande. Ce sera l'une des valeurs suivantes :

`"uninitialized"`

Le filtre n'est pas entièrement initialisé. Aucune fonction de filtrage ne peut être appelée.

`"transferringdata"`

Le canal sous-jacent transfère actuellement des données qui seront acheminées vers l'extension dans un ou plusieurs événements `ondata`. L'extension peut appeler des fonctions de filtrage telles que `write()`, `close()`, ou `disconnect()`.

`"finishedtransferringdata"`

Le canal sous-jacent a terminé le transfert des données. Dans cet état, l'extension peut toujours écrire des données de réponse en utilisant la fonction `write()` du filtre.

`"suspended"`

Le transfert de données est actuellement suspendu. Dans cet état, l'extension peut reprendre la requête en appelant la fonction `resume()` et peut écrire les données de réponse en utilisant la fonction `write()` du filtre.

`"closed"`

L'extension a fermé la requête en appelant la fonction `close()` du filtre. Le filtre ne déclenchera plus d'événements, et l'extension ne peut pas appeler de fonctions de filtrage.

`"disconnected"`

L'extension a déconnecté le filtre de la requête en appelant la fonction `disconnect()` du filtre. Toutes les autres données seront livrées directement, sans passer par le filtre. Le filtre ne déclenchera plus d'événements, et l'extension ne peut pas appeler de fonctions de filtrage.

`"failed"`

Une erreur s'est produite et le filtre a été déconnecté de la requête. L'extension peut trouver un message d'erreur dans `error`, et ne peut appeler aucune fonction de filtrage.

Compatibilité des navigateurs
-----------------------------

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

Exemples
--------


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);
  console.log(filter.status); // uninitialized

  filter.onstart = (event) => {
    console.log(filter.status); // transferringdata
  };

  filter.ondata = (event) => {
    console.log(filter.status); // transferringdata
    // pass through the response data
    filter.write(event.data);
  };

  filter.onstop = (event) => {
    console.log(filter.status); // finishedtransferringdata
    filter.disconnect();
    console.log(filter.status); // disconnected
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.com/\*"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.close()
===============================

Ferme la demande. Après cet appel, aucune autre donnée de réponse ne sera transmise au moteur de rendu du navigateur et aucun autre événement de filtrage ne sera donné à l'extension.

Notez la différence entre cette fonction et `disconnect()`. Avec `disconnect()`, le navigateur continuera à traiter d'autres données de réponse, mais il ne sera pas accessible par le filtre. Avec `close()`, le navigateur ignorera toutes les données de réponse qui n'ont pas déjà été transmises au moteur de rendu.

Vous devriez toujours appeler `close()` ou `disconnect()` une fois que vous n'avez plus besoin d'interagir avec la réponse.

Vous ne pouvez pas appeler cette fonction avant que l'événement `onstart` ne soit déclenché.

Syntaxe
-------


```js
filter.close();
```

### Paramètres

None.

### Valeur retournée

None.

Compatibilité des navigateurs
-----------------------------

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

Exemples
--------

Cet exemple remplacera le contenu de la page par "texte de remplacement" :


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);

  filter.onstart = (event) => {
    console.log("started");
    let encoder = new TextEncoder();
    filter.write(encoder.encode("replacement content"));
    filter.close();
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.org/"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.suspend()
=================================

Suspend une demande. Après cet appel, plus aucune donnée ne sera livrée jusqu'à ce que la requête soit reprise avec un appel à `resume()`.

Vous ne pouvez pas appeler cette fonction avant que l'événement `onstart` ne soit déclenché.

Syntaxe
-------


```js
filter.suspend();
```

### Paramètres

None.

### Valeur retournée

None.

Compatibilité des navigateurs
-----------------------------

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

Exemples
--------

Cet exemple utilise la *suspend/resume* pour retarder une requête web.


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);

  filter.onstart = (event) => {
    filter.suspend();

    setTimeout(() => {
      filter.resume();
      filter.disconnect();
    }, 1000);
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.org/"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.write()
===============================

Écrit quelques données de réponse dans le flux de sortie..Vous ne pouvez appeler cette fonction qu'après le déclenchement de l'événement `onstart`.Syntaxe
-------


```js
filter.write(
  data, // ArrayBuffer or Uint8Array
);
```

### Paramètres

`data`

`Uint8Array` ou `ArrayBuffer`: tableau d'octets contenant les données à transmettre au moteur de rendu du navigateur.

### Valeur retournée

None.

Compatibilité des navigateurs
-----------------------------

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

Exemples
--------

Cet exemple utilise `write()` pour remplacer "Example" dans la réponse par "WebExtension Example".


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);
  let decoder = new TextDecoder("utf-8");
  let encoder = new TextEncoder();

  filter.ondata = (event) => {
    let str = decoder.decode(event.data, { stream: true });
    // Just change any instance of Example in the HTTP response
    // to WebExtension Example.
    str = str.replace(/Example/g, "WebExtension Example");
    filter.write(encoder.encode(str));
    filter.disconnect();
  };

  //return {}; // not needed
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.com/\*"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.disconnect()
====================================

Déconnecte le filtre de la requête. Après cela, le navigateur continuera à traiter la réponse, mais plus aucun événement de filtrage ne se déclenchera, et plus aucun appel de fonction de filtrage n'aura d'effet.Notez la différence entre cette fonction et `close()`. Avec `disconnect()`, le navigateur continuera à traiter d'autres données de réponse, mais il ne sera pas accessible par le filtre. Avec `close()`, le navigateur ignorera toutes les données de réponse qui n'ont pas déjà été transmises au moteur de rendu.
Vous devriez toujours appeler `disconnect()` ou `close()` une fois que vous n'avez plus besoin d'interagir avec la réponse.

Vous ne pouvez pas appeler cette fonction avant que l'événement `onstart` ne soit déclenché.

Syntaxe
-------


```js
filter.disconnect();
```

### Paramètres

None.

### Valeur retournée

None.

Compatibilité des navigateurs
-----------------------------

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

Exemples
--------

Cet exemple précèdera "preface text" au corps de la réponse. Il se déconnecte ensuite, de sorte que le corps de réponse d'origine se charge normalement :


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);

  filter.onstart = (event) => {
    console.log("started");
    let encoder = new TextEncoder();
    filter.write(encoder.encode("preface text"));
    filter.disconnect();
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.org/"], types: ["main\_frame"] },
  ["blocking"],
);
```
webRequest.StreamFilter.onstart
===============================

Un gestionnaire d'événements qui sera appelé lorsque le flux est ouvert et est sur le point de commencer à livrer les données. A partir de ce point, l'extension peut utiliser des fonctions de filtrage telles que `write()`, `disconnect()`, ou `close()`.

Compatibilité des navigateurs
-----------------------------

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

Exemples
--------

Cet exemple remplacera le contenu de la page par "texte de remplacement" :


```js
function listener(details) {
  let filter = browser.webRequest.filterResponseData(details.requestId);

  filter.onstart = (event) => {
    console.log("started");
    let encoder = new TextEncoder();
    filter.write(encoder.encode("replacement content"));
    filter.close();
  };
}

browser.webRequest.onBeforeRequest.addListener(
  listener,
  { urls: ["https://example.org/"], types: ["main\_frame"] },
  ["blocking"],
);
```