blob: 84fae98b686e740ffa528500c97082eddb1e5268 [file] [log] [blame]
// 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;
// MAC Address for Bluetooth devices.
// Bluetooth Device Address (or BD_ADDR) is a unique 48-bit identifier assigned
// to each Bluetooth device by the manufacturer.
struct BluetoothAddress {
array<uint8, 6> address;
};
// Holds information about a Bluetooth Device.
struct BluetoothDeviceInfo {
enum ConnectionState {
kNotConnected,
kConnecting,
kConnected,
};
// Represent the different types of Bluetooth devices that we support
// or are aware of. Based on the Device Classes specified by the Bluetooth SIG
// https://www.bluetooth.com/specifications/assigned-numbers/baseband.
enum DeviceType {
kUnknown,
kComputer,
kPhone,
kModem,
kAudio,
kCarAudio,
kVideo,
kPeripheral,
kJoystick,
kGamepad,
kKeyboard,
kMouse,
kTablet,
kKeyboardMouseCombo,
};
// The MAC Address of the device e.g. AA:BB:CC:00:11:22.
BluetoothAddress address;
// Name of the device. Retrieved during the inquiry response for Classic
// devices, from the Advertisement from LE devices, or from the devices itself
// after connecting to it.
string? name;
// Indicates whether the device is not connected, connecting, or already
// connected.
ConnectionState connection_state;
// Indicates whether the device is paired to the system.
bool is_paired;
// Retrieved from the the Bluetooth class[1] for Classic and Dual devices and
// from the appearance characteristic[2] for LE devices.
//
// [1] https://www.bluetooth.com/specifications/assigned-numbers/baseband
// [2] https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.characteristic.gap.appearance.xml
DeviceType device_type;
};
// 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.
kFailedBluetoothUnavailable,
// Can't change the radio state right now, there is an in-progress call.
kFailedInProgress,
};
// 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. Does not support
// concurrent calls.
//
// To keep the implementation simple and because no clients need it (UI
// clients disable the power toggle during `kTransitioning`), this function
// does not support concurrent calls. Meaning, if there is a pending call to
// SetPowered(), all new calls to SetPowered() will immediately fail with
// `kFailedInProgress`.
//
// TODO(https://crbug.com/896113): This function is missing one feature:
// 1. The new state should be saved in the user's pref so that the next time
// the machine restarts the state matches the user pref.
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.
kFailedBluetoothUnavailable,
// 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.
kFailedBluetoothUnavailable,
// 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);
// Returns a list of devices we consider to be active. This includes
// recently seen devices, paired devices, and connected devices.
GetAvailableDevices() => (array<BluetoothDeviceInfo> devices);
};
// 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);
};