chrome.bluetoothSocket

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

Important: This API works only on Chrome OS

Description
Use the chrome.bluetoothSocket API to send and receive data to Bluetooth devices using RFCOMM and L2CAP connections.

Summary

Types
AcceptError
AcceptErrorInfo
AcceptInfo
CreateInfo
ListenOptions
ReceiveError
ReceiveErrorInfo
ReceiveInfo
SocketInfo
SocketProperties
Methods
close
close(socketId: number): Promise<object>
close(socketId: number, callback?: function): void
connect
connect(socketId: number, address: string, uuid: string): Promise<object>
connect(socketId: number, address: string, uuid: string, callback: function): void
create
create(properties?: SocketProperties): Promise<object>
create(properties?: SocketProperties, callback: function): void
disconnect
disconnect(socketId: number): Promise<object>
disconnect(socketId: number, callback?: function): void
getInfo
getInfo(socketId: number): Promise<object>
getInfo(socketId: number, callback: function): void
getSockets
getSockets(): Promise<object>
getSockets(callback: function): void
listenUsingL2cap
listenUsingL2cap(socketId: number, uuid: string, options?: ListenOptions): Promise<object>
listenUsingL2cap(socketId: number, uuid: string, options?: ListenOptions, callback: function): void
listenUsingRfcomm
listenUsingRfcomm(socketId: number, uuid: string, options?: ListenOptions): Promise<object>
listenUsingRfcomm(socketId: number, uuid: string, options?: ListenOptions, callback: function): void
send
send(socketId: number, data: ArrayBuffer): Promise<object>
send(socketId: number, data: ArrayBuffer, callback?: function): void
setPaused
setPaused(socketId: number, paused: boolean): Promise<object>
setPaused(socketId: number, paused: boolean, callback?: function): void
update
update(socketId: number, properties: SocketProperties): Promise<object>
update(socketId: number, properties: SocketProperties, callback?: function): void
Events
onAccept
onAcceptError
onReceive
onReceiveError

Types

AcceptError

Enum

"system_error", or "not_listening"

AcceptErrorInfo

Properties

error
AcceptError
An error code indicating what went wrong.
errorMessage
string
The error message.
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.bluetoothSocket 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 socket. Note that socket IDs created from this API are not compatible with socket IDs created from other APIs, such as the sockets.tcp API.

ListenOptions

Properties

backlog
number optional
Length of the socket's listen queue. The default value depends on the operating system's host subsystem.
channel
number optional
The RFCOMM Channel used by listenUsingRfcomm. If specified, this channel must not be previously in use or the method call will fail. When not specified, an unused channel will be automatically allocated.
psm
number optional
The L2CAP PSM used by listenUsingL2cap. If specified, this PSM must not be previously in use or the method call with fail. When not specified, an unused PSM will be automatically allocated.

ReceiveError

Enum

"disconnected", "system_error", or "not_connected"

ReceiveErrorInfo

Properties

error
ReceiveError
An error code indicating what went wrong.
errorMessage
string
The error message.
socketId
number
The socket identifier.

ReceiveInfo

Properties

data
ArrayBuffer
The data received, with a maxium size of bufferSize.
socketId
number
The socket identifier.

SocketInfo

Properties

address
string optional
If the underlying socket is connected, contains the Bluetooth address of the device it is connected to.
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.
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, or 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.
uuid
string optional
If the underlying socket is connected, contains information about the service UUID it is connected to, otherwise if the underlying socket is listening, contains information about the service UUID it is listening on.

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

Methods

close

close(socketId: number): Promise<object>
close(socketId: number, callback?: function): void

Promise

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.

Result

return/callback
async
Called when the close operation completes.
The close method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

connect

connect(socketId: number, address: string, uuid: string): Promise<object>
connect(socketId: number, address: string, uuid: string, callback: function): void

Promise

Connects the socket to a remote Bluetooth device. When the connect operation completes successfully, onReceive events are raised when data is received from the peer. If a network error occur 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 setPaused(false) method is called.

Parameters

socketId
number
The socket identifier.
address
string
The address of the Bluetooth device.
uuid
string
The UUID of the service to connect to.

Result

return/callback
async
Called when the connect attempt is complete.
The connect method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

create

create(properties?: SocketProperties): Promise<object>
create(properties?: SocketProperties, callback: function): void

Promise

Creates a Bluetooth socket.

