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