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