StreamFilter.webidl (4329B)
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 };