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