chrome.sockets.tcpServer

Description

Use the chrome.sockets.tcpServer API to create server applications 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

AcceptErrorInfo

Properties

  • resultCode

    number

    The result code returned from the underlying network call.

  • socketId

    number

    The server socket identifier.

AcceptInfo

Properties

  • clientSocketId

    number

    The client socket identifier, i.e. the socket identifier of the newly established connection. This socket identifier should be used only with functions from the chrome.sockets.tcp namespace. Note the client socket is initially paused and must be explictly un-paused by the application to start receiving data.

  • socketId

    number

    The server socket identifier.

CreateInfo

Properties

  • socketId

    number

    The ID of the newly created server 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.

SocketInfo

Properties

  • localAddress

    string optional

    If the socket is listening, contains its local IPv4/6 address.

  • localPort

    number optional

    If the socket is listening, contains its local port.

  • name

    string optional

    Application-defined string associated with the socket.

  • paused

    boolean

    Flag indicating whether connection requests on a listening socket are dispatched through the onAccept event or queued up in the listen queue backlog. See setPaused. The default value is "false".

  • persistent

    boolean

    Flag indicating if the socket remains open when the event page of the application is unloaded (see SocketProperties.persistent). The default value is "false".

  • socketId

    number

    The socket identifier.

SocketProperties

Properties

  • name

    string optional

    An application-defined string associated with the socket.

  • persistent

    boolean optional

    Flag indicating if the socket remains 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.

Methods

close()

Promise 
chrome.sockets.tcpServer.close(
  socketId: number,
  callback?: function,
): Promise<void>

Disconnects and destroys the socket. Each socket created should be closed after use. The socket id is 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.

create()

Promise 
chrome.sockets.tcpServer.create(
  properties?: SocketProperties,
  callback?: function,
): Promise<CreateInfo>

Creates a TCP server 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.tcpServer.disconnect(
  socketId: number,
  callback?: function,
): Promise<void>

Disconnects the listening socket, i.e. stops accepting new connections and releases the address/port the socket is bound to. The socket identifier remains valid, e.g. it can be used with listen to accept connections on a new port and address.

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.tcpServer.getInfo(
  socketId: number,
  callback?: function,
): Promise<SocketInfo>

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.tcpServer.getSockets(
  callback?: function,
): Promise<SocketInfo[]>

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.

listen()

chrome.sockets.tcpServer.listen(
  socketId: number,
  address: string,
  port: number,
  backlog?: number,
  callback: function,
): void

Listens for connections on the specified port and address. If the port/address is in use, the callback indicates a failure.

Parameters

  • socketId

    number

    The socket identifier.

  • address

    string

    The address of the local machine.

  • port

    number

    The port of the local machine. When set to 0, a free port is chosen dynamically. The dynamically allocated port can be found by calling getInfo.

  • backlog

    number optional

    Length of the socket's listen queue. The default value depends on the Operating System (SOMAXCONN), which ensures a reasonable queue length for most applications.

  • 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.tcpServer.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
): Promise<void>

Enables or disables a listening socket from accepting new connections. When paused, a listening socket accepts new connections until its backlog (see listen function) is full then refuses additional connection requests. onAccept events are raised only when the socket is un-paused.

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.tcpServer.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
): Promise<void>

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

onAccept

chrome.sockets.tcpServer.onAccept.addListener(
  callback: function,
)

Event raised when a connection has been made to the server socket.

Parameters

  • callback

    function

    The callback parameter looks like: 

    (info: AcceptInfo) => void

onAcceptError

chrome.sockets.tcpServer.onAcceptError.addListener(
  callback: function,
)

Event raised when a network error occured while the runtime was waiting for new connections on the socket address and port. Once this event is raised, the socket is set to paused and no more onAccept events are raised for this socket until the socket is resumed.

Parameters