Parameters

properties
SocketProperties optional
The socket properties (optional).

Result

return/callback
async
Called when the socket has been created.
The create method provides its result via callback or returned as a Promise (MV3 only).
- createInfo
  CreateInfo
  The result of the socket creation.

disconnect

disconnect(socketId: number): Promise<object>
disconnect(socketId: number, callback?: function): void

Promise

Disconnects the socket. The socket identifier remains valid.

Parameters

socketId
number
The socket identifier.

Result

return/callback
async
Called when the disconnect attempt is complete.
The disconnect method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

getInfo

getInfo(socketId: number): Promise<object>
getInfo(socketId: number, callback: function): void

Promise

Retrieves the state of the given socket.

Parameters

socketId
number
The socket identifier.

Result

return/callback
async
Called when the socket state is available.
The getInfo method provides its result via callback or returned as a Promise (MV3 only).
- socketInfo
  SocketInfo
  Object containing the socket information.

getSockets

getSockets(): Promise<object>
getSockets(callback: function): void

Promise

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

Result

return/callback
async
Called when the list of sockets is available.
The getSockets method provides its result via callback or returned as a Promise (MV3 only).
- sockets
  SocketInfo[]

listenUsingL2cap

listenUsingL2cap(socketId: number, uuid: string, options?: ListenOptions): Promise<object>
listenUsingL2cap(socketId: number, uuid: string, options?: ListenOptions, callback: function): void

Promise

Listen for connections using the L2CAP protocol.

Parameters

socketId
number
The socket identifier.
uuid
string
Service UUID to listen on.
options
ListenOptions optional
Optional additional options for the service.

Result

return/callback
async
Called when listen operation completes.
The listenUsingL2cap method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

listenUsingRfcomm

listenUsingRfcomm(socketId: number, uuid: string, options?: ListenOptions): Promise<object>
listenUsingRfcomm(socketId: number, uuid: string, options?: ListenOptions, callback: function): void

Promise

Listen for connections using the RFCOMM protocol.

Parameters

socketId
number
The socket identifier.
uuid
string
Service UUID to listen on.
options
ListenOptions optional
Optional additional options for the service.

Result

return/callback
async
Called when listen operation completes.
The listenUsingRfcomm method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

send

send(socketId: number, data: ArrayBuffer): Promise<object>
send(socketId: number, data: ArrayBuffer, callback?: function): void

Promise

Sends data on the given Bluetooth socket.

Parameters

socketId
number
The socket identifier.
data
ArrayBuffer
The data to send.

Result

return/callback
async
Called with the number of bytes sent.
The send method provides its result via callback or returned as a Promise (MV3 only).
- bytesSent
  number
  The number of bytes sent.

setPaused

setPaused(socketId: number, paused: boolean): Promise<object>
setPaused(socketId: number, paused: boolean, callback?: function): void

Promise

Enables or disables a connected socket from receiving messages from its peer, or a listening socket from accepting new connections. The default value is "false". Pausing a connected socket is typically used by an application to throttle data sent by its peer. When a connected socket is paused, no onReceiveevent is raised. When a socket is connected and un-paused, onReceive events are raised again when messages are received. When a listening socket is paused, new connections are accepted until its backlog is full then additional connection requests are refused. onAccept events are raised only when the socket is un-paused.

Parameters

socketId
number
paused
boolean

Result

return/callback
async
Callback from the setPaused method.
The setPaused method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

update

update(socketId: number, properties: SocketProperties): Promise<object>
update(socketId: number, properties: SocketProperties, callback?: function): void

Promise

Updates the socket properties.

Parameters

socketId
number
The socket identifier.
properties
SocketProperties
The properties to update.

Result

return/callback
async
Called when the properties are updated.
The update method provides its result via callback or returned as a Promise (MV3 only). It has no parameters.

Events

onAccept

onAccept.addListener(listener: function)

Event raised when a connection has been established for a given 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 occurred while the runtime was waiting for new connections on the given socket. Once this event is raised, the socket is set to paused and no more onAccept events are raised for this socket.

Event

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

onReceive

onReceive.addListener(listener: function)

Event raised when data has been received for a given socket.

Event

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

onReceiveError

onReceiveError.addListener(listener: function)

Event raised when a network error occured while the runtime was waiting for data on the socket. Once this event is raised, the socket is set to paused and no more onReceive events are raised for this socket.

Event

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