michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
michael@0:  * You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: /**
michael@0:  * MozTCPSocket exposes a TCP client and server sockets
michael@0:  * to highly privileged apps. It provides a buffered, non-blocking
michael@0:  * interface for sending. For receiving, it uses an asynchronous,
michael@0:  * event handler based interface.
michael@0:  */
michael@0: 
michael@0: #include "domstubs.idl"
michael@0: #include "nsIDOMEvent.idl"
michael@0: #include "nsITCPSocketChild.idl"
michael@0: #include "nsIDOMTCPServerSocket.idl"
michael@0: 
michael@0: interface nsISocketTransport;
michael@0: 
michael@0: // Bug 731746 - Allow chrome JS object to implement nsIDOMEventTarget
michael@0: // nsITCPSocket should be an nsIEventTarget but js objects
michael@0: // cannot be an nsIEventTarget yet
michael@0: // #include "nsIEventTarget.idl"
michael@0: 
michael@0: // Bug 723206 - Constructors implemented in JS from IDL should be
michael@0: //              allowed to have arguments
michael@0: //
michael@0: //  Once bug 723206 will be fixed, this method could be replaced by
michael@0: //  arguments when instantiating a TCPSocket object. For example it will
michael@0: //  be possible to do (similarly to the WebSocket API):
michael@0: //    var s = new MozTCPSocket(host, port);
michael@0: 
michael@0: // Bug 797561 - Expose a server tcp socket API to web applications
michael@0: 
michael@0: 
michael@0: [scriptable, uuid(65f6d2c8-4be6-4695-958d-0735e8935289)]
michael@0: interface nsIDOMTCPSocket : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Create and return a socket object which will attempt to connect to
michael@0:    * the given host and port.
michael@0:    *
michael@0:    * @param host The hostname of the server to connect to.
michael@0:    * @param port The port to connect to.
michael@0:    * @param options An object specifying one or more parameters which
michael@0:    *                determine the details of the socket.
michael@0:    *
michael@0:    *        useSecureTransport: true to create an SSL socket. Defaults to false.
michael@0:    *
michael@0:    *        binaryType: "arraybuffer" to use ArrayBuffer
michael@0:    *          instances in the ondata callback and as the argument
michael@0:    *          to send. Defaults to "string", to use JavaScript strings.
michael@0:    *
michael@0:    * @return The new TCPSocket instance.
michael@0:    */
michael@0:   nsIDOMTCPSocket open(in DOMString host, in unsigned short port, [optional] in jsval options);
michael@0: 
michael@0:   /**
michael@0:    * Listen on a port
michael@0:    *
michael@0:    * @param localPort The port of the server socket. Pass -1 to indicate no preference,
michael@0:    *                  and a port will be selected automatically.
michael@0:    * @param options An object specifying one or more parameters which
michael@0:    *                determine the details of the socket.
michael@0:    *
michael@0:    *        binaryType: "arraybuffer" to use ArrayBuffer
michael@0:    *          instances in the ondata callback and as the argument
michael@0:    *          to send. Defaults to "string", to use JavaScript strings.
michael@0:    * @param backlog The maximum length the queue of pending connections may grow to.
michael@0:    *                This parameter may be silently limited by the operating system.
michael@0:    *                Pass -1 to use the default value.
michael@0:    *
michael@0:    * @return The new TCPServerSocket instance.
michael@0:    */
michael@0:   nsIDOMTCPServerSocket listen(in unsigned short localPort, [optional] in jsval options,
michael@0:                                [optional] in unsigned short backlog);
michael@0: 
michael@0:   /**
michael@0:    * Enable secure on channel.
michael@0:    */
michael@0:   void upgradeToSecure();
michael@0: 
michael@0:   /**
michael@0:    * The host of this socket object.
michael@0:    */
michael@0:   readonly attribute DOMString host;
michael@0: 
michael@0:   /**
michael@0:    * The port of this socket object.
michael@0:    */
michael@0:   readonly attribute unsigned short port;
michael@0: 
michael@0:   /**
michael@0:    * True if this socket object is an SSL socket.
michael@0:    */
michael@0:   readonly attribute boolean ssl;
michael@0: 
michael@0:   /**
michael@0:    * The number of bytes which have previously been buffered by calls to
michael@0:    * send on this socket.
michael@0:    */
michael@0:   readonly attribute unsigned long bufferedAmount;
michael@0: 
michael@0:   /**
michael@0:    * Pause reading incoming data and invocations of the ondata handler until
michael@0:    * resume is called.
michael@0:    */
michael@0:   void suspend();
michael@0: 
michael@0:   /**
michael@0:    * Resume reading incoming data and invoking ondata as usual.
michael@0:    */
michael@0:   void resume();
michael@0: 
michael@0:   /**
michael@0:    * Close the socket.
michael@0:    */
michael@0:   void close();
michael@0: 
michael@0:   /**
michael@0:    * Write data to the socket.
michael@0:    *
michael@0:    * @param data The data to write to the socket. If
michael@0:    *             binaryType: "arraybuffer" was passed in the options
michael@0:    *             object, then this object should be an ArrayBuffer instance.
michael@0:    *             If binaryType: "string" was passed, or if no binaryType
michael@0:    *             option was specified, then this object should be an
michael@0:    *             ordinary JavaScript string.
michael@0:    * @param byteOffset The offset within the data from which to begin writing.
michael@0:    *                   Has no effect on non-ArrayBuffer data.
michael@0:    * @param byteLength The number of bytes to write. Has no effect on
michael@0:    *                   non-ArrayBuffer data.
michael@0:    *
michael@0:    * @return Send returns true or false as a hint to the caller that
michael@0:    *         they may either continue sending more data immediately, or
michael@0:    *         may want to wait until the other side has read some of the
michael@0:    *         data which has already been written to the socket before
michael@0:    *         buffering more. If send returns true, then less than 64k
michael@0:    *         has been buffered and it's safe to immediately write more.
michael@0:    *         If send returns false, then more than 64k has been buffered,
michael@0:    *         and the caller may wish to wait until the ondrain event
michael@0:    *         handler has been called before buffering more data by more
michael@0:    *         calls to send.
michael@0:    */
michael@0:   boolean send(in jsval data, [optional] in unsigned long byteOffset, [optional] in unsigned long byteLength);
michael@0: 
michael@0:   /**
michael@0:    * The readyState attribute indicates which state the socket is currently
michael@0:    * in. The state will be either "connecting", "open", "closing", or "closed".
michael@0:    */
michael@0:   readonly attribute DOMString readyState;
michael@0: 
michael@0:   /**
michael@0:    * The binaryType attribute indicates which mode this socket uses for
michael@0:    * sending and receiving data. If the binaryType: "arraybuffer" option
michael@0:    * was passed to the open method that created this socket, binaryType
michael@0:    * will be "arraybuffer". Otherwise, it will be "string".
michael@0:    */
michael@0:   readonly attribute DOMString binaryType;
michael@0: 
michael@0:   /**
michael@0:    * The onopen event handler is called when the connection to the server
michael@0:    * has been established. If the connection is refused, onerror will be
michael@0:    * called, instead.
michael@0:    */
michael@0:   attribute jsval onopen;
michael@0: 
michael@0:   /**
michael@0:    * After send has buffered more than 64k of data, it returns false to
michael@0:    * indicate that the client should pause before sending more data, to
michael@0:    * avoid accumulating large buffers. This is only advisory, and the client
michael@0:    * is free to ignore it and buffer as much data as desired, but if reducing
michael@0:    * the size of buffers is important (especially for a streaming application)
michael@0:    * ondrain will be called once the previously-buffered data has been written
michael@0:    * to the network, at which point the client can resume calling send again.
michael@0:    */
michael@0:   attribute jsval ondrain;
michael@0: 
michael@0:   /**
michael@0:    * The ondata handler will be called repeatedly and asynchronously after
michael@0:    * onopen has been called, every time some data was available from the server
michael@0:    * and was read. If binaryType: "arraybuffer" was passed to open, the data
michael@0:    * attribute of the event object will be an ArrayBuffer. If not, it will be a
michael@0:    * normal JavaScript string.
michael@0:    *
michael@0:    * At any time, the client may choose to pause reading and receiving ondata
michael@0:    * callbacks, by calling the socket's suspend() method. Further invocations
michael@0:    * of ondata will be paused until resume() is called.
michael@0:    */
michael@0:   attribute jsval ondata;
michael@0: 
michael@0:   /**
michael@0:    * The onerror handler will be called when there is an error. The data
michael@0:    * attribute of the event passed to the onerror handler will have a
michael@0:    * description of the kind of error.
michael@0:    *
michael@0:    * If onerror is called before onopen, the error was connection refused,
michael@0:    * and onclose will not be called. If onerror is called after onopen,
michael@0:    * the connection was lost, and onclose will be called after onerror.
michael@0:    */
michael@0:   attribute jsval onerror;
michael@0: 
michael@0:   /**
michael@0:    * The onclose handler is called once the underlying network socket
michael@0:    * has been closed, either by the server, or by the client calling
michael@0:    * close.
michael@0:    *
michael@0:    * If onerror was not called before onclose, then either side cleanly
michael@0:    * closed the connection.
michael@0:    */
michael@0:   attribute jsval onclose;
michael@0: };
michael@0: 
michael@0: /*
michael@0:  * This interface is implemented in TCPSocket.js as an internal interfaces
michael@0:  * for use in cross-process socket implementation.
michael@0:  * Needed to account for multiple possible types that can be provided to
michael@0:  * the socket callbacks as arguments.
michael@0:  */
michael@0: [scriptable, uuid(017f130f-2477-4215-8783-57eada957699)]
michael@0: interface nsITCPSocketInternal : nsISupports {
michael@0:   // Trigger the callback for |type| and provide a DOMError() object with the given data
michael@0:   void callListenerError(in DOMString type, in DOMString name);
michael@0: 
michael@0:   // Trigger the callback for |type| and provide a string argument
michael@0:   void callListenerData(in DOMString type, in DOMString data);
michael@0: 
michael@0:   // Trigger the callback for |type| and provide an ArrayBuffer argument
michael@0:   void callListenerArrayBuffer(in DOMString type, in jsval data);
michael@0: 
michael@0:   // Trigger the callback for |type| with no argument
michael@0:   void callListenerVoid(in DOMString type);
michael@0: 
michael@0:   // Update the DOM object's readyState.
michael@0:   // @param readyState
michael@0:   //        new ready state to be set to TCPSocket.
michael@0:   void updateReadyState(in DOMString readyState);
michael@0: 
michael@0:   // Update the DOM object's bufferedAmount value with a tracking number to
michael@0:   // ensure the update request is sent after child's send() invocation.
michael@0:   // @param bufferedAmount
michael@0:   //        TCPSocket parent's bufferedAmount.
michael@0:   // @param trackingNumber
michael@0:   //        A number to ensure the bufferedAmount is updated after data
michael@0:   //        from child are sent to parent.
michael@0:   void updateBufferedAmount(in uint32_t bufferedAmount,
michael@0:                             in uint32_t trackingNumber);
michael@0: 
michael@0:   // Create a socket object on the parent side.
michael@0:   // This is called in accepting any open request on the parent side.
michael@0:   // 
michael@0:   // @param transport
michael@0:   //        The accepted socket transport.
michael@0:   // @param binaryType
michael@0:   //        "arraybuffer" to use ArrayBuffer instances 
michael@0:   //        in the ondata callback and as the argument to send.
michael@0:   nsIDOMTCPSocket createAcceptedParent(in nsISocketTransport transport,
michael@0:                                        in DOMString binaryType);
michael@0: 
michael@0:   // Create a DOM socket on the child side
michael@0:   // This is called when the socket is accepted on the parent side.
michael@0:   //
michael@0:   // @param socketChild
michael@0:   //        The socket child object for the IPC implementation.
michael@0:   // @param binaryType
michael@0:   //        "arraybuffer" to use ArrayBuffer instances
michael@0:   //        in the ondata callback and as the argument to send.
michael@0:   // @param window
michael@0:   //        An object to create ArrayBuffer for this window. See Bug 831107.
michael@0:   nsIDOMTCPSocket createAcceptedChild(in nsITCPSocketChild socketChild,
michael@0:                                       in DOMString binaryType,
michael@0:                                       in nsIDOMWindow window);
michael@0: 
michael@0:   // Set App ID.
michael@0:   void setAppId(in unsigned long appId);
michael@0: 
michael@0:   // Set a callback that handles the request from a TCP socket parent when that
michael@0:   // socket parent wants to notify that its bufferedAmount is updated.
michael@0:   void setOnUpdateBufferedAmountHandler(in jsval handler);
michael@0: 
michael@0:   // Providing child process with ability to pass more arguments to parent's
michael@0:   // send() function.
michael@0:   // @param trackingNumber
michael@0:   //        To ensure the request to update bufferedAmount in child is after
michael@0:   //        lastest send() invocation from child.
michael@0:   void onRecvSendFromChild(in jsval data, in unsigned long byteOffset,
michael@0:                            in unsigned long byteLength, in unsigned long trackingNumber);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * nsITCPSocketEvent is the event object which is passed as the
michael@0:  * first argument to all the event handler callbacks. It contains
michael@0:  * the socket that was associated with the event, the type of event,
michael@0:  * and the data associated with the event (if any).
michael@0:  */
michael@0: 
michael@0: [scriptable, uuid(0f2abcca-b483-4539-a3e8-345707f75c44)]
michael@0: interface nsITCPSocketEvent : nsISupports {
michael@0:   /**
michael@0:    * The socket object which produced this event.
michael@0:    */
michael@0:   readonly attribute nsIDOMTCPSocket target;
michael@0: 
michael@0:   /**
michael@0:    * The type of this event. One of:
michael@0:    *
michael@0:    * open
michael@0:    * error
michael@0:    * data
michael@0:    * drain
michael@0:    * close
michael@0:    */
michael@0:   readonly attribute DOMString type;
michael@0: 
michael@0:   /**
michael@0:    * The data related to this event, if any. In the ondata callback,
michael@0:    * data will be the bytes read from the network; if the binaryType
michael@0:    * of the socket was "arraybuffer", this value will be of type ArrayBuffer;
michael@0:    * otherwise, it will be a normal JavaScript string.
michael@0:    *
michael@0:    * In the onerror callback, data will be a string with a description
michael@0:    * of the error.
michael@0:    *
michael@0:    * In the other callbacks, data will be an empty string.
michael@0:    */
michael@0:   readonly attribute jsval data;
michael@0: };
michael@0: