mirror of
https://gitlab.winehq.org/wine/wine-gecko.git
synced 2024-09-13 09:24:08 -07:00
240 lines
8.4 KiB
Plaintext
240 lines
8.4 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;
|
|
|
|
/**
|
|
* 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;
|
|
};
|
|
|