diff options
Diffstat (limited to 'chromium/extensions/common/api/bluetooth_socket.idl')
| -rw-r--r-- | chromium/extensions/common/api/bluetooth_socket.idl | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/chromium/extensions/common/api/bluetooth_socket.idl b/chromium/extensions/common/api/bluetooth_socket.idl new file mode 100644 index 00000000000..cb95c02adc8 --- /dev/null +++ b/chromium/extensions/common/api/bluetooth_socket.idl @@ -0,0 +1,316 @@ +// 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); + }; +}; |