The Tor Browser: dom/network/interfaces/nsIDOMTCPSocket.idl@b8a032363ba2 (annotated)

dom/network/interfaces/nsIDOMTCPSocket.idl@b8a032363ba2 (annotated)

dom/network/interfaces/nsIDOMTCPSocket.idl

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

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

The Tor Browser / annotate

dom/network/interfaces/nsIDOMTCPSocket.idl@b8a032363ba2 (annotated)

dom/network/interfaces/nsIDOMTCPSocket.idl