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.

Manifest

The following keys must be declared in the manifest to use this API.

"sockets"

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

Chrome 103+

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

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

    The values tls1 and tls1.1 are no longer supported. If min is set to one of these values, it will be silently clamped to tls1.2. If max is set to one of those values, or any other unrecognized value, it will be silently ignored.

Methods

close()

Promise 
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()

Promise 
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

      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()

Promise 
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()

Promise 
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

      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()

Promise 
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

      SocketInfo[]

      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

      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()

Promise 
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()

Promise 
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 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

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