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 (d1ed7de67f5a)

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 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327
/* 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/. */

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

#include "domstubs.idl"
#include "nsIDOMEvent.idl"
#include "nsITCPSocketChild.idl"
#include "nsIDOMTCPServerSocket.idl"

interface nsISocketTransport;

// Bug 731746 - Allow chrome JS object to implement nsIDOMEventTarget
// nsITCPSocket should be an nsIEventTarget but js objects
// cannot be an nsIEventTarget yet
// #include "nsIEventTarget.idl"

// Bug 723206 - Constructors implemented in JS from IDL should be
//              allowed to have arguments
//
//  Once bug 723206 will be fixed, this method could be replaced by
//  arguments when instantiating a TCPSocket object. For example it will
//  be possible to do (similarly to the WebSocket API):
//    var s = new MozTCPSocket(host, port);

// Bug 797561 - Expose a server tcp socket API to web applications


[scriptable, uuid(65f6d2c8-4be6-4695-958d-0735e8935289)]
interface nsIDOMTCPSocket : nsISupports
{
  /**
   * Create and return a socket object which will attempt to connect to
   * the given host and port.
   *
   * @param host The hostname of the server to connect to.
   * @param port The port to connect to.
   * @param options An object specifying one or more parameters which
   *                determine the details of the socket.
   *
   *        useSecureTransport: true to create an SSL socket. Defaults to false.
   *
   *        binaryType: "arraybuffer" to use ArrayBuffer
   *          instances in the ondata callback and as the argument
   *          to send. Defaults to "string", to use JavaScript strings.
   *
   * @return The new TCPSocket instance.
   */
  nsIDOMTCPSocket open(in DOMString host, in unsigned short port, [optional] in jsval options);

  /**
   * Listen on a port
   *
   * @param localPort The port of the server socket. Pass -1 to indicate no preference,
   *                  and a port will be selected automatically.
   * @param options An object specifying one or more parameters which
   *                determine the details of the socket.
   *
   *        binaryType: "arraybuffer" to use ArrayBuffer
   *          instances in the ondata callback and as the argument
   *          to send. Defaults to "string", to use JavaScript strings.
   * @param backlog The maximum length the queue of pending connections may grow to.
   *                This parameter may be silently limited by the operating system.
   *                Pass -1 to use the default value.
   *
   * @return The new TCPServerSocket instance.
   */
  nsIDOMTCPServerSocket listen(in unsigned short localPort, [optional] in jsval options,
                               [optional] in unsigned short backlog);

  /**
   * Enable secure on channel.
   */
  void upgradeToSecure();

  /**
   * The host of this socket object.
   */
  readonly attribute DOMString 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 bufferedAmount;

  /**
   * Pause reading incoming data and invocations of the ondata handler until
   * resume is called.
   */
  void suspend();

  /**
   * Resume reading incoming data and invoking ondata as usual.
   */
  void resume();

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

  /**
   * Write data to the socket.
   *
   * @param data The data to write to the socket. If
   *             binaryType: "arraybuffer" was passed in the options
   *             object, then this object should be an ArrayBuffer instance.
   *             If binaryType: "string" was passed, or if no binaryType
   *             option was specified, then this object should be an
   *             ordinary JavaScript string.
   * @param byteOffset The offset within the data from which to begin writing.
   *                   Has no effect on non-ArrayBuffer data.
   * @param byteLength The number of bytes to write. Has no effect on
   *                   non-ArrayBuffer data.
   *
   * @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.
   */
  boolean send(in jsval data, [optional] in unsigned long byteOffset, [optional] in unsigned long byteLength);

  /**
   * The readyState attribute indicates which state the socket is currently
   * in. The state will be either "connecting", "open", "closing", or "closed".
   */
  readonly attribute DOMString 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 DOMString binaryType;

  /**
   * The onopen event handler is called when the connection to the server
   * has been established. If the connection is refused, onerror will be
   * called, instead.
   */
  attribute jsval 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)
   * ondrain will be called once the previously-buffered data has been written
   * to the network, at which point the client can resume calling send again.
   */
  attribute jsval ondrain;

  /**
   * The ondata handler will be called repeatedly and asynchronously after
   * onopen has been called, every time some data was available from the server
   * and was read. If binaryType: "arraybuffer" was passed to open, the data
   * attribute of the event object will be an ArrayBuffer. If not, it will be a
   * normal JavaScript string.
   *
   * At any time, the client may choose to pause reading and receiving ondata
   * callbacks, by calling the socket's suspend() method. Further invocations
   * of ondata will be paused until resume() is called.
   */
  attribute jsval ondata;

  /**
   * The onerror handler will be called when there is an error. The data
   * attribute of the event passed to the onerror handler will have a
   * description of the kind of error.
   *
   * If onerror is called before onopen, the error was connection refused,
   * and onclose will not be called. If onerror is called after onopen,
   * the connection was lost, and onclose will be called after onerror.
   */
  attribute jsval onerror;

  /**
   * The onclose handler is called once the underlying network socket
   * has been closed, either by the server, or by the client calling
   * close.
   *
   * If onerror was not called before onclose, then either side cleanly
   * closed the connection.
   */
  attribute jsval onclose;
};

