common/api/bluetooth_socket.idl

// 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);
  };
};