chrome.socket

Description: Use the chrome.socket API to send and receive data over the network using TCP and UDP connections. Note: Starting with Chrome 33, this API is deprecated in favor of the sockets.udp, sockets.tcp and sockets.tcpServer APIs.
Availability: Since Chrome 35.
Permissions: {"socket": ["rule1", "rule2"]}
For example: {"socket": ["tcp-connect:*:*"]} means connecting on any port of any host. See Network Communications for rule syntax.
Learn More: Network Communications
Build Apps with Sencha ExtJS
Chrome Apps Office Hours: Networking APIs
Chrome Apps Office Hours: Controlling an AR ParrotDrone

Summary

Types
SocketType
WriteInfo
Methods
create − chrome.socket.create( SocketType type, object options, function callback)
destroy − chrome.socket.destroy(integer socketId)
connect − chrome.socket.connect(integer socketId, string hostname, integer port, function callback)
bind − chrome.socket.bind(integer socketId, string address, integer port, function callback)
disconnect − chrome.socket.disconnect(integer socketId)
read − chrome.socket.read(integer socketId, integer bufferSize, function callback)
write − chrome.socket.write(integer socketId, ArrayBuffer data, function callback)
recvFrom − chrome.socket.recvFrom(integer socketId, integer bufferSize, function callback)
sendTo − chrome.socket.sendTo(integer socketId, ArrayBuffer data, string address, integer port, function callback)
listen − chrome.socket.listen(integer socketId, string address, integer port, integer backlog, function callback)
accept − chrome.socket.accept(integer socketId, function callback)
setKeepAlive − chrome.socket.setKeepAlive(integer socketId, boolean enable, integer delay, function callback)
setNoDelay − chrome.socket.setNoDelay(integer socketId, boolean noDelay, function callback)
getInfo − chrome.socket.getInfo(integer socketId, function callback)
getNetworkList − chrome.socket.getNetworkList(function callback)
joinGroup − chrome.socket.joinGroup(integer socketId, string address, function callback)
leaveGroup − chrome.socket.leaveGroup(integer socketId, string address, function callback)
setMulticastTimeToLive − chrome.socket.setMulticastTimeToLive(integer socketId, integer ttl, function callback)
setMulticastLoopbackMode − chrome.socket.setMulticastLoopbackMode(integer socketId, boolean enabled, function callback)
getJoinedGroups − chrome.socket.getJoinedGroups(integer socketId, function callback)
secure − chrome.socket.secure(integer socketId, object options, function callback)

Types

SocketType

Enum
"tcp", or "udp"

WriteInfo

properties
integer bytesWritten

The number of bytes sent, or a negative error code.

Methods

create

chrome.socket.create( SocketType type, object options, function callback)

Creates a socket of the specified type that will connect to the specified remote machine.

Parameters
SocketType type

The type of socket to create. Must be tcp or udp.

object (optional) options

The socket options.

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
integer socketId

The id of the newly created socket.

destroy

chrome.socket.destroy(integer socketId)

Destroys the socket. Each socket created should be destroyed after use.

Parameters
integer socketId

The socketId.

connect

chrome.socket.connect(integer socketId, string hostname, integer port, function callback)

Connects the socket to the remote machine (for a tcp socket). For a udp socket, this sets the default address which packets are sent to and read from for read() and write() calls.

Parameters
integer socketId

The socketId.

string hostname

The hostname or IP address of the remote machine.

integer port

The port of the remote machine.

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

bind

chrome.socket.bind(integer socketId, string address, integer port, function callback)

Binds the local address for socket. Currently, it does not support TCP socket.

Parameters
integer socketId

The socketId.

string address

The address of the local machine.

integer port

The port of the local machine.

function callback

Called when the bind attempt is complete.

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

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

disconnect

chrome.socket.disconnect(integer socketId)

Disconnects the socket. For UDP sockets, disconnect is a non-operation but is safe to call.

Parameters
integer socketId

The socketId.

read

chrome.socket.read(integer socketId, integer bufferSize, function callback)

Reads data from the given connected socket.

Parameters
integer socketId

The socketId.

integer (optional) bufferSize

The read buffer size.

function callback

Delivers data that was available to be read without blocking.

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

function(object readInfo) {...};
object readInfo
integer resultCode

The resultCode returned from the underlying read() call.

ArrayBuffer data

write

chrome.socket.write(integer socketId, ArrayBuffer data, function callback)

Writes data on the given connected socket.

Parameters
integer socketId

The socketId.

ArrayBuffer data

The data to write.

function callback

Called when the write operation completes without blocking or an error occurs.

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

function( WriteInfo writeInfo) {...};
WriteInfo writeInfo

recvFrom

chrome.socket.recvFrom(integer socketId, integer bufferSize, function callback)

Receives data from the given UDP socket.

Parameters
integer socketId

The socketId.

integer (optional) bufferSize

The receive buffer size.

function callback

Returns result of the recvFrom operation.

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

function(object recvFromInfo) {...};
object recvFromInfo
integer resultCode

The resultCode returned from the underlying recvfrom() call.

ArrayBuffer data
string address

The address of the remote machine.

integer port

sendTo

chrome.socket.sendTo(integer socketId, ArrayBuffer data, string address, integer port, function callback)

