summaryrefslogtreecommitdiffstats
path: root/dom/webidl/TCPSocket.webidl
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
commit26a029d407be480d791972afb5975cf62c9360a6 (patch)
treef435a8308119effd964b339f76abb83a57c29483 /dom/webidl/TCPSocket.webidl
parentInitial commit. (diff)
downloadfirefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz
firefox-26a029d407be480d791972afb5975cf62c9360a6.zip
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'dom/webidl/TCPSocket.webidl')
-rw-r--r--dom/webidl/TCPSocket.webidl221
1 files changed, 221 insertions, 0 deletions
diff --git a/dom/webidl/TCPSocket.webidl b/dom/webidl/TCPSocket.webidl
new file mode 100644
index 0000000000..cf5ab4fdd5
--- /dev/null
+++ b/dom/webidl/TCPSocket.webidl
@@ -0,0 +1,221 @@
+/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* 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/. */
+
+/**
+ * TCPSocket 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.
+ */
+
+interface nsISocketTransport;
+
+enum TCPSocketBinaryType {
+ "arraybuffer",
+ "string"
+};
+
+dictionary SocketOptions {
+ boolean useSecureTransport = false;
+ TCPSocketBinaryType binaryType = "string";
+};
+
+enum TCPReadyState {
+ "connecting",
+ "open",
+ "closing",
+ "closed",
+};
+
+[LegacyNoInterfaceObject,
+ Exposed=Window]
+interface LegacyMozTCPSocket {
+ /**
+ * Legacy constructor for API compatibility.
+ */
+ [Throws]
+ TCPSocket open(DOMString host, unsigned short port, optional SocketOptions options = {});
+
+ [Throws]
+ TCPServerSocket listen(unsigned short port, optional ServerSocketOptions options = {}, optional unsigned short backlog = 0);
+};
+
+[Func="mozilla::dom::TCPSocket::ShouldTCPSocketExist",
+ Exposed=Window]
+interface TCPSocket : EventTarget {
+ [Throws]
+ constructor(DOMString host, unsigned short port,
+ optional SocketOptions options = {});
+
+ /**
+ * Upgrade an insecure connection to use TLS. Throws if the ready state is not OPEN.
+ */
+ [Throws] undefined upgradeToSecure();
+
+ /**
+ * The raw internal socket transport.
+ */
+ readonly attribute nsISocketTransport? transport;
+
+ /**
+ * The UTF16 host of this socket object.
+ */
+ readonly attribute USVString 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 long bufferedAmount;
+
+ /**
+ * Pause reading incoming data and invocations of the ondata handler until
+ * resume is called. Can be called multiple times without resuming.
+ */
+ undefined suspend();
+
+ /**
+ * Resume reading incoming data and invoking ondata as usual. There must be
+ * an equal number of resume as suspends that took place. Throws if the
+ * socket is not suspended.
+ */
+ [Throws]
+ undefined resume();
+
+ /**
+ * Close the socket.
+ */
+ undefined close();
+
+ /**
+ * Close the socket immediately without waiting for unsent data.
+ */
+ [ChromeOnly] undefined closeImmediately();
+
+ /**
+ * Write data to the socket.
+ *
+ * @param data The data to write to the socket.
+ *
+ * @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.
+ *
+ * @throws Throws if the ready state is not OPEN.
+ */
+ [Throws]
+ boolean send(ByteString data);
+
+ /**
+ * Write data to the socket.
+ *
+ * @param data The data to write to the socket.
+ * @param byteOffset The offset within the data from which to begin writing.
+ * @param byteLength The number of bytes to write.
+ * Defaults to the byte length of the ArrayBuffer if not present,
+ * and clamped to (length - byteOffset).
+ *
+ * @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.
+ *
+ * @throws Throws if the ready state is not OPEN.
+ */
+ [Throws]
+ boolean send(ArrayBuffer data, optional unsigned long byteOffset = 0, optional unsigned long byteLength);
+
+ /**
+ * The readyState attribute indicates which state the socket is currently
+ * in.
+ */
+ readonly attribute TCPReadyState 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 TCPSocketBinaryType binaryType;
+
+ /**
+ * The "open" event is dispatched when the connection to the server
+ * has been established. If the connection is refused, the "error" event
+ * will be dispatched, instead.
+ */
+ attribute EventHandler 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)
+ * the "drain" event will be dispatched once the previously-buffered data has
+ * been written to the network, at which point the client can resume calling
+ * send again.
+ */
+ attribute EventHandler ondrain;
+
+ /**
+ * The "data" event will be dispatched repeatedly and asynchronously after
+ * "open" is dispatched, every time some data was available from the server
+ * and was read. The event object will be a TCPSocketEvent; if the "arraybuffer"
+ * binaryType was passed to the constructor, the data attribute of the event
+ * object will be an ArrayBuffer. If not, it will be a normal JavaScript string,
+ * truncated at the first null byte found in the payload and the remainder
+ * interpreted as ASCII bytes.
+ *
+ * At any time, the client may choose to pause reading and receiving "data"
+ * events by calling the socket's suspend() method. Further "data" events
+ * will be paused until resume() is called.
+ */
+ attribute EventHandler ondata;
+
+ /**
+ * The "error" event will be dispatched when there is an error. The event
+ * object will be a TCPSocketErrorEvent.
+ *
+ * If an "error" event is dispatched before an "open" one, the connection
+ * was refused, and the "close" event will not be dispatched. If an "error"
+ * event is dispatched after an "open" event, the connection was lost,
+ * and a "close" event will be dispatched subsequently.
+ */
+ attribute EventHandler onerror;
+
+ /**
+ * The "close" event is dispatched once the underlying network socket
+ * has been closed, either by the server, or by the client calling
+ * close.
+ *
+ * If the "error" event was not dispatched before "close", then one of
+ * the sides cleanly closed the connection.
+ */
+ attribute EventHandler onclose;
+};