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 thechrome.socket
API.
Summary
- Types
- Methods
chrome.sockets.tcp.close(socketId: number, callback: function)
chrome.sockets.tcp.connect(socketId: number, peerAddress: string, peerPort: number, callback: function)
chrome.sockets.tcp.create(properties?: SocketProperties, callback: function)
chrome.sockets.tcp.disconnect(socketId: number, callback: function)
chrome.sockets.tcp.getInfo(socketId: number, callback: function)
chrome.sockets.tcp.getSockets(callback: function)
chrome.sockets.tcp.secure(socketId: number, options?: SecureOptions, callback: function)
chrome.sockets.tcp.send(socketId: number, data: ArrayBuffer, callback: function)
chrome.sockets.tcp.setKeepAlive(socketId: number, enable: boolean, delay?: number, callback: function)
chrome.sockets.tcp.setNoDelay(socketId: number, noDelay: boolean, callback: function)
chrome.sockets.tcp.setPaused(socketId: number, paused: boolean, callback: function)
chrome.sockets.tcp.update(socketId: number, properties: SocketProperties, callback: function)
- Events
Types
CreateInfo
Properties
- socketIdnumber
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
API.socket
ReceiveErrorInfo
Properties
- resultCodenumber
The result code returned from the underlying network call.
- socketIdnumber
The socket identifier.
ReceiveInfo
Properties
- dataArrayBuffer
The data received, with a maxium size of
bufferSize
. - socketIdnumber
The socket identifier.
SecureOptions
Properties
- tlsVersionTLSVersionConstraints optional
SendInfo
Properties
- bytesSentnumber optional
The number of bytes sent (if result == 0)
- resultCodenumber
The result code returned from the underlying network call. A negative value indicates an error.
SocketInfo
Properties
- bufferSizenumber optional
The size of the buffer used to receive data. If no buffer size has been specified explictly, the value is not provided.
- connectedboolean
Flag indicating whether the socket is connected to a remote peer.
- localAddressstring optional
If the underlying socket is connected, contains its local IPv4/6 address.
- localPortnumber optional
If the underlying socket is connected, contains its local port.
- namestring optional
Application-defined string associated with the socket.
- pausedboolean
Flag indicating whether a connected socket blocks its peer from sending more data (see
setPaused
). - peerAddressstring optional
If the underlying socket is connected, contains the peer/ IPv4/6 address.
- peerPortnumber optional
If the underlying socket is connected, contains the peer port.
- persistentboolean
Flag indicating whether the socket is left open when the application is suspended (see
SocketProperties.persistent
). - socketIdnumber
The socket identifier.
SocketProperties
Properties
- bufferSizenumber optional
The size of the buffer used to receive data. The default value is 4096.
- namestring optional
An application-defined string associated with the socket.
- persistentboolean 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
- maxstring optional
- minstring optional
The minimum and maximum acceptable versions of TLS. These will be
tls1
,tls1.1
,tls1.2
, ortls1.3
.
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
- socketIdnumber
The socket identifier.
- callbackfunction
Called when the
close
operation completes.The callback parameter should be a function that looks like this:
() => {...}
connect
chrome.sockets.tcp.connect(socketId: number, peerAddress: string, peerPort: number, 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
- socketIdnumber
The socket identifier.
- peerAddressstring
The address of the remote machine. DNS name, IPv4 and IPv6 formats are supported.
- peerPortnumber
The port of the remote machine.
- callbackfunction
Called when the connect attempt is complete.
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.
create
chrome.sockets.tcp.create(properties?: SocketProperties, callback: function)
Creates a TCP 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.tcp.disconnect(socketId: number, callback: function)
Disconnects the socket.
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.tcp.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.tcp.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.
secure
chrome.sockets.tcp.secure(socketId: number, options?: SecureOptions, callback: function)
Start a TLS client connection over the connected TCP client socket.
Parameters
- socketIdnumber
The existing, connected socket to use.
- optionsSecureOptions optional
Constraints and parameters for the TLS connection.
- callbackfunction
Called when the connection attempt is complete.
The callback parameter should be a function that looks like this:
(result: number) => {...}
- resultnumber
send
chrome.sockets.tcp.send(socketId: number, data: ArrayBuffer, callback: function)
Sends data on the given TCP socket.
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
- socketIdnumber
The socket identifier.
- enableboolean
If true, enable keep-alive functionality.
- delaynumber optional
Set the delay seconds between the last data packet received and the first keepalive probe. Default is 0.
- callbackfunction
Called when the setKeepAlive attempt is complete.
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.
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
- socketIdnumber
The socket identifier.
- noDelayboolean
If true, disables Nagle's algorithm.
- callbackfunction
Called when the setNoDelay attempt is complete.
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.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
- socketIdnumber
- pausedboolean
- callbackfunction
Callback from the
setPaused
method.The callback parameter should be a function that looks like this:
() => {...}
update
chrome.sockets.tcp.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
onReceive
chrome.sockets.tcp.onReceive.addListener(listener: function)
Event raised when data has been received for a given socket.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(info: ReceiveInfo) => {...}
- info
The event data.
onReceiveError
chrome.sockets.tcp.onReceiveError.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(info: ReceiveErrorInfo) => {...}
- info
The event data.