diff -r 000000000000 -r 6474c204b198 dom/network/interfaces/nsIDOMTCPSocket.idl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/dom/network/interfaces/nsIDOMTCPSocket.idl Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,327 @@ +/* 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; +}; +