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/. */
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.
13 interface nsISocketTransport;
15 enum TCPSocketBinaryType {
20 dictionary SocketOptions {
21 boolean useSecureTransport = false;
22 TCPSocketBinaryType binaryType = "string";
32 [LegacyNoInterfaceObject,
34 interface LegacyMozTCPSocket {
36 * Legacy constructor for API compatibility.
39 TCPSocket open(DOMString host, unsigned short port, optional SocketOptions options = {});
42 TCPServerSocket listen(unsigned short port, optional ServerSocketOptions options = {}, optional unsigned short backlog = 0);
45 [Func="mozilla::dom::TCPSocket::ShouldTCPSocketExist",
47 interface TCPSocket : EventTarget {
49 constructor(DOMString host, unsigned short port,
50 optional SocketOptions options = {});
53 * Upgrade an insecure connection to use TLS. Throws if the ready state is not OPEN.
55 [Throws] undefined upgradeToSecure();
58 * The raw internal socket transport.
60 readonly attribute nsISocketTransport? transport;
63 * The UTF16 host of this socket object.
65 readonly attribute USVString host;
68 * The port of this socket object.
70 readonly attribute unsigned short port;
73 * True if this socket object is an SSL socket.
75 readonly attribute boolean ssl;
78 * The number of bytes which have previously been buffered by calls to
79 * send on this socket.
81 readonly attribute unsigned long long bufferedAmount;
84 * Pause reading incoming data and invocations of the ondata handler until
85 * resume is called. Can be called multiple times without resuming.
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.
103 * Close the socket immediately without waiting for unsent data.
105 [ChromeOnly] undefined closeImmediately();
108 * Write data to the socket.
110 * @param data The data to write to the socket.
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
123 * @throws Throws if the ready state is not OPEN.
126 boolean send(ByteString data);
129 * Write data to the socket.
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).
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
148 * @throws Throws if the ready state is not OPEN.
151 boolean send(ArrayBuffer data, optional unsigned long byteOffset = 0, optional unsigned long byteLength);
154 * The readyState attribute indicates which state the socket is currently
157 readonly attribute TCPReadyState readyState;
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".
165 readonly attribute TCPSocketBinaryType binaryType;
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.
172 attribute EventHandler onopen;
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
184 attribute EventHandler ondrain;
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.
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.
199 attribute EventHandler ondata;
202 * The "error" event will be dispatched when there is an error. The event
203 * object will be a TCPSocketErrorEvent.
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.
210 attribute EventHandler onerror;
213 * The "close" event is dispatched once the underlying network socket
214 * has been closed, either by the server, or by the client calling
217 * If the "error" event was not dispatched before "close", then one of
218 * the sides cleanly closed the connection.
220 attribute EventHandler onclose;