webRequest.StreamFilter

Ein StreamFilter ist ein Objekt, das Sie verwenden können, um HTTP-Antworten zu überwachen und zu modifizieren.

Um einen StreamFilter zu erstellen, rufen Sie webRequest.filterResponseData() auf und übergeben Sie die ID der Webanfrage, die Sie filtern möchten.

Sie können sich den Stream-Filter als eine Instanz vorstellen, die zwischen dem Netzwerk-Stack und der Rendering-Engine des Browsers sitzt. Der Filter erhält HTTP-Antwortdaten, während diese vom Netzwerk empfangen werden. Er kann die Daten untersuchen und modifizieren, bevor er sie an die Rendering-Engine weitergibt, wo sie analysiert und gerendert werden. Der Filter hat die volle Kontrolle über den Antwortkörper, und das Standardverhalten ohne jegliche Listener oder Schreibvorgänge ist ein Stream ohne Inhalt, der niemals endet.

Der Filter generiert vier verschiedene Ereignisse:

onstart wenn der Filter kurz davor steht, Antwortdaten zu empfangen.
ondata wenn einige Antwortdaten vom Filter empfangen wurden und zur Untersuchung oder Modifikation zur Verfügung stehen.
onstop wenn der Filter das Empfangen von Antwortdaten beendet hat.
onerror wenn ein Fehler beim Initialisieren und Betrieb des Filters aufgetreten ist.

Sie können auf jedes Ereignis lauschen, indem Sie eine Listener-Funktion seinem Attribut zuweisen:

filter.onstart = (event) => {
  console.log("started");
};

Beachten Sie, dass die Anfrage während der Ausführung eines Listener-Ereignisses blockiert ist.

Der Filter bietet die Funktion write(). Ab dem onstart-Ereignis können Sie diese Funktion verwenden, um Daten in den Ausgabestream zu schreiben.

Wenn Sie Listener zu einem der Filterereignisse hinzufügen, werden alle an die Rendering-Engine übergebenen Antwortdaten durch Aufrufe, die Sie an write() machen, bereitgestellt. Wenn Sie also einen Listener hinzufügen und write() nicht aufrufen, bleibt die gerenderte Seite leer.

Sobald Sie die Interaktion mit der Antwort abgeschlossen haben, rufen Sie eine der folgenden Funktionen auf:

disconnect(): Trennt den Filter von der Anfrage, sodass der Rest der Antwort normal verarbeitet wird.
close(): Schließt die Anfrage, sodass keine zusätzlichen Antwortdaten verarbeitet werden.

Der Filter bietet auch Funktionen zum suspend() und resume(), um die Anfrage zu pausieren oder fortzusetzen.

Methoden

webRequest.StreamFilter.close(): Schließt die Anfrage.
webRequest.StreamFilter.disconnect(): Trennt den Filter von der Anfrage.
webRequest.StreamFilter.resume(): Setzt die Verarbeitung der Anfrage fort.
webRequest.StreamFilter.suspend(): Pausiert die Verarbeitung der Anfrage.
webRequest.StreamFilter.write(): Schreibt einige Daten in den Ausgabestream.

Eigenschaften

webRequest.StreamFilter.ondata: Ereignishandler, der aufgerufen wird, wenn eingehende Daten verfügbar sind.
webRequest.StreamFilter.onerror: Ereignishandler, der aufgerufen wird, wenn ein Fehler aufgetreten ist.
webRequest.StreamFilter.onstart: Ereignishandler, der aufgerufen wird, wenn der Stream kurz davor ist, Daten zu empfangen.
webRequest.StreamFilter.onstop: Ereignishandler, der aufgerufen wird, wenn der Stream keine Daten mehr liefert und geschlossen wurde.
webRequest.StreamFilter.error: Wenn webRequest.StreamFilter.onerror aufgerufen wird, beschreibt dies den Fehler.
webRequest.StreamFilter.status: Beschreibt den aktuellen Status des Streams.

Browser-Kompatibilität

BCD tables only load in the browser

Beispiele

Dieser Code lauscht auf onstart, ondata und onstop. Er protokolliert diese Ereignisse und die Antwortdaten selbst als ArrayBuffer:

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

  filter.onstart = (event) => {
    console.log("started");
  };

  filter.ondata = (event) => {
    console.log(event.data);
    filter.write(event.data);
  };

  filter.onstop = (event) => {
    console.log("finished");
    filter.disconnect();
  };

  //return {}; // not needed
}

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