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 thechrome.socket
API.
Summary
- Types
- Methods
chrome.sockets.tcpServer.close(socketId: number, callback: function)
chrome.sockets.tcpServer.create(properties?: SocketProperties, callback: function)
chrome.sockets.tcpServer.disconnect(socketId: number, callback: function)
chrome.sockets.tcpServer.getInfo(socketId: number, callback: function)
chrome.sockets.tcpServer.getSockets(callback: function)
chrome.sockets.tcpServer.listen(socketId: number, address: string, port: number, backlog?: number, callback: function)
chrome.sockets.tcpServer.setPaused(socketId: number, paused: boolean, callback: function)
chrome.sockets.tcpServer.update(socketId: number, properties: SocketProperties, callback: function)
- Events
Types
AcceptErrorInfo
Properties
- resultCodenumber
The result code returned from the underlying network call.
- socketIdnumber
The server socket identifier.
AcceptInfo
Properties
- clientSocketIdnumber
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. - socketIdnumber
The server socket identifier.
CreateInfo
Properties
- socketIdnumber
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
API.socket
SocketInfo
Properties
- localAddressstring optional
If the socket is listening, contains its local IPv4/6 address.
- localPortnumber optional
If the socket is listening, contains its local port.
- namestring optional
Application-defined string associated with the socket.
- pausedboolean
Flag indicating whether connection requests on a listening socket are dispatched through the
onAccept
event or queued up in the listen queue backlog. SeesetPaused
. The default value is "false". - persistentboolean
Flag indicating if the socket remains open when the event page of the application is unloaded (see
SocketProperties.persistent
). The default value is "false". - socketIdnumber
The socket identifier.
SocketProperties
Properties
- namestring optional
An application-defined string associated with the socket.
- persistentboolean 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
chrome.sockets.tcpServer.close(socketId: number, callback: function)
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
- socketIdnumber
The socket identifier.
- callbackfunction
Called when the
close
operation completes.The callback parameter should be a function that looks like this:
() => {...}
create
chrome.sockets.tcpServer.create(properties?: SocketProperties, callback: function)
Creates a TCP server socket.
Parameters
- propertiesSocketProperties optional
The socket properties (optional).
- callbackfunction
Called when the socket has been created.
The callback parameter should be a function that looks like this:
(createInfo: CreateInfo) => {...}
- createInfo
The result of the socket creation.
disconnect
chrome.sockets.tcpServer.disconnect(socketId: number, callback: function)
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
- socketIdnumber
The socket identifier.
- callbackfunction
Called when the disconnect attempt is complete.
The callback parameter should be a function that looks like this:
() => {...}
getInfo
chrome.sockets.tcpServer.getInfo(socketId: number, callback: function)
Retrieves the state of the given socket.
Parameters
- socketIdnumber
The socket identifier.
- callbackfunction
Called when the socket state is available.
The callback parameter should be a function that looks like this:
(socketInfo: SocketInfo) => {...}
- socketInfo
Object containing the socket information.
getSockets
chrome.sockets.tcpServer.getSockets(callback: function)
Retrieves the list of currently opened sockets owned by the application.
Parameters
- callbackfunction
Called when the list of sockets is available.
The callback parameter should be a function that looks like this:
(socketInfos: SocketInfo[]) => {...}
- socketInfos
Array of object containing socket information.
listen
chrome.sockets.tcpServer.listen(socketId: number, address: string, port: number, backlog?: number, callback: function)
Listens for connections on the specified port and address. If the port/address is in use, the callback indicates a failure.
Parameters
- socketIdnumber
The socket identifier.
- addressstring
The address of the local machine.
- portnumber
The port of the local machine. When set to
0
, a free port is chosen dynamically. The dynamically allocated port can be found by callinggetInfo
. - backlognumber 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.
- callbackfunction
Called when listen operation completes.
The callback parameter should be a function that looks like this:
(result: number) => {...}
- resultnumber
The result code returned from the underlying network call. A negative value indicates an error.
setPaused
chrome.sockets.tcpServer.setPaused(socketId: number, paused: boolean, callback: function)
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
- socketIdnumber
- pausedboolean
- callbackfunction
Callback from the
setPaused
method.The callback parameter should be a function that looks like this:
() => {...}
update
chrome.sockets.tcpServer.update(socketId: number, properties: SocketProperties, callback: function)
Updates the socket properties.
Parameters
- socketIdnumber
The socket identifier.
- properties
The properties to update.
- callbackfunction
Called when the properties are updated.
The callback parameter should be a function that looks like this:
() => {...}
Events
onAccept
chrome.sockets.tcpServer.onAccept.addListener(listener: function)
Event raised when a connection has been made to the server socket.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(info: AcceptInfo) => {...}
- info
The event data.
onAcceptError
chrome.sockets.tcpServer.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
- listenerfunction
The listener parameter should be a function that looks like this:
(info: AcceptErrorInfo) => {...}
- info
The event data.