/*
 * This interface is implemented in TCPSocket.js as an internal interfaces
 * for use in cross-process socket implementation.
 * Needed to account for multiple possible types that can be provided to
 * the socket callbacks as arguments.
 */
[scriptable, uuid(017f130f-2477-4215-8783-57eada957699)]
interface nsITCPSocketInternal : nsISupports {
  // Trigger the callback for |type| and provide a DOMError() object with the given data
  void callListenerError(in DOMString type, in DOMString name);

  // Trigger the callback for |type| and provide a string argument
  void callListenerData(in DOMString type, in DOMString data);

  // Trigger the callback for |type| and provide an ArrayBuffer argument
  void callListenerArrayBuffer(in DOMString type, in jsval data);

  // Trigger the callback for |type| with no argument
  void callListenerVoid(in DOMString type);

  // Update the DOM object's readyState.
  // @param readyState
  //        new ready state to be set to TCPSocket.
  void updateReadyState(in DOMString readyState);

  // Update the DOM object's bufferedAmount value with a tracking number to
  // ensure the update request is sent after child's send() invocation.
  // @param bufferedAmount
  //        TCPSocket parent's bufferedAmount.
  // @param trackingNumber
  //        A number to ensure the bufferedAmount is updated after data
  //        from child are sent to parent.
  void updateBufferedAmount(in uint32_t bufferedAmount,
                            in uint32_t trackingNumber);

  // Create a socket object on the parent side.
  // This is called in accepting any open request on the parent side.
  // 
  // @param transport
  //        The accepted socket transport.
  // @param binaryType
  //        "arraybuffer" to use ArrayBuffer instances 
  //        in the ondata callback and as the argument to send.
  nsIDOMTCPSocket createAcceptedParent(in nsISocketTransport transport,
                                       in DOMString binaryType);

  // Create a DOM socket on the child side
  // This is called when the socket is accepted on the parent side.
  //
  // @param socketChild
  //        The socket child object for the IPC implementation.
  // @param binaryType
  //        "arraybuffer" to use ArrayBuffer instances
  //        in the ondata callback and as the argument to send.
  // @param window
  //        An object to create ArrayBuffer for this window. See Bug 831107.
  nsIDOMTCPSocket createAcceptedChild(in nsITCPSocketChild socketChild,
                                      in DOMString binaryType,
                                      in nsIDOMWindow window);

  // Set App ID.
  void setAppId(in unsigned long appId);

  // Set a callback that handles the request from a TCP socket parent when that
  // socket parent wants to notify that its bufferedAmount is updated.
  void setOnUpdateBufferedAmountHandler(in jsval handler);

  // Providing child process with ability to pass more arguments to parent's
  // send() function.
  // @param trackingNumber
  //        To ensure the request to update bufferedAmount in child is after
  //        lastest send() invocation from child.
  void onRecvSendFromChild(in jsval data, in unsigned long byteOffset,
                           in unsigned long byteLength, in unsigned long trackingNumber);
};

/**
 * nsITCPSocketEvent is the event object which is passed as the
 * first argument to all the event handler callbacks. It contains
 * the socket that was associated with the event, the type of event,
 * and the data associated with the event (if any).
 */

[scriptable, uuid(0f2abcca-b483-4539-a3e8-345707f75c44)]
interface nsITCPSocketEvent : nsISupports {
  /**
   * The socket object which produced this event.
   */
  readonly attribute nsIDOMTCPSocket target;

  /**
   * The type of this event. One of:
   *
   * open
   * error
   * data
   * drain
   * close
   */
  readonly attribute DOMString type;

  /**
   * The data related to this event, if any. In the ondata callback,
   * data will be the bytes read from the network; if the binaryType
   * of the socket was "arraybuffer", this value will be of type ArrayBuffer;
   * otherwise, it will be a normal JavaScript string.
   *
   * In the onerror callback, data will be a string with a description
   * of the error.
   *
   * In the other callbacks, data will be an empty string.
   */
  readonly attribute jsval data;
};