chrome.sockets.tcpServer

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

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.

Summary

Types
AcceptErrorInfo
AcceptInfo
CreateInfo
SocketInfo
SocketProperties
Methods
close
close(socketId: number, callback?: function): void
create
create(properties?: SocketProperties, callback: function): void
disconnect
disconnect(socketId: number, callback?: function): void
getInfo
getInfo(socketId: number, callback: function): void
getSockets
getSockets(callback: function): void
listen
listen(socketId: number, address: string, port: number, backlog?: number, callback: function): void
setPaused
setPaused(socketId: number, paused: boolean, callback?: function): void
update
update(socketId: number, properties: SocketProperties, callback?: function): void
Events
onAccept
onAcceptError

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

close(socketId: number, callback?: function): 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
Called when the close operation completes.
If you specify the parameter, it should be a function that looks like this:
() => {...}

create

create(properties?: SocketProperties, callback: function): void

Creates a TCP server socket.

Parameters

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

disconnect

disconnect(socketId: number, callback?: function): 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
Called when the disconnect attempt is complete.
If you specify the parameter, it should be a function that looks like this:
() => {...}

getInfo

getInfo(socketId: number, callback: function): void

Retrieves the state of the given socket.

Parameters

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

getSockets

getSockets(callback: function): void

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

Parameters

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

listen

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
Called when listen operation completes.
The 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

setPaused(socketId: number, paused: boolean, callback?: function): 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
Callback from the setPaused method.
If you specify the parameter, it should be a function that looks like this:
() => {...}

update

update(socketId: number, properties: SocketProperties, callback?: function): void

Updates the socket properties.

Parameters

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

Events

onAccept

onAccept.addListener(listener: function)

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

Event

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

onAcceptError

onAcceptError.addListener(listener: 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.

Event

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