Sends data on the given UDP socket to the given address and port.

Parameters
integer socketId

The socketId.

ArrayBuffer data

The data to write.

string address

The address of the remote machine.

integer port

The port of the remote machine.

function callback

Called when the send operation completes without blocking or an error occurs.

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

function( WriteInfo writeInfo) {...};
WriteInfo writeInfo

listen

chrome.socket.listen(integer socketId, string address, integer port, integer backlog, function callback)

This method applies to TCP sockets only. Listens for connections on the specified port and address. This effectively makes this a server socket, and client socket functions (connect, read, write) can no longer be used on this socket.

Parameters
integer socketId

The socketId.

string address

The address of the local machine.

integer port

The port of the local machine.

integer (optional) backlog

Length of the socket's listen queue.

function callback

Called when listen operation completes.

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

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

accept

chrome.socket.accept(integer socketId, function callback)

This method applies to TCP sockets only. Registers a callback function to be called when a connection is accepted on this listening server socket. Listen must be called first. If there is already an active accept callback, this callback will be invoked immediately with an error as the resultCode.

Parameters
integer socketId

The socketId.

function callback

The callback is invoked when a new socket is accepted.

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

function(object acceptInfo) {...};
object acceptInfo
integer resultCode
integer (optional) socketId

The id of the accepted socket.

setKeepAlive

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

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

Parameters
integer socketId

The socketId.

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(boolean result) {...};
boolean result

setNoDelay

chrome.socket.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 socketId.

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(boolean result) {...};
boolean result

getInfo

chrome.socket.getInfo(integer socketId, function callback)

Retrieves the state of the given socket.

Parameters
integer socketId

The socketId.

function callback

Called when the state is available.

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

function(object result) {...};
object result
SocketType socketType

The type of the passed socket. This will be tcp or udp.

boolean connected

Whether or not the underlying socket is connected.

For tcp sockets, this will remain true even if the remote peer has disconnected. Reading or writing to the socket may then result in an error, hinting that this socket should be disconnected via disconnect().

For udp sockets, this just represents whether a default remote address has been specified for reading and writing packets.
string (optional) peerAddress

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

integer (optional) peerPort

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

string (optional) localAddress

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

integer (optional) localPort

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

getNetworkList

chrome.socket.getNetworkList(function callback)

Retrieves information about local adapters on this system.

Parameters
function callback

Called when local adapter information is available.

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

function(array of object result) {...};
array of object result

Properties of each object

string name

The underlying name of the adapter. On *nix, this will typically be "eth0", "lo", etc.

string address

The available IPv4/6 address.

integer prefixLength

The prefix length

joinGroup

chrome.socket.joinGroup(integer socketId, string address, function callback)

Join the multicast group and start to receive packets from that group. The socket must be of UDP type and must be bound to a local port before calling this method.

Parameters
integer socketId

The socketId.

string address

The group address to join. Domain names are not supported.

function callback

Called when the join group operation is done with an integer parameter indicating the platform-independent error code.

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

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

leaveGroup

chrome.socket.leaveGroup(integer socketId, string address, function callback)

Leave the multicast group previously joined using joinGroup. It's not necessary to leave the multicast group before destroying the socket or exiting. This is automatically called by the OS.

Leaving the group will prevent the router from sending multicast datagrams to the local host, presuming no other process on the host is still joined to the group.

Parameters
integer socketId

The socketId.

string address

The group address to leave. Domain names are not supported.

function callback

Called when the leave group operation is done with an integer parameter indicating the platform-independent error code.

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

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

setMulticastTimeToLive

chrome.socket.setMulticastTimeToLive(integer socketId, integer ttl, function callback)

Set the time-to-live of multicast packets sent to the multicast group.

Calling this method does not require multicast permissions.

Parameters
integer socketId

The socketId.

integer ttl

The time-to-live value.

function callback

Called when the configuration operation is done.

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

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

setMulticastLoopbackMode

chrome.socket.setMulticastLoopbackMode(integer socketId, boolean enabled, function callback)

Set whether multicast packets sent from the host to the multicast group will be looped back to the host.

Note: the behavior of setMulticastLoopbackMode is slightly different between Windows and Unix-like systems. The inconsistency happens only when there is more than one application on the same host joined to the same multicast group while having different settings on multicast loopback mode. On Windows, the applications with loopback off will not RECEIVE the loopback packets; while on Unix-like systems, the applications with loopback off will not SEND the loopback packets to other applications on the same host. See MSDN: http://goo.gl/6vqbj

Calling this method does not require multicast permissions.

Parameters
integer socketId

The socketId.

boolean enabled

Indicate whether to enable loopback mode.

function callback

Called when the configuration operation is done.

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

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

getJoinedGroups

chrome.socket.getJoinedGroups(integer socketId, function callback)

Get the multicast group addresses the socket is currently joined to.

Parameters
integer socketId

The socketId.

function callback

Called with an array of strings of the result.

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

function(array of string groups) {...};
array of string groups

secure

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

Since Chrome 38.

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

Parameters
integer socketId

The 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, tls1.2, or tls1.3.

string (optional) max
function callback

Called when the TLS connection attempt is complete.

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

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