chrome.socket

This API is part of the deprecated Chrome Apps platform. Learn more about migrating your app.

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.
Permissions
socket
Availability
Pending

Summary

Types
AcceptInfo
CreateInfo
CreateOptions
NetworkInterface
ReadInfo
RecvFromInfo
SecureOptions
SocketInfo
SocketType
TLSVersionConstraints
WriteInfo
Methods
accept
bind
connect
create
destroy
disconnect
getInfo
getJoinedGroups
getNetworkList
joinGroup
leaveGroup
listen
read
recvFrom
secure
sendTo
setKeepAlive
setMulticastLoopbackMode
setMulticastTimeToLive
setNoDelay
write

Types

AcceptInfo

Properties

resultCode
number
socketId
number optional
The id of the accepted socket.

CreateInfo

Properties

socketId
number
The id of the newly created socket.

CreateOptions

NetworkInterface

Properties

address
string
The available IPv4/6 address.
name
string
The underlying name of the adapter. On *nix, this will typically be "eth0", "lo", etc.
prefixLength
number
The prefix length

ReadInfo

Properties

data
ArrayBuffer
resultCode
number
The resultCode returned from the underlying read() call.

RecvFromInfo

Properties

address
string
The address of the remote machine.
data
ArrayBuffer
port
number
resultCode
number
The resultCode returned from the underlying recvfrom() call.

SecureOptions

Properties

tlsVersion
TLSVersionConstraints optional

SocketInfo

Properties

connected
boolean
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.
localAddress
string optional
If the underlying socket is bound or connected, contains its local IPv4/6 address.
localPort
number optional
If the underlying socket is bound or connected, contains its local port.
peerAddress
string optional
If the underlying socket is connected, contains the IPv4/6 address of the peer.
peerPort
number optional
If the underlying socket is connected, contains the port of the connected peer.
socketType
SocketType
The type of the passed socket. This will be tcp or udp.

SocketType

Type

"tcp", or "udp"

TLSVersionConstraints

Properties

max
string optional
min
string optional
The minimum and maximum acceptable versions of TLS. These will be tls1, tls1.1, tls1.2, or tls1.3.

WriteInfo

Properties

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

Methods

accept

chrome.socket.accept(
  socketId: number,
  callback: function,
)

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

socketId
number
The socketId.
callback
function
The callback parameter looks like: (acceptInfo: AcceptInfo) => void
- acceptInfo
  AcceptInfo

bind

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

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

Parameters

socketId
number
The socketId.
address
string
The address of the local machine.
port
number
The port of the local machine.
callback
function
The callback parameter looks like: (result: number) => void
- result
  number

connect

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

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

socketId
number
The socketId.
hostname
string
The hostname or IP address of the remote machine.
port
number
The port of the remote machine.
callback
function
The callback parameter looks like: (result: number) => void
- result
  number

create

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

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

Parameters

type
SocketType
The type of socket to create. Must be tcp or udp.
options
CreateOptions
The socket options.
callback
function
The callback parameter looks like: (createInfo: CreateInfo) => void
- createInfo
  CreateInfo

destroy

chrome.socket.destroy(
  socketId: number,
)

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

Parameters

socketId
number
The socketId.

disconnect

chrome.socket.disconnect(
  socketId: number,
)

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

Parameters

socketId
number
The socketId.

getInfo

chrome.socket.getInfo(
  socketId: number,
  callback: function,
)

Retrieves the state of the given socket.

Parameters

socketId
number
The socketId.
callback
function
The callback parameter looks like: (result: SocketInfo) => void
- result
  SocketInfo

getJoinedGroups

chrome.socket.getJoinedGroups(
  socketId: number,
  callback: function,
)

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

Parameters

socketId
number
The socketId.
callback
function
The callback parameter looks like: (groups: string[]) => void
- groups
  string[]

getNetworkList

chrome.socket.getNetworkList(
  callback: function,
)

Retrieves information about local adapters on this system.

Parameters

callback
function
The callback parameter looks like: (result: NetworkInterface[]) => void
- result
  NetworkInterface[]

joinGroup

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

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

socketId
number
The socketId.
address
string
The group address to join. Domain names are not supported.
callback
function
The callback parameter looks like: (result: number) => void
- result
  number

leaveGroup

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

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

socketId
number
The socketId.
address
string
The group address to leave. Domain names are not supported.
callback
function
The callback parameter looks like: (result: number) => void
- result
  number

listen

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

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

socketId
number
The socketId.
address
string
The address of the local machine.
port
number
The port of the local machine.
backlog
number
Length of the socket's listen queue.
callback
function
The callback parameter looks like: (result: number) => void
- result
  number

read

chrome.socket.read(
  socketId: number,
  bufferSize: number,
  callback: function,
)

Reads data from the given connected socket.

Parameters

socketId
number
The socketId.
bufferSize
number
The read buffer size.
callback
function
The callback parameter looks like: (readInfo: ReadInfo) => void
- readInfo
  ReadInfo

recvFrom

chrome.socket.recvFrom(
  socketId: number,
  bufferSize: number,
  callback: function,
)

Receives data from the given UDP socket.

Parameters

socketId
number
The socketId.
bufferSize
number
The receive buffer size.
callback
function
The callback parameter looks like: (recvFromInfo: RecvFromInfo) => void
- recvFromInfo
  RecvFromInfo

secure

chrome.socket.secure(
  socketId: number,
  options: SecureOptions,
  callback: function,
)

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

Parameters

socketId
number
The connected socket to use.
options
SecureOptions
Constraints and parameters for the TLS connection.
callback
function
The callback parameter looks like: (result: number) => void
- result
  number

sendTo

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

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

Parameters

socketId
number
The socketId.
data
ArrayBuffer
The data to write.
address
string
The address of the remote machine.
port
number
The port of the remote machine.
callback
function
The callback parameter looks like: (writeInfo: WriteInfo) => void
- writeInfo
  WriteInfo

setKeepAlive

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

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

Parameters

socketId
number
The socketId.
enable
boolean
If true, enable keep-alive functionality.
delay
number
Set the delay seconds between the last data packet received and the first keepalive probe. Default is 0.
callback
function
The callback parameter looks like: (result: boolean) => void
- result
  boolean

setMulticastLoopbackMode

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

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

socketId
number
The socketId.
enabled
boolean
Indicate whether to enable loopback mode.
callback
function
The callback parameter looks like: (result: number) => void
- result
  number

setMulticastTimeToLive

chrome.socket.setMulticastTimeToLive(
  socketId: number,
  ttl: number,
  callback: function,
)

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

Calling this method does not require multicast permissions.

Parameters

socketId
number
The socketId.
ttl
number
The time-to-live value.
callback
function
The callback parameter looks like: (result: number) => void
- result
  number

setNoDelay

chrome.socket.setNoDelay(
  socketId: number,
  noDelay: boolean,
  callback: function,
)

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

Parameters

socketId
number
The socketId.
noDelay
boolean
If true, disables Nagle's algorithm.
callback
function
The callback parameter looks like: (result: boolean) => void
- result
  boolean

write

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

Writes data on the given connected socket.

Parameters

socketId
number
The socketId.
data
ArrayBuffer
The data to write.
callback
function
The callback parameter looks like: (writeInfo: WriteInfo) => void
- writeInfo
  WriteInfo