gecko/dom/network/interfaces/nsIDOMTCPSocket.idl

220 lines
7.5 KiB
Plaintext

/* 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;
readonly attribute DOMString CONNECTING;
readonly attribute DOMString OPEN;
readonly attribute DOMString CLOSING;
readonly attribute DOMString CLOSED;
/**
* 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;
};
/**
* 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 socket;
/**
* The type of this event. One of:
*
* onopen
* onerror
* ondata
* ondrain
* onclose
*/
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;
};