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