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.
Manifest
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](../socket/)
API.
DnsQueryType
DNS resolution preferences. The default is any
and uses the current OS config which may return IPv4 or IPv6. ipv4
forces IPv4, and ipv6
forces IPv6.
Enum
"any" "ipv4" "ipv6"
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. Supported values are
tls1.2
ortls1.3
.The values
tls1
andtls1.1
are no longer supported. Ifmin
is set to one of these values, it will be silently clamped totls1.2
. Ifmax
is set to one of those values, or any other unrecognized value, it will be silently ignored.
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 optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 121+Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.
connect()
chrome.sockets.tcp.connect(
socketId: number,
peerAddress: string,
peerPort: number,
dnsQueryType?: DnsQueryType,
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.
-
dnsQueryType
DnsQueryType optional
Chrome 103+The address resolution preference.
-
callback
function
The
callback
parameter looks like:(result: number) => void
-
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 optional
The
callback
parameter looks like:(createInfo: CreateInfo) => void
-
createInfo
The result of the socket creation.
-
Returns
-
Promise<CreateInfo>
Chrome 121+Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.
disconnect()
chrome.sockets.tcp.disconnect(
socketId: number,
callback?: function,
)
Disconnects the socket.
Parameters
-
socketId
number
The socket identifier.
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 121+Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.
getInfo()
chrome.sockets.tcp.getInfo(
socketId: number,
callback?: function,
)
Retrieves the state of the given socket.
Parameters
-
socketId
number
The socket identifier.
-
callback
function optional
The
callback
parameter looks like:(socketInfo: SocketInfo) => void
-
socketInfo
Object containing the socket information.
-
Returns
-
Promise<SocketInfo>
Chrome 121+Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.
getSockets()
chrome.sockets.tcp.getSockets(
callback?: function,
)
Retrieves the list of currently opened sockets owned by the application.
Parameters
-
callback
function optional
The
callback
parameter looks like:(socketInfos: SocketInfo[]) => void
-
socketInfos
Array of object containing socket information.
-
Returns
-
Promise<SocketInfo[]>
Chrome 121+Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.
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
The
callback
parameter looks like:(result: number) => void
-
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
The
callback
parameter looks like:(sendInfo: SendInfo) => void
-
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
The
callback
parameter looks like:(result: number) => void
-
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
The
callback
parameter looks like:(result: number) => void
-
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 optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 121+Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.
update()
chrome.sockets.tcp.update(
socketId: number,
properties: SocketProperties,
callback?: function,
)
Updates the socket properties.
Parameters
-
socketId
number
The socket identifier.
-
properties
The properties to update.
-
callback
function optional
The
callback
parameter looks like:() => void
Returns
-
Promise<void>
Chrome 121+Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.
Events
onReceive
chrome.sockets.tcp.onReceive.addListener(
callback: function,
)
Event raised when data has been received for a given socket.
Parameters
-
callback
function
The
callback
parameter looks like:(info: ReceiveInfo) => void
-
info
-
onReceiveError
chrome.sockets.tcp.onReceiveError.addListener(
callback: 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.
Parameters
-
callback
function
The
callback
parameter looks like:(info: ReceiveErrorInfo) => void
-
info
-