chrome.sockets.tcp

Description: Use the chrome.sockets.tcp API to send and receive data over the network using TCP connections. This API supersedes the TCP functionality previously found in the chrome.socket API.
Availability: Since Chrome 33.
Manifest: "sockets": {...}

Summary

Types
SocketProperties
SocketInfo
Methods
create chrome.sockets.tcp.create( SocketProperties properties, function callback)
update chrome.sockets.tcp.update(integer socketId, SocketProperties properties, function callback)
setPaused chrome.sockets.tcp.setPaused(integer socketId, boolean paused, function callback)
setKeepAlive chrome.sockets.tcp.setKeepAlive(integer socketId, boolean enable, integer delay, function callback)
setNoDelay chrome.sockets.tcp.setNoDelay(integer socketId, boolean noDelay, function callback)
connect chrome.sockets.tcp.connect(integer socketId, string peerAddress, integer peerPort, function callback)
disconnect chrome.sockets.tcp.disconnect(integer socketId, function callback)
secure chrome.sockets.tcp.secure(integer socketId, object options, function callback)
send chrome.sockets.tcp.send(integer socketId, ArrayBuffer data, function callback)
close chrome.sockets.tcp.close(integer socketId, function callback)
getInfo chrome.sockets.tcp.getInfo(integer socketId, function callback)
getSockets chrome.sockets.tcp.getSockets(function callback)
Events
onReceive
onReceiveError

Types

SocketProperties

properties
boolean (optional) persistent

Flag indicating if the socket is left open when the event page of the application is unloaded (see Manage App Lifecycle). The default value is "false." When the application is loaded, any sockets previously opened with persistent=true can be fetched with getSockets.

string (optional) name

An application-defined string associated with the socket.

integer (optional) bufferSize

The size of the buffer used to receive data. The default value is 4096.

SocketInfo

properties
integer socketId

The socket identifier.

boolean persistent

Flag indicating whether the socket is left open when the application is suspended (see SocketProperties.persistent).

string (optional) name

Application-defined string associated with the socket.

integer (optional) bufferSize

The size of the buffer used to receive data. If no buffer size has been specified explictly, the value is not provided.

boolean paused

Flag indicating whether a connected socket blocks its peer from sending more data (see setPaused).

boolean connected

Flag indicating whether the socket is connected to a remote peer.

string (optional) localAddress

If the underlying socket is connected, contains its local IPv4/6 address.

integer (optional) localPort

If the underlying socket is connected, contains its local port.

string (optional) peerAddress

If the underlying socket is connected, contains the peer/ IPv4/6 address.

integer (optional) peerPort

If the underlying socket is connected, contains the peer port.

Methods

create

chrome.sockets.tcp.create( SocketProperties properties, function callback)

Creates a TCP socket.

Parameters
SocketProperties (optional) properties

The socket properties (optional).

function callback

Called when the socket has been created.

The callback parameter should be a function that looks like this:

function(object createInfo) {...};
object createInfo

The result of the socket creation.

integer socketId

The ID of the newly created socket. Note that socket IDs created from this API are not compatible with socket IDs created from other APIs, such as the deprecated socket API.

update

chrome.sockets.tcp.update(integer socketId, SocketProperties properties, function callback)

Updates the socket properties.

Parameters
integer socketId

The socket identifier.

SocketProperties properties

The properties to update.

function (optional) callback

Called when the properties are updated.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

setPaused

chrome.sockets.tcp.setPaused(integer socketId, boolean paused, function callback)

Enables or disables the application from receiving messages from its peer. The default value is "false". Pausing a socket is typically used by an application to throttle data sent by its peer. When a socket is paused, no onReceive event is raised. When a socket is connected and un-paused, onReceive events are raised again when messages are received.

Parameters
integer socketId
boolean paused
function (optional) callback

Callback from the setPaused method.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

setKeepAlive

chrome.sockets.tcp.setKeepAlive(integer socketId, boolean enable, integer delay, function callback)

Enables or disables the keep-alive functionality for a TCP connection.

Parameters
integer socketId

The socket identifier.

boolean enable

If true, enable keep-alive functionality.

integer (optional) delay

Set the delay seconds between the last data packet received and the first keepalive probe. Default is 0.

function callback

Called when the setKeepAlive attempt is complete.

