The Tor Browser / file revision

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

 };