| // Copyright 2014 The Chromium Authors. All rights reserved. |
| // 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); |
| }; |
| }; |