dom/webidl/StreamFilter.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 file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 /**
   8  * This is a Mozilla-specific WebExtension API, which is not available to web
   9  * content. It allows monitoring and filtering of HTTP response stream data.
  10  *
  11  * This API should currently be considered experimental, and is not defined by
  12  * any standard.
  13  */
  14
  15 enum StreamFilterStatus {
  16   /**
  17    * The StreamFilter is not fully initialized. No methods may be called until
  18    * a "start" event has been received.
  19    */
  20   "uninitialized",
  21   /**
  22    * The underlying channel is currently transferring data, which will be
  23    * dispatched via "data" events.
  24    */
  25   "transferringdata",
  26   /**
  27    * The underlying channel has finished transferring data. Data may still be
  28    * written via write() calls at this point.
  29    */
  30   "finishedtransferringdata",
  31   /**
  32    * Data transfer is currently suspended. It may be resumed by a call to
  33    * resume(). Data may still be written via write() calls in this state.
  34    */
  35   "suspended",
  36   /**
  37    * The channel has been closed by a call to close(). No further data wlil be
  38    * delivered via "data" events, and no further data may be written via
  39    * write() calls.
  40    */
  41   "closed",
  42   /**
  43    * The channel has been disconnected by a call to disconnect(). All further
  44    * data will be delivered directly, without passing through the filter. No
  45    * further events will be dispatched, and no further data may be written by
  46    * write() calls.
  47    */
  48   "disconnected",
  49   /**
  50    * An error has occurred and the channel is disconnected. The `error`
  51    * property contains the details of the error.
  52    */
  53   "failed",
  54 };
  55
  56 /**
  57  * An interface which allows an extension to intercept, and optionally modify,
  58  * response data from an HTTP request.
  59  */
  60 [Exposed=Window,
  61  Func="mozilla::extensions::StreamFilter::IsAllowedInContext"]
  62 interface StreamFilter : EventTarget {
  63   /**
  64    * Creates a stream filter for the given add-on and the given extension ID.
  65    */
  66   [ChromeOnly]
  67   static StreamFilter create(unsigned long long requestId, DOMString addonId);
  68
  69   /**
  70    * Suspends processing of the request. After this is called, no further data
  71    * will be delivered until the request is resumed.
  72    */
  73   [Throws]
  74   undefined suspend();
  75
  76   /**
  77    * Resumes delivery of data for a suspended request.
  78    */
  79   [Throws]
  80   undefined resume();
  81
  82   /**
  83    * Closes the request. After this is called, no more data may be written to
  84    * the stream, and no further data will be delivered.
  85    *
  86    * This *must* be called after the consumer is finished writing data, unless
  87    * disconnect() has already been called.
  88    */
  89   [Throws]
  90   undefined close();
  91
  92   /**
  93    * Disconnects the stream filter from the request. After this is called, no
  94    * further data will be delivered to the filter, and any unprocessed data
  95    * will be written directly to the output stream.
  96    */
  97   [Throws]
  98   undefined disconnect();
  99
 100   /**
 101    * Writes a chunk of data to the output stream. This may not be called
 102    * before the "start" event has been received.
 103    */
 104   [Throws]
 105   undefined write((ArrayBuffer or Uint8Array) data);
 106
 107   /**
 108    * Returns the current status of the stream.
 109    */
 110   [Pure]
 111   readonly attribute StreamFilterStatus status;
 112
 113   /**
 114    * After an "error" event has been dispatched, this contains a message
 115    * describing the error.
 116    */
 117   [Pure]
 118   readonly attribute DOMString error;
 119
 120   /**
 121    * Dispatched with a StreamFilterDataEvent whenever incoming data is
 122    * available on the stream. This data will not be delivered to the output
 123    * stream unless it is explicitly written via a write() call.
 124    */
 125   attribute EventHandler ondata;
 126
 127   /**
 128    * Dispatched when the stream is opened, and is about to begin delivering
 129    * data.
 130    */
 131   attribute EventHandler onstart;
 132
 133   /**
 134    * Dispatched when the stream has closed, and has no more data to deliver.
 135    * The output stream remains open and writable until close() is called.
 136    */
 137   attribute EventHandler onstop;
 138
 139   /**
 140    * Dispatched when an error has occurred. No further data may be read or
 141    * written after this point.
 142    */
 143   attribute EventHandler onerror;
 144 };