chrome.bluetoothSocket

Description:	Use the `chrome.bluetoothSocket` API to send and receive data to Bluetooth devices using RFCOMM and L2CAP connections.
Availability:	Since Chrome 37.
Manifest:	"bluetooth": {...}
Learn More:	Bluetooth

Important: This API works only on OS X, Windows and Chrome OS.

Summary

Types
SocketProperties
ListenOptions
SocketInfo
Methods
create − `chrome.bluetoothSocket.create( SocketProperties properties, function callback)`
update − `chrome.bluetoothSocket.update(integer socketId, SocketProperties properties, function callback)`
setPaused − `chrome.bluetoothSocket.setPaused(integer socketId, boolean paused, function callback)`
listenUsingRfcomm − `chrome.bluetoothSocket.listenUsingRfcomm(integer socketId, string uuid, ListenOptions options, function callback)`
listenUsingL2cap − `chrome.bluetoothSocket.listenUsingL2cap(integer socketId, string uuid, ListenOptions options, function callback)`
connect − `chrome.bluetoothSocket.connect(integer socketId, string address, string uuid, function callback)`
disconnect − `chrome.bluetoothSocket.disconnect(integer socketId, function callback)`
close − `chrome.bluetoothSocket.close(integer socketId, function callback)`
send − `chrome.bluetoothSocket.send(integer socketId, ArrayBuffer data, function callback)`
getInfo − `chrome.bluetoothSocket.getInfo(integer socketId, function callback)`
getSockets − `chrome.bluetoothSocket.getSockets(function callback)`
Events
onAccept
onAcceptError
onReceive
onReceiveError

Types

SocketProperties

properties
boolean	(optional) persistent	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.
string	(optional) name	An application-defined string associated with the socket.
integer	(optional) bufferSize	The size of the buffer used to receive data. The default value is 4096.

ListenOptions

properties
integer	(optional) channel	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.
integer	(optional) psm	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.
integer	(optional) backlog	Length of the socket's listen queue. The default value depends on the operating system's host subsystem.

SocketInfo

properties
integer	socketId	The socket identifier.
boolean	persistent	Flag indicating if the socket remains open when the event page of the application is unloaded (see `SocketProperties.persistent`). The default value is "false".
string	(optional) name	Application-defined string associated with the socket.
integer	(optional) bufferSize	The size of the buffer used to receive data. If no buffer size has been specified explictly, the value is not provided.
boolean	paused	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".
boolean	connected	Flag indicating whether the socket is connected to a remote peer.
string	(optional) address	If the underlying socket is connected, contains the Bluetooth address of the device it is connected to.
string	(optional) uuid	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.

Methods

create


              chrome.bluetoothSocket.create(    SocketProperties properties, function callback)

Creates a Bluetooth socket.

Parameters

SocketProperties

(optional) properties

The socket properties (optional).

function

callback

Called when the socket has been created.

The callback parameter should be a function that looks like this:

function(object createInfo) {...};

object

createInfo

The result of the socket creation.

integer

socketId

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.

update


              chrome.bluetoothSocket.update(integer socketId,     SocketProperties properties, function callback)

Updates the socket properties.

Parameters

integer

socketId

The socket identifier.

SocketProperties

properties

The properties to update.

function

(optional) callback

Called when the properties are updated.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

setPaused


              chrome.bluetoothSocket.setPaused(integer socketId, boolean paused, function callback)

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

integer socketId

boolean paused

function

Parameters
integer	socketId
boolean	paused
function	(optional) callback	Callback from the `setPaused` method. If you specify the callback parameter, it should be a function that looks like this: `function() {...};`

(optional) callback

Callback from the setPaused method.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

listenUsingRfcomm


              chrome.bluetoothSocket.listenUsingRfcomm(integer socketId, string uuid,     ListenOptions options, function callback)

Listen for connections using the RFCOMM protocol.

Parameters
integer	socketId	The socket identifier.
string	uuid	Service UUID to listen on.
ListenOptions	(optional) options	Optional additional options for the service.
function	callback	Called when listen operation completes. The callback parameter should be a function that looks like this: `function() {...};`

listenUsingL2cap


              chrome.bluetoothSocket.listenUsingL2cap(integer socketId, string uuid,     ListenOptions options, function callback)

Listen for connections using the L2CAP protocol.

Parameters
integer	socketId	The socket identifier.
string	uuid	Service UUID to listen on.
ListenOptions	(optional) options	Optional additional options for the service.
function	callback	Called when listen operation completes. The callback parameter should be a function that looks like this: `function() {...};`

connect


              chrome.bluetoothSocket.connect(integer socketId, string address, string uuid, function callback)

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
integer	socketId	The socket identifier.
string	address	The address of the Bluetooth device.
string	uuid	The UUID of the service to connect to.
function	callback	Called when the connect attempt is complete. The callback parameter should be a function that looks like this: `function() {...};`

disconnect


              chrome.bluetoothSocket.disconnect(integer socketId, function callback)

Disconnects the socket. The socket identifier remains valid.

Parameters

integer

socketId

The socket identifier.

function

(optional) callback

Called when the disconnect attempt is complete.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

close


              chrome.bluetoothSocket.close(integer socketId, function callback)

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

integer

socketId

The socket identifier.

function

(optional) callback

Called when the close operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

send


              chrome.bluetoothSocket.send(integer socketId, ArrayBuffer data, function callback)

Sends data on the given Bluetooth socket.

Parameters

integer

socketId

The socket identifier.

ArrayBuffer

data

The data to send.

function

(optional) callback

Called with the number of bytes sent.

If you specify the callback parameter, it should be a function that looks like this:

function(integer bytesSent) {...};

integer

bytesSent

The number of bytes sent.

getInfo


              chrome.bluetoothSocket.getInfo(integer socketId, function callback)

Retrieves the state of the given socket.

Parameters

integer

socketId

The socket identifier.

function

callback

Called when the socket state is available.

The callback parameter should be a function that looks like this:

function( SocketInfo socketInfo) {...};

SocketInfo

socketInfo

Object containing the socket information.

getSockets


              chrome.bluetoothSocket.getSockets(function callback)

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

Parameters

function

callback

Called when the list of sockets is available.

The callback parameter should be a function that looks like this:

function(array of SocketInfo sockets) {...};

array of SocketInfo

sockets

Events

onAccept

Event raised when a connection has been established for a given socket.

addListener


                    chrome.bluetoothSocket.onAccept.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(object info) {...};

object

info

The event data.

integer	socketId	The server socket identifier.
integer	clientSocketId	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.

onAcceptError

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.

addListener


                    chrome.bluetoothSocket.onAcceptError.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(object info) {...};

object

info

The event data.

integer

socketId

The server socket identifier.

string

errorMessage

The error message.

enum of "system_error", or "not_listening"

error

An error code indicating what went wrong.

system_error: A system error occurred and the connection may be unrecoverable.

not_listening: The socket is not listening.

onReceive

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

addListener


                    chrome.bluetoothSocket.onReceive.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(object info) {...};

object

info

The event data.

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

onReceiveError

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.

addListener


                    chrome.bluetoothSocket.onReceiveError.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(object info) {...};

object

info

The event data.

integer

socketId

The socket identifier.

string

errorMessage

The error message.

enum of "disconnected", "system_error", or "not_connected"

error

An error code indicating what went wrong.

disconnected: The connection was disconnected.

system_error: A system error occurred and the connection may be unrecoverable.

not_connected: The socket has not been connected.