1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/dom/network/interfaces/nsIDOMTCPSocket.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,327 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this file,
1.6 + * You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +/**
1.9 + * MozTCPSocket exposes a TCP client and server sockets
1.10 + * to highly privileged apps. It provides a buffered, non-blocking
1.11 + * interface for sending. For receiving, it uses an asynchronous,
1.12 + * event handler based interface.
1.13 + */
1.14 +
1.15 +#include "domstubs.idl"
1.16 +#include "nsIDOMEvent.idl"
1.17 +#include "nsITCPSocketChild.idl"
1.18 +#include "nsIDOMTCPServerSocket.idl"
1.19 +
1.20 +interface nsISocketTransport;
1.21 +
1.22 +// Bug 731746 - Allow chrome JS object to implement nsIDOMEventTarget
1.23 +// nsITCPSocket should be an nsIEventTarget but js objects
1.24 +// cannot be an nsIEventTarget yet
1.25 +// #include "nsIEventTarget.idl"
1.26 +
1.27 +// Bug 723206 - Constructors implemented in JS from IDL should be
1.28 +// allowed to have arguments
1.29 +//
1.30 +// Once bug 723206 will be fixed, this method could be replaced by
1.31 +// arguments when instantiating a TCPSocket object. For example it will
1.32 +// be possible to do (similarly to the WebSocket API):
1.33 +// var s = new MozTCPSocket(host, port);
1.34 +
1.35 +// Bug 797561 - Expose a server tcp socket API to web applications
1.36 +
1.37 +
1.38 +[scriptable, uuid(65f6d2c8-4be6-4695-958d-0735e8935289)]
1.39 +interface nsIDOMTCPSocket : nsISupports
1.40 +{
1.41 + /**
1.42 + * Create and return a socket object which will attempt to connect to
1.43 + * the given host and port.
1.44 + *
1.45 + * @param host The hostname of the server to connect to.
1.46 + * @param port The port to connect to.
1.47 + * @param options An object specifying one or more parameters which
1.48 + * determine the details of the socket.
1.49 + *
1.50 + * useSecureTransport: true to create an SSL socket. Defaults to false.
1.51 + *
1.52 + * binaryType: "arraybuffer" to use ArrayBuffer
1.53 + * instances in the ondata callback and as the argument
1.54 + * to send. Defaults to "string", to use JavaScript strings.
1.55 + *
1.56 + * @return The new TCPSocket instance.
1.57 + */
1.58 + nsIDOMTCPSocket open(in DOMString host, in unsigned short port, [optional] in jsval options);
1.59 +
1.60 + /**
1.61 + * Listen on a port
1.62 + *
1.63 + * @param localPort The port of the server socket. Pass -1 to indicate no preference,
1.64 + * and a port will be selected automatically.
1.65 + * @param options An object specifying one or more parameters which
1.66 + * determine the details of the socket.
1.67 + *
1.68 + * binaryType: "arraybuffer" to use ArrayBuffer
1.69 + * instances in the ondata callback and as the argument
1.70 + * to send. Defaults to "string", to use JavaScript strings.
1.71 + * @param backlog The maximum length the queue of pending connections may grow to.
1.72 + * This parameter may be silently limited by the operating system.
1.73 + * Pass -1 to use the default value.
1.74 + *
1.75 + * @return The new TCPServerSocket instance.
1.76 + */
1.77 + nsIDOMTCPServerSocket listen(in unsigned short localPort, [optional] in jsval options,
1.78 + [optional] in unsigned short backlog);
1.79 +
1.80 + /**
1.81 + * Enable secure on channel.
1.82 + */
1.83 + void upgradeToSecure();
1.84 +
1.85 + /**
1.86 + * The host of this socket object.
1.87 + */
1.88 + readonly attribute DOMString host;
1.89 +
1.90 + /**
1.91 + * The port of this socket object.
1.92 + */
1.93 + readonly attribute unsigned short port;
1.94 +
1.95 + /**
1.96 + * True if this socket object is an SSL socket.
1.97 + */
1.98 + readonly attribute boolean ssl;
1.99 +
1.100 + /**
1.101 + * The number of bytes which have previously been buffered by calls to
1.102 + * send on this socket.
1.103 + */
1.104 + readonly attribute unsigned long bufferedAmount;
1.105 +
1.106 + /**
1.107 + * Pause reading incoming data and invocations of the ondata handler until
1.108 + * resume is called.
1.109 + */
1.110 + void suspend();
1.111 +
1.112 + /**
1.113 + * Resume reading incoming data and invoking ondata as usual.
1.114 + */
1.115 + void resume();
1.116 +
1.117 + /**
1.118 + * Close the socket.
1.119 + */
1.120 + void close();
1.121 +
1.122 + /**
1.123 + * Write data to the socket.
1.124 + *
1.125 + * @param data The data to write to the socket. If
1.126 + * binaryType: "arraybuffer" was passed in the options
1.127 + * object, then this object should be an ArrayBuffer instance.
1.128 + * If binaryType: "string" was passed, or if no binaryType
1.129 + * option was specified, then this object should be an
1.130 + * ordinary JavaScript string.
1.131 + * @param byteOffset The offset within the data from which to begin writing.
1.132 + * Has no effect on non-ArrayBuffer data.
1.133 + * @param byteLength The number of bytes to write. Has no effect on
1.134 + * non-ArrayBuffer data.
1.135 + *
1.136 + * @return Send returns true or false as a hint to the caller that
1.137 + * they may either continue sending more data immediately, or
1.138 + * may want to wait until the other side has read some of the
1.139 + * data which has already been written to the socket before
1.140 + * buffering more. If send returns true, then less than 64k
1.141 + * has been buffered and it's safe to immediately write more.
1.142 + * If send returns false, then more than 64k has been buffered,
1.143 + * and the caller may wish to wait until the ondrain event
1.144 + * handler has been called before buffering more data by more
1.145 + * calls to send.
1.146 + */
1.147 + boolean send(in jsval data, [optional] in unsigned long byteOffset, [optional] in unsigned long byteLength);
1.148 +
1.149 + /**
1.150 + * The readyState attribute indicates which state the socket is currently
1.151 + * in. The state will be either "connecting", "open", "closing", or "closed".
1.152 + */
1.153 + readonly attribute DOMString readyState;
1.154 +
1.155 + /**
1.156 + * The binaryType attribute indicates which mode this socket uses for
1.157 + * sending and receiving data. If the binaryType: "arraybuffer" option
1.158 + * was passed to the open method that created this socket, binaryType
1.159 + * will be "arraybuffer". Otherwise, it will be "string".
1.160 + */
1.161 + readonly attribute DOMString binaryType;
1.162 +
1.163 + /**
1.164 + * The onopen event handler is called when the connection to the server
1.165 + * has been established. If the connection is refused, onerror will be
1.166 + * called, instead.
1.167 + */
1.168 + attribute jsval onopen;
1.169 +
1.170 + /**
1.171 + * After send has buffered more than 64k of data, it returns false to
1.172 + * indicate that the client should pause before sending more data, to
1.173 + * avoid accumulating large buffers. This is only advisory, and the client
1.174 + * is free to ignore it and buffer as much data as desired, but if reducing
1.175 + * the size of buffers is important (especially for a streaming application)
1.176 + * ondrain will be called once the previously-buffered data has been written
1.177 + * to the network, at which point the client can resume calling send again.
1.178 + */
1.179 + attribute jsval ondrain;
1.180 +
1.181 + /**
1.182 + * The ondata handler will be called repeatedly and asynchronously after
1.183 + * onopen has been called, every time some data was available from the server
1.184 + * and was read. If binaryType: "arraybuffer" was passed to open, the data
1.185 + * attribute of the event object will be an ArrayBuffer. If not, it will be a
1.186 + * normal JavaScript string.
1.187 + *
1.188 + * At any time, the client may choose to pause reading and receiving ondata
1.189 + * callbacks, by calling the socket's suspend() method. Further invocations
1.190 + * of ondata will be paused until resume() is called.
1.191 + */
1.192 + attribute jsval ondata;
1.193 +
1.194 + /**
1.195 + * The onerror handler will be called when there is an error. The data
1.196 + * attribute of the event passed to the onerror handler will have a
1.197 + * description of the kind of error.
1.198 + *
1.199 + * If onerror is called before onopen, the error was connection refused,
1.200 + * and onclose will not be called. If onerror is called after onopen,
1.201 + * the connection was lost, and onclose will be called after onerror.
1.202 + */
1.203 + attribute jsval onerror;
1.204 +
1.205 + /**
1.206 + * The onclose handler is called once the underlying network socket
1.207 + * has been closed, either by the server, or by the client calling
1.208 + * close.
1.209 + *
1.210 + * If onerror was not called before onclose, then either side cleanly
1.211 + * closed the connection.
1.212 + */
1.213 + attribute jsval onclose;
1.214 +};
1.215 +
1.216 +/*
1.217 + * This interface is implemented in TCPSocket.js as an internal interfaces
1.218 + * for use in cross-process socket implementation.
1.219 + * Needed to account for multiple possible types that can be provided to
1.220 + * the socket callbacks as arguments.
1.221 + */
1.222 +[scriptable, uuid(017f130f-2477-4215-8783-57eada957699)]
1.223 +interface nsITCPSocketInternal : nsISupports {
1.224 + // Trigger the callback for |type| and provide a DOMError() object with the given data
1.225 + void callListenerError(in DOMString type, in DOMString name);
1.226 +
1.227 + // Trigger the callback for |type| and provide a string argument
1.228 + void callListenerData(in DOMString type, in DOMString data);
1.229 +
1.230 + // Trigger the callback for |type| and provide an ArrayBuffer argument
1.231 + void callListenerArrayBuffer(in DOMString type, in jsval data);
1.232 +
1.233 + // Trigger the callback for |type| with no argument
1.234 + void callListenerVoid(in DOMString type);
1.235 +
1.236 + // Update the DOM object's readyState.
1.237 + // @param readyState
1.238 + // new ready state to be set to TCPSocket.
1.239 + void updateReadyState(in DOMString readyState);
1.240 +
1.241 + // Update the DOM object's bufferedAmount value with a tracking number to
1.242 + // ensure the update request is sent after child's send() invocation.
1.243 + // @param bufferedAmount
1.244 + // TCPSocket parent's bufferedAmount.
1.245 + // @param trackingNumber
1.246 + // A number to ensure the bufferedAmount is updated after data
1.247 + // from child are sent to parent.
1.248 + void updateBufferedAmount(in uint32_t bufferedAmount,
1.249 + in uint32_t trackingNumber);
1.250 +
1.251 + // Create a socket object on the parent side.
1.252 + // This is called in accepting any open request on the parent side.
1.253 + //
1.254 + // @param transport
1.255 + // The accepted socket transport.
1.256 + // @param binaryType
1.257 + // "arraybuffer" to use ArrayBuffer instances
1.258 + // in the ondata callback and as the argument to send.
1.259 + nsIDOMTCPSocket createAcceptedParent(in nsISocketTransport transport,
1.260 + in DOMString binaryType);
1.261 +
1.262 + // Create a DOM socket on the child side
1.263 + // This is called when the socket is accepted on the parent side.
1.264 + //
1.265 + // @param socketChild
1.266 + // The socket child object for the IPC implementation.
1.267 + // @param binaryType
1.268 + // "arraybuffer" to use ArrayBuffer instances
1.269 + // in the ondata callback and as the argument to send.
1.270 + // @param window
1.271 + // An object to create ArrayBuffer for this window. See Bug 831107.
1.272 + nsIDOMTCPSocket createAcceptedChild(in nsITCPSocketChild socketChild,
1.273 + in DOMString binaryType,
1.274 + in nsIDOMWindow window);
1.275 +
1.276 + // Set App ID.
1.277 + void setAppId(in unsigned long appId);
1.278 +
1.279 + // Set a callback that handles the request from a TCP socket parent when that
1.280 + // socket parent wants to notify that its bufferedAmount is updated.
1.281 + void setOnUpdateBufferedAmountHandler(in jsval handler);
1.282 +
1.283 + // Providing child process with ability to pass more arguments to parent's
1.284 + // send() function.
1.285 + // @param trackingNumber
1.286 + // To ensure the request to update bufferedAmount in child is after
1.287 + // lastest send() invocation from child.
1.288 + void onRecvSendFromChild(in jsval data, in unsigned long byteOffset,
1.289 + in unsigned long byteLength, in unsigned long trackingNumber);
1.290 +};
1.291 +
1.292 +/**
1.293 + * nsITCPSocketEvent is the event object which is passed as the
1.294 + * first argument to all the event handler callbacks. It contains
1.295 + * the socket that was associated with the event, the type of event,
1.296 + * and the data associated with the event (if any).
1.297 + */
1.298 +
1.299 +[scriptable, uuid(0f2abcca-b483-4539-a3e8-345707f75c44)]
1.300 +interface nsITCPSocketEvent : nsISupports {
1.301 + /**
1.302 + * The socket object which produced this event.
1.303 + */
1.304 + readonly attribute nsIDOMTCPSocket target;
1.305 +
1.306 + /**
1.307 + * The type of this event. One of:
1.308 + *
1.309 + * open
1.310 + * error
1.311 + * data
1.312 + * drain
1.313 + * close
1.314 + */
1.315 + readonly attribute DOMString type;
1.316 +
1.317 + /**
1.318 + * The data related to this event, if any. In the ondata callback,
1.319 + * data will be the bytes read from the network; if the binaryType
1.320 + * of the socket was "arraybuffer", this value will be of type ArrayBuffer;
1.321 + * otherwise, it will be a normal JavaScript string.
1.322 + *
1.323 + * In the onerror callback, data will be a string with a description
1.324 + * of the error.
1.325 + *
1.326 + * In the other callbacks, data will be an empty string.
1.327 + */
1.328 + readonly attribute jsval data;
1.329 +};
1.330 +
