// Copyright 2014 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Use the <code>chrome.bluetoothSocket</code> API to send and receive data
// to Bluetooth devices using RFCOMM and L2CAP connections.
namespace bluetoothSocket {
// The socket properties specified in the $ref:create or $ref:update
// function. Each property is optional. If a property value is not specified,
// a default value is used when calling $ref:create, or the existing value is
// preserved when calling $ref:update.
dictionary SocketProperties {
// Flag indicating whether the socket is left open when the event page of
// the application is unloaded (see <a
// href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
// Lifecycle</a>). The default value is <code>false.</code> When the
// application is loaded, any sockets previously opened with persistent=true
// can be fetched with $ref:getSockets.
boolean? persistent;
// An application-defined string associated with the socket.
DOMString? name;
// The size of the buffer used to receive data. The default value is 4096.
long? bufferSize;
};
// Result of <code>create</code> call.
dictionary CreateInfo {
// 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 <code>$(ref:sockets.tcp)</code> API.
long socketId;
};
// Callback from the <code>create</code> method.
// |createInfo| : The result of the socket creation.
callback CreateCallback = void (CreateInfo createInfo);
// Callback from the <code>update</code> method.
callback UpdateCallback = void ();
// Callback from the <code>setPaused</code> method.
callback SetPausedCallback = void ();
// Options that may be passed to the <code>listenUsingRfcomm</code> and
// <code>listenUsingL2cap</code> methods. Each property is optional with a
// default being used if not specified.
dictionary ListenOptions {
// The RFCOMM Channel used by <code>listenUsingRfcomm</code>. 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.
long? channel;
// The L2CAP PSM used by <code>listenUsingL2cap</code>. 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.
long? psm;
// Length of the socket's listen queue. The default value depends on the
// operating system's host subsystem.
long? backlog;
};
// Callback from the <code>listenUsingRfcomm</code> and
// <code>listenUsingL2cap</code> methods.
callback ListenCallback = void ();
// Callback from the <code>connect</code> method.
callback ConnectCallback = void ();
// Callback from the <code>disconnect</code> method.
callback DisconnectCallback = void ();
// Callback from the <code>close</code> method.
callback CloseCallback = void ();
// Callback from the <code>send</code> method.
// |bytesSent| : The number of bytes sent.
callback SendCallback = void (long bytesSent);
// Result of the <code>getInfo</code> method.
dictionary SocketInfo {
// The socket identifier.
long socketId;
// Flag indicating if the socket remains open when the event page of the
// application is unloaded (see <code>SocketProperties.persistent</code>).
// The default value is "false".
boolean persistent;
// Application-defined string associated with the socket.
DOMString? name;
// The size of the buffer used to receive data. If no buffer size has been
// specified explictly, the value is not provided.
long? bufferSize;
// 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 <code>onAccept</code> event or queued up in the
// listen queue backlog.
// See <code>setPaused</code>. The default value is "false".
boolean paused;
// Flag indicating whether the socket is connected to a remote peer.
boolean connected;
// If the underlying socket is connected, contains the Bluetooth address of
// the device it is connected to.
DOMString? address;
// 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.
DOMString? uuid;
};
// Callback from the <code>getInfo</code> method.
// |socketInfo| : Object containing the socket information.
callback GetInfoCallback = void (SocketInfo socketInfo);
// Callback from the <code>getSockets</code> method.
// |socketInfos| : Array of object containing socket information.
callback GetSocketsCallback = void (SocketInfo[] sockets);
// Data from an <code>onAccept</code> event.
dictionary AcceptInfo {
// The server socket identifier.
long socketId;
// 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 <code>chrome.bluetoothSocket</code> namespace. Note
// the client socket is initially paused and must be explictly un-paused by
// the application to start receiving data.
long clientSocketId;
};
enum AcceptError {
// A system error occurred and the connection may be unrecoverable.
system_error,
// The socket is not listening.
not_listening
};
// Data from an <code>onAcceptError</code> event.
dictionary AcceptErrorInfo {
// The server socket identifier.
long socketId;
// The error message.
DOMString errorMessage;
// An error code indicating what went wrong.
AcceptError error;
};
// Data from an <code>onReceive</code> event.
dictionary ReceiveInfo {
// The socket identifier.
long socketId;
// The data received, with a maxium size of <code>bufferSize</code>.
ArrayBuffer data;
};
enum ReceiveError {
// The connection was disconnected.
disconnected,
// A system error occurred and the connection may be unrecoverable.
system_error,
// The socket has not been connected.
not_connected
};
// Data from an <code>onReceiveError</code> event.
dictionary ReceiveErrorInfo {
// The socket identifier.
long socketId;
// The error message.
DOMString errorMessage;
// An error code indicating what went wrong.
ReceiveError error;
};
// These functions all report failures via chrome.runtime.lastError.
interface Functions {
// Creates a Bluetooth socket.
// |properties| : The socket properties (optional).
// |callback| : Called when the socket has been created.
static void create(
optional SocketProperties properties,
CreateCallback callback);
// Updates the socket properties.
// |socketId| : The socket identifier.
// |properties| : The properties to update.
// |callback| : Called when the properties are updated.
static void update(
long socketId,
SocketProperties properties,
optional UpdateCallback 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 <code>onReceive</code>event is raised. When a socket is
// connected and un-paused, <code>onReceive</code> 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. <code>onAccept</code> events are raised
// only when the socket is un-paused.
static void setPaused(
long socketId,
boolean paused,
optional SetPausedCallback callback);
// Listen for connections using the RFCOMM protocol.
// |socketId| : The socket identifier.
// |uuid| : Service UUID to listen on.
// |options| : Optional additional options for the service.
// |callback| : Called when listen operation completes.
static void listenUsingRfcomm(
long socketId,
DOMString uuid,
optional ListenOptions options,
ListenCallback callback);
// Listen for connections using the L2CAP protocol.
// |socketId| : The socket identifier.
// |uuid| : Service UUID to listen on.
// |options| : Optional additional options for the service.
// |callback| : Called when listen operation completes.
static void listenUsingL2cap(
long socketId,
DOMString uuid,
optional ListenOptions options,
ListenCallback callback);
// Connects the socket to a remote Bluetooth device. When the
// <code>connect</code> operation completes successfully,
// <code>onReceive</code> events are raised when data is received from the
// peer. If a network error occur while the runtime is receiving packets,
// a <code>onReceiveError</code> event is raised, at which point no more
// <code>onReceive</code> event will be raised for this socket until the
// <code>setPaused(false)</code> method is called.
// |socketId| : The socket identifier.
// |address| : The address of the Bluetooth device.
// |uuid| : The UUID of the service to connect to.
// |callback| : Called when the connect attempt is complete.
static void connect(
long socketId,
DOMString address,
DOMString uuid,
ConnectCallback callback);
// Disconnects the socket. The socket identifier remains valid.
// |socketId| : The socket identifier.
// |callback| : Called when the disconnect attempt is complete.
static void disconnect(
long socketId,
optional DisconnectCallback 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.
// |socketId| : The socket identifier.
// |callback| : Called when the <code>close</code> operation completes.
static void close(
long socketId,
optional CloseCallback callback);
// Sends data on the given Bluetooth socket.
// |socketId| : The socket identifier.
// |data| : The data to send.
// |callback| : Called with the number of bytes sent.
static void send(
long socketId,
ArrayBuffer data,
optional SendCallback callback);
// Retrieves the state of the given socket.
// |socketId| : The socket identifier.
// |callback| : Called when the socket state is available.
static void getInfo(
long socketId,
GetInfoCallback callback);
// Retrieves the list of currently opened sockets owned by the application.
// |callback| : Called when the list of sockets is available.
static void getSockets(GetSocketsCallback callback);
};
interface Events {
// Event raised when a connection has been established for a given socket.
// |info| : The event data.
static void onAccept(AcceptInfo info);
// 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 <code>paused</code> and no more <code>onAccept</code>
// events are raised for this socket.
// |info| : The event data.
static void onAcceptError(AcceptErrorInfo info);
// Event raised when data has been received for a given socket.
// |info| : The event data.
static void onReceive(ReceiveInfo info);
// 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
// <code>paused</code> and no more <code>onReceive</code> events are raised
// for this socket.
// |info| : The event data.
static void onReceiveError(ReceiveErrorInfo info);
};
};
Codebase Browser
chromium