TCP Socket API
Non-standard
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.
This API is available on Firefox OS for privileged or certified applications only.
Summary
The TCPSocket API offers a whole API to open and use a TCP connection. This allows app makers to implement any protocol available on top of TCP such as IMAP, IRC, POP, HTTP, etc., or even build their own to sustain any specific needs they could have.
Permission
In order to use that API, as for all privileged API, it's required to request permission to use it within the app manifest.
"permissions" : { "tcp-socket" : { "description" : "Create TCP sockets and communicate over them." } }
Overview
This API is available through the Navigator.mozTCPSocket
property which is itself a TCPSocket
object.
Opening a socket
Opening a socket is done with the TCPSocket.open()
method. This method expects up to three parameters:
- A string representing the hostname of the server to connect to (it can also be its raw IP address).
- A number representing the TCP port to be used by the socket (some protocols have a standard port, for example 80 for HTTP, 447 for SSL, 25 for SMTP, etc. Port numbers beyond 1024 are not assigned to any specific protocol and can be used for any purpose.)
- A optional object containing up to two options: a boolean named
useSecureTransport
is the socket needed to use SSL,false
by default; and a string namedbinaryType
allows to state the type of data retrieved by the application through thedata
event, with the expected valuesstring
orarraybuffer
. By default, it isstring
.
var socket = navigator.mozTCPSocket.open('localhost', 80);
Note: Only certified apps can use a port below 1024.
Listening for connections
Listening for connections is done with the TCPSocket.listen()
Requires FirefoxOS 1.2 method. This method expects up to three parameters:
- A number representing the TCP port to be used to listen for connections.
- An optional object specifying the details of the socket. This object expects a property called
binaryType
, which is a string that can have two possible values: "string" or "arraybuffer". If the value is "arraybuffer" then theTCPSocket.send()
will useArrayBuffer
s and the data received from the remote connection will also be available in that format. - A number representing the maximum length that the pending connections queue can grow.
var socket = navigator.mozTCPSocket.listen(8080);
Note: Only certified apps can listen on a port below 1024.
Sending data
Sending data is done using the TCPSocket.send()
method. The data sent can be either a string or a Uint8Array
object; however, remember that a TCP socket always deals with binary data. For that reason, it's a lot safer to use Uint8Array
instead of a string when sending data.
As per the TCP protocol, it's a good optimization to send a maximum of 64kb of data at the same time. As long as less than 64kb has been buffered, a call to the send
method returns true
. Once the buffer is full, the method will return false
which indicates the application should make a pause to flush the buffer. Each time the buffer is flushed, a drain
event is fired and the application can use it to resume data sending.
It's possible to know exactly the current amount of data buffered with the TCPSocket.bufferedAmount
property.
function getData() { var data; // do stuff that will retrieve data return data; } function pushData() { var data; do { data = getData(); } while (data != null && socket.send(data)); } // Each time the buffer is flushed // we try to send data again. socket.ondrain = pushData; // Start sending data. pushData();
Getting data
Each time the socket gets some data from the host, it fires a data
event. This event will give access to the data from the socket. The type of the data depends on the option set when the socket was opened (see above).
socket.ondata = function (event) { if (typeof event.data === 'string') { console.log('Get a string: ' + event.data); } else { console.log('Get a Uint8Array'); } }
As the data
event is fired as much as needed, it can sometimes be necessary to pause the flow of incoming data. To that end, calling the TCPSocket.suspend()
method will pause reading incoming data and stop firing the data
. It's possible to start reading data and firing events again by calling the TCPSocket.resume()
method.
Closing a socket
Closing a socket is simply done using TCPSocket.close()
.
Standard
Not part of any specification yet; however, this API is discussed at W3C as part of the System Applications Working Group under the Raw Sockets proposal.
See also
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/tcp_socket_api