services/device/public/mojom/bluetooth_system.mojom

// Copyright 2018 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.

module device.mojom;

// Factory to get an instance of the BluetoothSystem interface.
interface BluetoothSystemFactory {
  Create(BluetoothSystem& system, BluetoothSystemClient system_client);
};

// High level interface targeted towards UI level components that:
//  - Show the BT Radio state and allow users to change it.
//  - Show a list of nearby, connected and paired BT Devices.
//  - Start and stop BT scans.
//  - Connect to and pair with BT devices.
//
// This interface is implemented only on Chrome OS and lives in the Device
// Service.
interface BluetoothSystem {

  // State of Bluetooth.
  enum State {
    // The platform does not support Bluetooth.
    kUnsupported,
    // The platform supports Bluetooth but we can’t use it right now e.g. a BT
    // radio is not present.
    kUnavailable,
    // Bluetooth Radio is off.
    kPoweredOff,
    // State is transitioning between PoweredOff and PoweredOn or vice versa.
    kTransitioning,
    // Bluetooth Radio is on.
    kPoweredOn,
  };

  GetState() => (State state);

  enum SetPoweredResult {
    // Command successfully sent to BT Radio or ignored if the new state matches
    // the current state. OnStateChanged call is imminent if the former.
    kSuccess,
    // Unknown failure when sending the command to the BT Radio.
    kFailedUnknownReason,
    // Can't use Bluetooth right now e.g. a BT radio is not present.
    kBluetoothUnavailable,
  };

  // Attempts to change the state of the Bluetooth to `kPoweredOn` if |powered|
  // and `kPoweredOff` otherwise . Callback is run with `kSuccess if the command
  // was successfully sent to the BT Radio. The state immediately changes to
  // kTransitioning and once the BT Radio actually changes state
  // BluetoothSystemClient::OnStateChanged will be called.
  // TODO(https://crbug.com/896113): This function is missing two features:
  //  1. The new state should be saved in the user's pref so that the next time
  //     the machine turns off the state matches the user pref.
  //  2. Support concurrent calls; currently BlueZ just drops other calls if
  //     there is one in progress already.
  SetPowered(bool powered) => (SetPoweredResult result);

  // Whether the BT Radio is scanning for devices.
  enum ScanState {
    // The BT Radio is not scanning for devices, Bluetooth is unavailable, or
    // the BT Radio is off.
    kNotScanning,
    // State is transitioning between Scanning and Not Scanning and vice versa.
    kTransitioning,
    // Scanning for devices.
    kScanning,
  };

  GetScanState() => (ScanState scan_state);

  enum StartScanResult {
    // Command successfully sent to BT Radio or ignored if already scanning.
    // OnScanStateChanged call is imminent if the former.
    kSuccess,
    // Unknown failure when sending the command to the BT Radio.
    kFailedUnknownReason,
    // Can't use Bluetooth right now e.g. BT radio is off, not present, or
    // transitioning between states.
    kBluetoothUnavailable,
    // TODO(https://crbug.com/897996): Add more specific error codes.
  };

  // Attempts to start scanning for Bluetooth devices. Callback is run with
  // `kSuccess` if the command was successfully sent to the BT Radio. Once the
  // BT Radio actually starts scanning for devices,
  // BluetoothSystemClient::OnScanStateChanged will be called.
  // TODO(https://crbug.com/897996): This function is missing two features:
  //  1. Support concurrent calls; currently BlueZ just drops other calls if
  //     there is one in progress already.
  //  2. Return more detailed error codes.
  StartScan() => (StartScanResult result);

  enum StopScanResult {
    // Command successfully sent to BT Radio.
    kSuccess,
    // Unknown failure when sending the command to the BT Radio.
    kFailedUnknownReason,
    // Can't use Bluetooth right now e.g. BT radio is off, or not present.
    kBluetoothUnavailable,
    // TODO(https://crbug.com/897996): Add more specific error codes.
  };

  // Attempts to stop scanning for Bluetooth devices. Callback is run with
  // `kSuccess` if the command was successfully sent to the BT Radio. Once the
  // BT Radio actually stops scanning for devices,
  // BluetoothSystemClient::OnScanStateChanged will be called.
  // TODO(https://crbug.com/897996): This function is missing two features:
  //  1. Support concurrent calls; currently BlueZ just drops other calls if
  //     there is one in progress already.
  //  2. Return more detailed error codes.
  StopScan() => (StopScanResult result);
};

// Interface used by clients of BluetoothSystem to get notified of events
// like Bluetooth State changes.
interface BluetoothSystemClient {
  OnStateChanged(BluetoothSystem.State new_state);
  OnScanStateChanged(BluetoothSystem.ScanState new_state);
};