TCPSocket.webidl (7654B)
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 * TCPSocket exposes a TCP client socket (no server sockets yet) 8 * to highly privileged apps. It provides a buffered, non-blocking 9 * interface for sending. For receiving, it uses an asynchronous, 10 * event handler based interface. 11 */ 12 13 interface nsISocketTransport; 14 15 enum TCPSocketBinaryType { 16 "arraybuffer", 17 "string" 18 }; 19 20 dictionary SocketOptions { 21 boolean useSecureTransport = false; 22 TCPSocketBinaryType binaryType = "string"; 23 }; 24 25 enum TCPReadyState { 26 "connecting", 27 "open", 28 "closing", 29 "closed", 30 }; 31 32 [LegacyNoInterfaceObject, 33 Exposed=Window] 34 interface LegacyMozTCPSocket { 35 /** 36 * Legacy constructor for API compatibility. 37 */ 38 [Throws] 39 TCPSocket open(DOMString host, unsigned short port, optional SocketOptions options = {}); 40 41 [Throws] 42 TCPServerSocket listen(unsigned short port, optional ServerSocketOptions options = {}, optional unsigned short backlog = 0); 43 }; 44 45 [Func="mozilla::dom::TCPSocket::ShouldTCPSocketExist", 46 Exposed=Window] 47 interface TCPSocket : EventTarget { 48 [Throws] 49 constructor(DOMString host, unsigned short port, 50 optional SocketOptions options = {}); 51 52 /** 53 * Upgrade an insecure connection to use TLS. Throws if the ready state is not OPEN. 54 */ 55 [Throws] undefined upgradeToSecure(); 56 57 /** 58 * The raw internal socket transport. 59 */ 60 readonly attribute nsISocketTransport? transport; 61 62 /** 63 * The UTF16 host of this socket object. 64 */ 65 readonly attribute USVString host; 66 67 /** 68 * The port of this socket object. 69 */ 70 readonly attribute unsigned short port; 71 72 /** 73 * True if this socket object is an SSL socket. 74 */ 75 readonly attribute boolean ssl; 76 77 /** 78 * The number of bytes which have previously been buffered by calls to 79 * send on this socket. 80 */ 81 readonly attribute unsigned long long bufferedAmount; 82 83 /** 84 * Pause reading incoming data and invocations of the ondata handler until 85 * resume is called. Can be called multiple times without resuming. 86 */ 87 undefined suspend(); 88 89 /** 90 * Resume reading incoming data and invoking ondata as usual. There must be 91 * an equal number of resume as suspends that took place. Throws if the 92 * socket is not suspended. 93 */ 94 [Throws] 95 undefined resume(); 96 97 /** 98 * Close the socket. 99 */ 100 undefined close(); 101 102 /** 103 * Close the socket immediately without waiting for unsent data. 104 */ 105 [ChromeOnly] undefined closeImmediately(); 106 107 /** 108 * Write data to the socket. 109 * 110 * @param data The data to write to the socket. 111 * 112 * @return Send returns true or false as a hint to the caller that 113 * they may either continue sending more data immediately, or 114 * may want to wait until the other side has read some of the 115 * data which has already been written to the socket before 116 * buffering more. If send returns true, then less than 64k 117 * has been buffered and it's safe to immediately write more. 118 * If send returns false, then more than 64k has been buffered, 119 * and the caller may wish to wait until the ondrain event 120 * handler has been called before buffering more data by more 121 * calls to send. 122 * 123 * @throws Throws if the ready state is not OPEN. 124 */ 125 [Throws] 126 boolean send(ByteString data); 127 128 /** 129 * Write data to the socket. 130 * 131 * @param data The data to write to the socket. 132 * @param byteOffset The offset within the data from which to begin writing. 133 * @param byteLength The number of bytes to write. 134 * Defaults to the byte length of the ArrayBuffer if not present, 135 * and clamped to (length - byteOffset). 136 * 137 * @return Send returns true or false as a hint to the caller that 138 * they may either continue sending more data immediately, or 139 * may want to wait until the other side has read some of the 140 * data which has already been written to the socket before 141 * buffering more. If send returns true, then less than 64k 142 * has been buffered and it's safe to immediately write more. 143 * If send returns false, then more than 64k has been buffered, 144 * and the caller may wish to wait until the ondrain event 145 * handler has been called before buffering more data by more 146 * calls to send. 147 * 148 * @throws Throws if the ready state is not OPEN. 149 */ 150 [Throws] 151 boolean send(ArrayBuffer data, optional unsigned long byteOffset = 0, optional unsigned long byteLength); 152 153 /** 154 * The readyState attribute indicates which state the socket is currently 155 * in. 156 */ 157 readonly attribute TCPReadyState readyState; 158 159 /** 160 * The binaryType attribute indicates which mode this socket uses for 161 * sending and receiving data. If the binaryType: "arraybuffer" option 162 * was passed to the open method that created this socket, binaryType 163 * will be "arraybuffer". Otherwise, it will be "string". 164 */ 165 readonly attribute TCPSocketBinaryType binaryType; 166 167 /** 168 * The "open" event is dispatched when the connection to the server 169 * has been established. If the connection is refused, the "error" event 170 * will be dispatched, instead. 171 */ 172 attribute EventHandler onopen; 173 174 /** 175 * After send has buffered more than 64k of data, it returns false to 176 * indicate that the client should pause before sending more data, to 177 * avoid accumulating large buffers. This is only advisory, and the client 178 * is free to ignore it and buffer as much data as desired, but if reducing 179 * the size of buffers is important (especially for a streaming application) 180 * the "drain" event will be dispatched once the previously-buffered data has 181 * been written to the network, at which point the client can resume calling 182 * send again. 183 */ 184 attribute EventHandler ondrain; 185 186 /** 187 * The "data" event will be dispatched repeatedly and asynchronously after 188 * "open" is dispatched, every time some data was available from the server 189 * and was read. The event object will be a TCPSocketEvent; if the "arraybuffer" 190 * binaryType was passed to the constructor, the data attribute of the event 191 * object will be an ArrayBuffer. If not, it will be a normal JavaScript string, 192 * truncated at the first null byte found in the payload and the remainder 193 * interpreted as ASCII bytes. 194 * 195 * At any time, the client may choose to pause reading and receiving "data" 196 * events by calling the socket's suspend() method. Further "data" events 197 * will be paused until resume() is called. 198 */ 199 attribute EventHandler ondata; 200 201 /** 202 * The "error" event will be dispatched when there is an error. The event 203 * object will be a TCPSocketErrorEvent. 204 * 205 * If an "error" event is dispatched before an "open" one, the connection 206 * was refused, and the "close" event will not be dispatched. If an "error" 207 * event is dispatched after an "open" event, the connection was lost, 208 * and a "close" event will be dispatched subsequently. 209 */ 210 attribute EventHandler onerror; 211 212 /** 213 * The "close" event is dispatched once the underlying network socket 214 * has been closed, either by the server, or by the client calling 215 * close. 216 * 217 * If the "error" event was not dispatched before "close", then one of 218 * the sides cleanly closed the connection. 219 */ 220 attribute EventHandler onclose; 221 };