The callback parameter should be a function that looks like this:

function(integer result) {...};
integer result

The result code returned from the underlying network call. A negative value indicates an error.

setNoDelay

chrome.sockets.tcp.setNoDelay(integer socketId, boolean noDelay, function callback)

Sets or clears TCP_NODELAY for a TCP connection. Nagle's algorithm will be disabled when TCP_NODELAY is set.

Parameters
integer socketId

The socket identifier.

boolean noDelay

If true, disables Nagle's algorithm.

function callback

Called when the setNoDelay attempt is complete.

The callback parameter should be a function that looks like this:

function(integer result) {...};
integer result

The result code returned from the underlying network call. A negative value indicates an error.

connect

chrome.sockets.tcp.connect(integer socketId, string peerAddress, integer peerPort, function callback)

Connects the socket to a remote machine. When the connect operation completes successfully, onReceive events are raised when data is received from the peer. If a network error occurs while the runtime is receiving packets, a onReceiveError event is raised, at which point no more onReceive event will be raised for this socket until the resume method is called.

Parameters
integer socketId

The socket identifier.

string peerAddress

The address of the remote machine. DNS name, IPv4 and IPv6 formats are supported.

integer peerPort

The port of the remote machine.

function callback

Called when the connect attempt is complete.

The callback parameter should be a function that looks like this:

function(integer result) {...};
integer result

The result code returned from the underlying network call. A negative value indicates an error.

disconnect

chrome.sockets.tcp.disconnect(integer socketId, function callback)

Disconnects the socket.

Parameters
integer socketId

The socket identifier.

function (optional) callback

Called when the disconnect attempt is complete.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

secure

chrome.sockets.tcp.secure(integer socketId, object options, function callback)

Since Chrome 38.

Start a TLS client connection over the connected TCP client socket.

Parameters
integer socketId

The existing, connected socket to use.

object (optional) options

Constraints and parameters for the TLS connection.

object (optional) tlsVersion
string (optional) min

The minimum and maximum acceptable versions of TLS. These will be tls1, tls1.1, or tls1.2.

string (optional) max
function callback

Called when the connection attempt is complete.

The callback parameter should be a function that looks like this:

function(integer result) {...};
integer result

send

chrome.sockets.tcp.send(integer socketId, ArrayBuffer data, function callback)

Sends data on the given TCP socket.

Parameters
integer socketId

The socket identifier.

ArrayBuffer data

The data to send.

function callback

Called when the send operation completes.

The callback parameter should be a function that looks like this:

function(object sendInfo) {...};
object sendInfo

Result of the send method.

integer resultCode

The result code returned from the underlying network call. A negative value indicates an error.

integer (optional) bytesSent

The number of bytes sent (if result == 0)

close

chrome.sockets.tcp.close(integer socketId, function callback)

Closes the socket and releases the address/port the socket is bound to. Each socket created should be closed after use. The socket id is no no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked.

Parameters
integer socketId

The socket identifier.

function (optional) callback

Called when the close operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

getInfo

chrome.sockets.tcp.getInfo(integer socketId, function callback)

Retrieves the state of the given socket.

Parameters
integer socketId

The socket identifier.

function callback

Called when the socket state is available.

The callback parameter should be a function that looks like this:

function( SocketInfo socketInfo) {...};
SocketInfo socketInfo

Object containing the socket information.

getSockets

chrome.sockets.tcp.getSockets(function callback)

Retrieves the list of currently opened sockets owned by the application.

Parameters
function callback

Called when the list of sockets is available.

The callback parameter should be a function that looks like this:

function(array of SocketInfo socketInfos) {...};
array of SocketInfo socketInfos

Array of object containing socket information.

Events

onReceive

Event raised when data has been received for a given socket.

addListener

chrome.sockets.tcp.onReceive.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(object info) {...};
object info

The event data.

integer socketId

The socket identifier.

ArrayBuffer data

The data received, with a maxium size of bufferSize.

onReceiveError

Event raised when a network error occured while the runtime was waiting for data on the socket address and port. Once this event is raised, the socket is set to paused and no more onReceive events are raised for this socket.

addListener

chrome.sockets.tcp.onReceiveError.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(object info) {...};
object info

The event data.

integer socketId

The socket identifier.

integer resultCode

The result code returned from the underlying network call.