// Copyright 2016 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 bluetooth.mojom;

import "device/bluetooth/public/mojom/uuid.mojom";

// Values representing the possible properties of a characteristic, which
// define how the characteristic can be used. Each of these properties serve
// a role as defined in the Bluetooth Specification.
// |EXTENDED_PROPERTIES| is a special property that, if present,
// indicates that there is a characteristic descriptor (namely the
// "Characteristic Extended Properties Descriptor" with UUID 0x2900) that
// contains additional properties pertaining to the characteristic.
// The properties |RELIABLE_WRITE| and |WRITABLE_AUXILIARIES| are retrieved from
// that characteristic.
// TODO(crbug.com/684168): Remove assignment of values when this is automated.
enum Property {
  NONE = 0,
  BROADCAST = 1,
  READ = 2,
  WRITE_WITHOUT_RESPONSE = 4,
  WRITE = 8,
  NOTIFY = 16,
  INDICATE = 32,
  AUTHENTICATED_SIGNED_WRITES = 64,
  EXTENDED_PROPERTIES = 128,
  RELIABLE_WRITE = 256,
  WRITABLE_AUXILIARIES = 512,
  READ_ENCRYPTED = 1024,
  WRITE_ENCRYPTED = 2048,
  READ_ENCRYPTED_AUTHENTICATED = 4096,
  WRITE_ENCRYPTED_AUTHENTICATED = 8192
};

enum GattResult {
  SUCCESS,
  UNKNOWN,
  FAILED,
  IN_PROGRESS,
  INVALID_LENGTH,
  NOT_PERMITTED,
  NOT_AUTHORIZED,
  NOT_PAIRED,
  NOT_SUPPORTED,
  SERVICE_NOT_FOUND,
  CHARACTERISTIC_NOT_FOUND,
  DESCRIPTOR_NOT_FOUND
};

// TODO(crbug.com/657632): Remove when numerical values can be optional.
struct RSSIWrapper {
  int8 value;
};

struct DeviceInfo {
  string? name;
  string name_for_display;
  string address;
  bool is_gatt_connected;
  RSSIWrapper? rssi;
};

struct ServiceInfo {
  string id;
  UUID uuid;
  bool is_primary;
};

struct CharacteristicInfo {
  string id;
  UUID uuid;
  uint32 properties;
  array<uint8> last_known_value;
};

struct DescriptorInfo {
  string id;
  UUID uuid;
  array<uint8> last_known_value;
};

interface Device {
  // Disconnects and deletes the Device.
  Disconnect();

  // Gets basic information about the device. Returns null, if no device is
  // available.
  GetInfo() => (DeviceInfo? info);

  // Gets the GATT Services in this device's GATT Server.
  GetServices() => (array<ServiceInfo> services);

  // Gets the GATT Characteristics in the GATT Service with |service_id|.
  // If |characteristics| is null, an error occured while attempting to retrieve
  // the array of characteristics. If |characteristics| is empty, this simply
  // means that no characteristics were found.
  GetCharacteristics(string service_id) =>
      (array<CharacteristicInfo>? characteristics);

  // Reads the value for the GATT Characteristic with |characteristic_id| in
  // the GATT Service with |service_id|.
  ReadValueForCharacteristic(string service_id, string characteristic_id) =>
      (GattResult result, array<uint8>? value);

  // Writes the |value| to the GATT Characteristic with |characteristic_id| in
  // the GATT Service with |service_id|.
  WriteValueForCharacteristic(string service_id, string characteristic_id,
      array<uint8> value) => (GattResult result);

  // Gets the GATT Descriptors of the GATT Characteristic with matching
  // |characteristic_id| in the GATT Service with matching |service_id|.
  // If |descriptors| is null, an error occured while attempting to retrieve
  // the array of descriptors. If |descriptors| is empty, this simply
  // means that no descriptors were found.
  GetDescriptors(string service_id, string characteristic_id) =>
      (array<DescriptorInfo>? descriptors);

  // Reads the value for the GATT Descriptor with |descriptor_id| in the GATT
  // Characteristic with |characteristic_id| in the GATT Service with
  // |service_id|.
  ReadValueForDescriptor(string service_id, string characteristic_id,
      string descriptor_id) => (GattResult result, array<uint8>? value);

  // Writes the |value| for the GATT Descriptor with |descriptor_id| in the GATT
  // Characteristic with |characteristic_id| in the GATT Service with
  // |service_id|.
  WriteValueForDescriptor(string service_id, string characteristic_id,
      string descriptor_id, array<uint8> value) => (GattResult result);
};