chrome.bluetoothSocket
- Description
Use the
chrome.bluetoothSocket
API to send and receive data to Bluetooth devices using RFCOMM and L2CAP connections.
Summary
- Types
- Methods
chrome.bluetoothSocket.close(socketId: number, callback: function)
chrome.bluetoothSocket.connect(socketId: number, address: string, uuid: string, callback: function)
chrome.bluetoothSocket.create(properties?: SocketProperties, callback: function)
chrome.bluetoothSocket.disconnect(socketId: number, callback: function)
chrome.bluetoothSocket.getInfo(socketId: number, callback: function)
chrome.bluetoothSocket.getSockets(callback: function)
chrome.bluetoothSocket.listenUsingL2cap(socketId: number, uuid: string, options?: ListenOptions, callback: function)
chrome.bluetoothSocket.listenUsingRfcomm(socketId: number, uuid: string, options?: ListenOptions, callback: function)
chrome.bluetoothSocket.send(socketId: number, data: ArrayBuffer, callback: function)
chrome.bluetoothSocket.setPaused(socketId: number, paused: boolean, callback: function)
chrome.bluetoothSocket.update(socketId: number, properties: SocketProperties, callback: function)
- Events
Types
AcceptErrorInfo
Properties
- error
An error code indicating what went wrong.
- errorMessagestring
The error message.
- 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.bluetoothSocket
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 socket. Note that socket IDs created from this API are not compatible with socket IDs created from other APIs, such as the
API.sockets.tcp
ListenOptions
Properties
- backlognumber optional
Length of the socket's listen queue. The default value depends on the operating system's host subsystem.
- channelnumber 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. - psmnumber 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.
ReceiveErrorInfo
Properties
- error
An error code indicating what went wrong.
- errorMessagestring
The error message.
- socketIdnumber
The socket identifier.
ReceiveInfo
Properties
- dataArrayBuffer
The data received, with a maxium size of
bufferSize
. - socketIdnumber
The socket identifier.
SocketInfo
Properties
- addressstring optional
If the underlying socket is connected, contains the Bluetooth address of the device it is connected to.
- 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.
- namestring optional
Application-defined string associated with the socket.
- pausedboolean
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. 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.
- uuidstring 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
- 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 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 $ref:getSockets.
AcceptError
Enum
"system_error"
, or "not_listening"
ReceiveError
Enum
"disconnected"
, "system_error"
, or "not_connected"
Methods
close
chrome.bluetoothSocket.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:
() => {...}
connect
chrome.bluetoothSocket.connect(socketId: number, address: string, uuid: string, callback: function)
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
- socketIdnumber
The socket identifier.
- addressstring
The address of the Bluetooth device.
- uuidstring
The UUID of the service to connect to.
- callbackfunction
Called when the connect attempt is complete.
The callback parameter should be a function that looks like this:
() => {...}
create
chrome.bluetoothSocket.create(properties?: SocketProperties, callback: function)
Creates a Bluetooth 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.bluetoothSocket.disconnect(socketId: number, callback: function)
Disconnects the socket. The socket identifier remains valid.
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.bluetoothSocket.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.bluetoothSocket.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:
(sockets: SocketInfo[]) => {...}
- sockets
listenUsingL2cap
chrome.bluetoothSocket.listenUsingL2cap(socketId: number, uuid: string, options?: ListenOptions, callback: function)
Listen for connections using the L2CAP protocol.
Parameters
- socketIdnumber
The socket identifier.
- uuidstring
Service UUID to listen on.
- optionsListenOptions optional
Optional additional options for the service.
- callbackfunction
Called when listen operation completes.
The callback parameter should be a function that looks like this:
() => {...}
listenUsingRfcomm
chrome.bluetoothSocket.listenUsingRfcomm(socketId: number, uuid: string, options?: ListenOptions, callback: function)
Listen for connections using the RFCOMM protocol.
Parameters
- socketIdnumber
The socket identifier.
- uuidstring
Service UUID to listen on.
- optionsListenOptions optional
Optional additional options for the service.
- callbackfunction
Called when listen operation completes.
The callback parameter should be a function that looks like this:
() => {...}
send
chrome.bluetoothSocket.send(socketId: number, data: ArrayBuffer, callback: function)
Sends data on the given Bluetooth socket.
Parameters
- socketIdnumber
The socket identifier.
- dataArrayBuffer
The data to send.
- callbackfunction
Called with the number of bytes sent.
The callback parameter should be a function that looks like this:
(bytesSent: number) => {...}
- bytesSentnumber
The number of bytes sent.
setPaused
chrome.bluetoothSocket.setPaused(socketId: number, paused: boolean, callback: function)
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 onReceive
event 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
- socketIdnumber
- pausedboolean
- callbackfunction
Callback from the
setPaused
method.The callback parameter should be a function that looks like this:
() => {...}
update
chrome.bluetoothSocket.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.bluetoothSocket.onAccept.addListener(listener: function)
Event raised when a connection has been established for a given socket.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(info: AcceptInfo) => {...}
- info
The event data.
onAcceptError
chrome.bluetoothSocket.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
- listenerfunction
The listener parameter should be a function that looks like this:
(info: AcceptErrorInfo) => {...}
- info
The event data.
onReceive
chrome.bluetoothSocket.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.bluetoothSocket.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
- listenerfunction
The listener parameter should be a function that looks like this:
(info: ReceiveErrorInfo) => {...}
- info
The event data.