dom/webidl/TCPSocket.webidl

   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 };