зеркало из https://github.com/mozilla/gecko-dev.git
303 строки
11 KiB
Plaintext
303 строки
11 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 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;
|
|
};
|
|
|
|
/*
|
|
* 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(234c664c-3d6c-4859-b45c-4e9a98cb5bdc)]
|
|
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 and bufferedAmount values with the provided data
|
|
void updateReadyStateAndBuffered(in DOMString readyState, in uint32_t bufferedAmount);
|
|
|
|
// 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);
|
|
};
|
|
|
|
/**
|
|
* 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;
|
|
};
|
|
|