// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.hardware.bt.gattsvc;

using zx;

alias BtGattId = uint64;

struct BtGattUuid {
    array<uint8>:16 bytes;
};

/// ATT protocol error codes.
enum BtGattErr : uint8 {
    NO_ERROR = 0x00;
    INVALID_HANDLE = 0x01;
    READ_NOT_PERMITTED = 0x02;
    WRITE_NOT_PERMITTED = 0x03;
    INVALID_PDU = 0x04;
    INSUFFICIENT_AUTHENTICATION = 0x05;
    REQUEST_NOT_SUPPORTED = 0x06;
    INVALID_OFFSET = 0x07;
    INSUFFICIENT_AUTHORIZATION = 0x08;
    PREPARE_QUEUE_FULL = 0x09;
    ATTRIBUTE_NOT_FOUND = 0x0A;
    ATTRIBUTENOTLONG = 0x0B;
    INSUFFICIENT_ENCRYPTION_KEY_SIZE = 0x0C;
    INVALID_ATTRIBUTE_VALUE_LENGTH = 0x0D;
    UNLIKELY_ERROR = 0x0E;
    INSUFFICIENT_ENCRYPTION = 0x0F;
    UNSUPPORTED_GROUP_TYPE = 0x10;
    INSUFFICIENT_RESOURCES = 0x11;
};

/// Represents the status of a GATT operation.
struct BtGattStatus {
    /// Represents errors reported by the host (i.e. not over ATT).
    zx.status status;

    /// ATT protocol error.
    BtGattErr att_ecode;
};

/// Possible values for the characteristic properties bitfield.
enum BtGattChrPropr : uint8 {
    BROADCAST = 0x01;
    READ = 0x02;
    WRITE_WITHOUT_RESPONSE = 0x04;
    WRITE = 0x08;
    NOTIFY = 0x10;
    INDICATE = 0x20;
    AUTHENTICATED_SIGNED_WRITES = 0x40;
    EXTENDED_PROPERTIES = 0x80;
};

enum BtGattChrExtProp : uint16 {
    RELIABLE_WRITE = 0x0100;
    WRITABLE_AUXILIARIES = 0x0200;
};

/// Represents a GATT characteristic descriptor.
struct BtGattDescriptor {
    BtGattId id;
    BtGattUuid type;
};

/// Represents a GATT characteristic.
struct BtGattChr {
    BtGattId id;
    BtGattUuid type;

    /// The bitmask of characteristic properties. The |extended_properties| field
    /// is populated if the "Characteristic Extended Properties" descriptor is
    /// present.
    ///
    /// See enums |BtGattChrProp| and |BtGattChrExtProp| for possible bit values.
    uint8 properties;
    uint16 extended_properties;

    [Mutable] vector<BtGattDescriptor> descriptor;
};

/// Value change notification callback of the |EnableNotifications| function.
[Transport = "Banjo", BanjoLayout = "ddk-callback"]
protocol BtGattNotificationValue {
    Callback(BtGattId id, [Buffer] vector<uint8> value) -> ();
};

[Transport = "Banjo", BanjoLayout = "ddk-protocol"]
protocol BtGattSvc {
    /// Connects to and starts characteristic discovery on the remote service.
    ///
    /// |status| will contain the result of the characteristic discovery procedure if it was
    /// initiated by |connect|. The service will be ready to receive further requests once this
    /// has been called successfully and the |status| callback has been called with success.
    [Async]
    Connect() -> (BtGattStatus status, vector<BtGattChr> characteristic);

    /// Stops this service and unregisters previously registered callbacks.
    Stop() -> ();

    /// Reads the value of the characteristic with the given ID.
    [Async]
    ReadCharacteristic(BtGattId id) -> (BtGattStatus status, BtGattId id, [Buffer] vector<uint8> value);

    /// Reads the long value of the characteristic with the given ID.
    [Async]
    ReadLongCharacteristic(BtGattId id, uint16 offset, uint64 max_bytes)
                     -> (BtGattStatus status, BtGattId id, [Buffer] vector<uint8> value);

    /// Writes a characteristic with the given ID. Automatically handles long writes
    /// if required by the mtu size.
    [Async]
    WriteCharacteristic(BtGattId id, [Buffer] vector<uint8> buf) -> (BtGattStatus status, BtGattId id);

    /// Enables notifications from the characteristic with the given ID. Returns
    /// `ZX_ERR_BAD_STATE` if the service has not been started yet.
    ///
    /// Returns `ZX_ERR_SHOULD_WAIT` if this request is already in progress.
    ///
    /// The async callback will be called to asynchronously report the result
    /// of this operation.
    [Async]
    EnableNotifications(BtGattId id, BtGattNotificationValue value_cb)
                     -> (BtGattStatus status, BtGattId id);
};