// 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.bluetooth.gatt;

using fuchsia.bluetooth as bt;

/// Codes that can be returned in the `protocol_error_code` field of a
/// bluetooth.Error.
type ErrorCode = strict enum {
    /// Indicates that the operation was successful.
    NO_ERROR = 0;

    /// Indicates that the offset used in a read or write request exceeds the
    /// bounds of the value.
    INVALID_OFFSET = 1;

    /// Indicates that the value given in a write request would exceed the maximum
    /// length allowed for the destionation characteristic or descriptor.
    INVALID_VALUE_LENGTH = 2;

    /// Indicates that a read or write request is not permitted.
    NOT_PERMITTED = 3;
};

/// Errors that are returned by bluetooth.gatt methods.
type Error = strict enum {
    /// A general error occurred that can not be classified as one of the more specific statuses.
    FAILURE = 1;

    /// Indicates that the response received from the server was invalid.
    INVALID_RESPONSE = 2;

    /// Indicates that more results were read than can fit in a FIDL response. Consider
    /// reading attributes individually.
    TOO_MANY_RESULTS = 3;

    /// This attribute requires authorization, but the client is not authorized.
    INSUFFICIENT_AUTHORIZATION = 4;

    /// This attribute requires authentication, but the client is not authenticated.
    INSUFFICIENT_AUTHENTICATION = 5;

    /// This attribute requires a connection encrypted by a larger encryption key.
    INSUFFICIENT_ENCRYPTION_KEY_SIZE = 6;

    /// This attribute requires encryption, but the connection is not encrypted.
    INSUFFICIENT_ENCRYPTION = 7;

    /// This attribute is not readable.
    READ_NOT_PERMITTED = 8;
};

/// Represents encryption, authentication, and authorization permissions that can
/// be assigned to a specific access permission.
type SecurityRequirements = struct {
    /// If true, the physical link must be encrypted to access this attribute.
    encryption_required bool;

    /// If true, the physical link must be authenticated to access this
    /// attribute.
    authentication_required bool;

    /// If true, the client needs to be authorized before accessing this
    /// attribute.
    authorization_required bool;
};

/// Specifies the access permissions for a specific attribute value.
type AttributePermissions = struct {
    /// Specifies whether or not an attribute has the read permission. If null,
    /// then the attribute value cannot be read. Otherwise, it can be read only if
    /// the permissions specified in the Permissions struct are satisfied.
    read box<SecurityRequirements>;

    /// Specifies whether or not an attribute has the write permission. If null,
    /// then the attribute value cannot be written. Otherwise, it be written only
    /// if the permissions specified in the Permissions struct are satisfied.
    write box<SecurityRequirements>;

    /// Specifies the security requirements for a client to subscribe to
    /// notifications or indications on a characteristic. A characteristic's
    /// support for notifications or indiciations is specified using the NOTIFY and
    /// INDICATE characteristic properties. If a local characteristic has one of
    /// these properties then this field can not be null. Otherwise, this field
    /// must be left as null.
    ///
    /// This field is ignored for Descriptors.
    update box<SecurityRequirements>;
};

/// Possible values for the characteristic properties bitfield. These specify the
/// GATT procedures that are allowed for a particular characteristic.
const kPropertyBroadcast uint32 = 1;
const kPropertyRead uint32 = 2;
const kPropertyWriteWithoutResponse uint32 = 4;
const kPropertyWrite uint32 = 8;
const kPropertyNotify uint32 = 16;
const kPropertyIndicate uint32 = 32;
const kPropertyAuthenticatedSignedWrites uint32 = 64;
const kPropertyReliableWrite uint32 = 256;
const kPropertyWritableAuxiliaries uint32 = 512;

/// Represents a local or remote GATT service.
type ServiceInfo = struct {
    /// Uniquely identifies this GATT service. This value will be ignored for local
    /// services. Remote services will always have an identifier.
    id uint64;

    /// Indicates whether this is a primary or secondary service.
    primary bool;

    /// The 128-bit UUID that identifies the type of this service. This is a string
    /// in the canonical 8-4-4-4-12 format.
    type bt.UuidString;

    /// The characteristics of this service.
    characteristics vector<Characteristic>:<MAX_CHARACTERISTIC_COUNT, optional>;

    /// Ids of other services that are included by this service.
    includes vector<uint64>:<MAX_SERVICE_COUNT, optional>;
};

/// Represents a local or remote GATT characteristic.
type Characteristic = struct {
    /// Uniquely identifies this characteristic within a service.
    id uint64;

    /// The 128-bit UUID that identifies the type of this characteristic. This is a
    /// string in the canonical 8-4-4-4-12 format.
    type bt.UuidString;

    /// The characteristic properties bitfield. See kProperty* above for possible
    /// values.
    properties uint32;

    /// The attribute permissions of this characteristic. For remote
    /// characteristics, this value will be null until the permissions are
    /// discovered via read and write requests.
    ///
    /// For local characteristics, this value is mandatory.
    permissions box<AttributePermissions>;

    /// The descriptors of this characteristic.
    descriptors vector<Descriptor>:<MAX_DESCRIPTOR_COUNT, optional>;
};

/// Represents a local or remote GATT characteristic descriptor.
type Descriptor = struct {
    /// Uniquely identifies this descriptor within the characteristic that it
    /// belongs to.
    id uint64;

    /// The 128-bit UUID that identifies the type of this descriptor. This is a
    /// string in the canonical 8-4-4-4-12 format.
    type bt.UuidString;

    /// The attribute permissions of this descriptor. For remote
    /// descriptors, this value will be null until the permissions are
    /// discovered via read and write requests.
    ///
    /// For local descriptors, this value is mandatory.
    permissions box<AttributePermissions>;
};

/// Represents the reliability mode during long and prepared write operations.
///
/// If enabled, every value blob is verified against an echo response from the server.
/// The procedure is aborted if a value blob has not been reliably delivered to the peer.
type ReliableMode = strict enum {
    DISABLED = 1;
    ENABLED = 2;
};

/// Represents the supported options to write a characteristic value to a server.
type WriteOptions = table {
    /// The reliable mode of the write operation.
    ///
    /// Defaults to [`fuchsia.bluetooth.gatt/ReliableMode.DISABLED`] if not present.
    1: reliable_mode ReliableMode;
};