gecko/dom/network/interfaces/nsIDOMTCPSocket.idl

/* 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 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.
 */

#include "domstubs.idl"
#include "nsIDOMEvent.idl"

// 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); 

[scriptable, uuid(b82e17da-6476-11e1-8813-57a2ffe9e42c)]
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.
   *
   *        useSSL: true to create an SSL socket. Defaults to false.
   *
   *        binaryType: "arraybuffer" to use UInt8 array
   *          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);

  /**
   * 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 Uint8Array instance.
   *             If binaryType: "string" was passed, or if no binaryType
   *             option was specified, then this object should be an
   *             ordinary JavaScript string.
   *
   * @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);

  /**
   * 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 Uint8Array. 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;
};

/*
 * 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(fff9ed4a-5e94-4fc0-84e4-7f4d35d0a26c)]
interface nsITCPSocketInternal : nsISupports {
  // Trigger the callback for |type| and provide an Error() object with the given data
  void callListenerError(in DOMString type, in DOMString message, in DOMString filename,
                         in uint32_t lineNumber, in uint32_t columnNumber);

  // 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 a Uint8Array 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 and bufferedAmount values with the provided data
  void updateReadyStateAndBuffered(in DOMString readyState, in uint32_t bufferedAmount);
};

/**
 * 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 Uint8Array;
   * 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;
};