The Tor Browser: comparison dom/network/interfaces/nsIDOMTCPSocket.idl

--1:000000000000
+:7cd9726a88c7
+/* 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 / file comparison

comparison: dom/network/interfaces/nsIDOMTCPSocket.idl

dom/network/interfaces/nsIDOMTCPSocket.idl