DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (dcc6d7a0dc00)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/. */

/**
 * TCPSocket exposes a TCP client socket (no server sockets yet)
 * to highly privileged apps. It provides a buffered, non-blocking
 * interface for sending. For receiving, it uses an asynchronous,
 * event handler based interface.
 */

enum TCPSocketBinaryType {
  "arraybuffer",
  "string"
};

dictionary SocketOptions {
  boolean useSecureTransport = false;
  TCPSocketBinaryType binaryType = "string";
};

enum TCPReadyState {
  "connecting",
  "open",
  "closing",
  "closed",
};

[NoInterfaceObject]
interface LegacyMozTCPSocket {
  /**
   * Legacy constructor for API compatibility.
   */
  [Throws]
  TCPSocket open(DOMString host, unsigned short port, optional SocketOptions options);

  [Throws]
  TCPServerSocket listen(unsigned short port, optional ServerSocketOptions options, optional unsigned short backlog = 0);
};

[Constructor(DOMString host, unsigned short port, optional SocketOptions options),
 Func="mozilla::dom::TCPSocket::ShouldTCPSocketExist",
 Exposed=(Window,System)]
interface TCPSocket : EventTarget {
  /**
   * Upgrade an insecure connection to use TLS. Throws if the ready state is not OPEN.
   */
  [Throws] void upgradeToSecure();

  /**
   * The UTF16 host of this socket object.
   */
  readonly attribute USVString host;

  /**
   * The port of this socket object.
   */
  readonly attribute unsigned short port;

  /**
   * True if this socket object is an SSL socket.
   */
  readonly attribute boolean ssl;

  /**
   * The number of bytes which have previously been buffered by calls to
   * send on this socket.
   */
  readonly attribute unsigned long long bufferedAmount;

  /**
   * Pause reading incoming data and invocations of the ondata handler until
   * resume is called. Can be called multiple times without resuming.
   */
  void suspend();

  /**
   * Resume reading incoming data and invoking ondata as usual. There must be
   * an equal number of resume as suspends that took place. Throws if the
   * socket is not suspended.
   */
  [Throws]
  void resume();

  /**
   * Close the socket.
   */
  void close();

  /**
   * Write data to the socket.
   *
   * @param data The data to write to the socket.
   *
   * @return Send returns true or false as a hint to the caller that
   *         they may either continue sending more data immediately, or
   *         may want to wait until the other side has read some of the
   *         data which has already been written to the socket before
   *         buffering more. If send returns true, then less than 64k
   *         has been buffered and it's safe to immediately write more.
   *         If send returns false, then more than 64k has been buffered,
   *         and the caller may wish to wait until the ondrain event
   *         handler has been called before buffering more data by more
   *         calls to send.
   * 
   * @throws Throws if the ready state is not OPEN.
   */
  [Throws]
  boolean send(ByteString data);

  /**
   * Write data to the socket.
   *
   * @param data The data to write to the socket.
   * @param byteOffset The offset within the data from which to begin writing.
   * @param byteLength The number of bytes to write.
   *                   Defaults to the byte length of the ArrayBuffer if not present,
   *                   and clamped to (length - byteOffset).
   *
   * @return Send returns true or false as a hint to the caller that
   *         they may either continue sending more data immediately, or
   *         may want to wait until the other side has read some of the
   *         data which has already been written to the socket before
   *         buffering more. If send returns true, then less than 64k
   *         has been buffered and it's safe to immediately write more.
   *         If send returns false, then more than 64k has been buffered,
   *         and the caller may wish to wait until the ondrain event
   *         handler has been called before buffering more data by more
   *         calls to send.
   * 
   * @throws Throws if the ready state is not OPEN.
   */
  [Throws]
  boolean send(ArrayBuffer data, optional unsigned long byteOffset = 0, optional unsigned long byteLength);

  /**
   * The readyState attribute indicates which state the socket is currently
   * in.
   */
  readonly attribute TCPReadyState readyState;

  /**
   * The binaryType attribute indicates which mode this socket uses for
   * sending and receiving data. If the binaryType: "arraybuffer" option
   * was passed to the open method that created this socket, binaryType
   * will be "arraybuffer". Otherwise, it will be "string".
   */
  readonly attribute TCPSocketBinaryType binaryType;

  /**
   * The "open" event is dispatched when the connection to the server
   * has been established. If the connection is refused, the "error" event
   * will be dispatched, instead.
   */
  attribute EventHandler onopen;

  /**
   * After send has buffered more than 64k of data, it returns false to
   * indicate that the client should pause before sending more data, to
   * avoid accumulating large buffers. This is only advisory, and the client
   * is free to ignore it and buffer as much data as desired, but if reducing
   * the size of buffers is important (especially for a streaming application)
   * the "drain" event will be dispatched once the previously-buffered data has
   * been written to the network, at which point the client can resume calling
   * send again.
   */
  attribute EventHandler ondrain;

  /**
   * The "data" event will be dispatched repeatedly and asynchronously after
   * "open" is dispatched, every time some data was available from the server
   * and was read. The event object will be a TCPSocketEvent; if the "arraybuffer"
   * binaryType was passed to the constructor, the data attribute of the event
   * object will be an ArrayBuffer. If not, it will be a normal JavaScript string,
   * truncated at the first null byte found in the payload and the remainder
   * interpreted as ASCII bytes.
   *
   * At any time, the client may choose to pause reading and receiving "data"
   * events by calling the socket's suspend() method. Further "data" events
   * will be paused until resume() is called.
   */
  attribute EventHandler ondata;

  /**
   * The "error" event will be dispatched when there is an error. The event
   * object will be a TCPSocketErrorEvent.
   *
   * If an "error" event is dispatched before an "open" one, the connection
   * was refused, and the "close" event will not be dispatched. If an "error"
   * event is dispatched after an "open" event, the connection was lost,
   * and a "close" event will be dispatched subsequently.
   */
  attribute EventHandler onerror;

  /**
   * The "close" event is dispatched once the underlying network socket
   * has been closed, either by the server, or by the client calling
   * close.
   *
   * If the "error" event was not dispatched before "close", then one of
   * the sides cleanly closed the connection.
   */
  attribute EventHandler onclose;  
};