chrome.sockets.tcp

Warning

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

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.

Summary

Types
CreateInfo
ReceiveErrorInfo
ReceiveInfo
SecureOptions
SendInfo
SocketInfo
SocketProperties
TLSVersionConstraints
Methods
close
chrome.sockets.tcp.close(socketId: number, callback: function)
connect
chrome.sockets.tcp.connect(socketId: number, peerAddress: string, peerPort: number, callback: function)
create
chrome.sockets.tcp.create(properties?: SocketProperties, callback: function)
disconnect
chrome.sockets.tcp.disconnect(socketId: number, callback: function)
getInfo
chrome.sockets.tcp.getInfo(socketId: number, callback: function)
getSockets
chrome.sockets.tcp.getSockets(callback: function)
secure
chrome.sockets.tcp.secure(socketId: number, options?: SecureOptions, callback: function)
send
chrome.sockets.tcp.send(socketId: number, data: ArrayBuffer, callback: function)
setKeepAlive
chrome.sockets.tcp.setKeepAlive(socketId: number, enable: boolean, delay?: number, callback: function)
setNoDelay
chrome.sockets.tcp.setNoDelay(socketId: number, noDelay: boolean, callback: function)
setPaused
chrome.sockets.tcp.setPaused(socketId: number, paused: boolean, callback: function)
update
chrome.sockets.tcp.update(socketId: number, properties: SocketProperties, callback: function)
Events
onReceive
onReceiveError

Types

CreateInfo

Properties

socketId
number
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.

ReceiveErrorInfo

Properties

resultCode
number
The result code returned from the underlying network call.
socketId
number
The socket identifier.

ReceiveInfo

Properties

data
ArrayBuffer
The data received, with a maxium size of bufferSize.
socketId
number
The socket identifier.

SecureOptions

Properties

tlsVersion
TLSVersionConstraints optional

SendInfo

Properties

bytesSent
number optional
The number of bytes sent (if result == 0)
resultCode
number
The result code returned from the underlying network call. A negative value indicates an error.

SocketInfo

Properties

bufferSize
number optional
The size of the buffer used to receive data. If no buffer size has been specified explictly, the value is not provided.
connected
boolean
Flag indicating whether the socket is connected to a remote peer.
localAddress
string optional
If the underlying socket is connected, contains its local IPv4/6 address.
localPort
number optional
If the underlying socket is connected, contains its local port.
name
string optional
Application-defined string associated with the socket.
paused
boolean
Flag indicating whether a connected socket blocks its peer from sending more data (see setPaused).
peerAddress
string optional
If the underlying socket is connected, contains the peer/ IPv4/6 address.
peerPort
number optional
If the underlying socket is connected, contains the peer port.
persistent
boolean
Flag indicating whether the socket is left open when the application is suspended (see SocketProperties.persistent).
socketId
number
The socket identifier.

SocketProperties

Properties

bufferSize
number optional
The size of the buffer used to receive data. The default value is 4096.
name
string optional
An application-defined string associated with the socket.
persistent
boolean optional
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.

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.

Methods

close

chrome.sockets.tcp.close(socketId: number, callback: function)

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

socketId
number
The socket identifier.
callback
function
Called when the close operation completes.
The callback parameter should be a function that looks like this:
() => {...}

connect

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

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

socketId
number
The socket identifier.
peerAddress
string
The address of the remote machine. DNS name, IPv4 and IPv6 formats are supported.
peerPort
number
The port of the remote machine.
callback
function
Called when the connect attempt is complete.
The callback parameter should be a function that looks like this:
(result: number) => {...}
- result
  number
  The result code returned from the underlying network call. A negative value indicates an error.

create

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

Creates a TCP socket.

Parameters

properties
SocketProperties optional
The socket properties (optional).
callback
function
Called when the socket has been created.
The callback parameter should be a function that looks like this:
(createInfo: CreateInfo) => {...}
- createInfo
  CreateInfo
  The result of the socket creation.

disconnect

chrome.sockets.tcp.disconnect(socketId: number, callback: function)

Disconnects the socket.

Parameters

socketId
number
The socket identifier.
callback
function
Called when the disconnect attempt is complete.
The callback parameter should be a function that looks like this:
() => {...}

getInfo

chrome.sockets.tcp.getInfo(socketId: number, callback: function)

Retrieves the state of the given socket.

Parameters

socketId
number
The socket identifier.
callback
function
Called when the socket state is available.
The callback parameter should be a function that looks like this:
(socketInfo: SocketInfo) => {...}
- socketInfo
  SocketInfo
  Object containing the socket information.

getSockets

chrome.sockets.tcp.getSockets(callback: function)

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

Parameters

callback
function
Called when the list of sockets is available.
The callback parameter should be a function that looks like this:
(socketInfos: SocketInfo[]) => {...}
- socketInfos
  SocketInfo[]
  Array of object containing socket information.

secure

chrome.sockets.tcp.secure(socketId: number, options?: SecureOptions, callback: function)

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

Parameters

socketId
number
The existing, connected socket to use.
options
SecureOptions optional
Constraints and parameters for the TLS connection.
callback
function
Called when the connection attempt is complete.
The callback parameter should be a function that looks like this:
(result: number) => {...}
- result
  number

send

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

Sends data on the given TCP socket.

Parameters

socketId
number
The socket identifier.
data
ArrayBuffer
The data to send.
callback
function
Called when the send operation completes.
The callback parameter should be a function that looks like this:
(sendInfo: SendInfo) => {...}
- sendInfo
  SendInfo
  Result of the send method.

setKeepAlive

chrome.sockets.tcp.setKeepAlive(socketId: number, enable: boolean, delay?: number, callback: function)

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

Parameters

socketId
number
The socket identifier.
enable
boolean
If true, enable keep-alive functionality.
delay
number optional
Set the delay seconds between the last data packet received and the first keepalive probe. Default is 0.
callback
function
Called when the setKeepAlive attempt is complete.
The callback parameter should be a function that looks like this:
(result: number) => {...}
- result
  number
  The result code returned from the underlying network call. A negative value indicates an error.

setNoDelay

chrome.sockets.tcp.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 socket identifier.
noDelay
boolean
If true, disables Nagle's algorithm.
callback
function
Called when the setNoDelay attempt is complete.
The callback parameter should be a function that looks like this:
(result: number) => {...}
- result
  number
  The result code returned from the underlying network call. A negative value indicates an error.

setPaused

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

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

socketId
number
paused
boolean
callback
function
Callback from the setPaused method.
The callback parameter should be a function that looks like this:
() => {...}

update

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

Updates the socket properties.

Parameters

socketId
number
The socket identifier.
properties
SocketProperties
The properties to update.
callback
function
Called when the properties are updated.
The callback parameter should be a function that looks like this:
() => {...}

Events

onReceive

chrome.sockets.tcp.onReceive.addListener(listener: function)

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

Event

listener
function
The listener parameter should be a function that looks like this:
(info: ReceiveInfo) => {...}
- info
  ReceiveInfo
  The event data.

onReceiveError

chrome.sockets.tcp.onReceiveError.addListener(listener: function)

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.

Event

listener
function
The listener parameter should be a function that looks like this:
(info: ReceiveErrorInfo) => {...}
- info
  ReceiveErrorInfo
  The event data.