// Copyright 2021 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.gatt2;

using fuchsia.bluetooth as bt;

/// Errors that are returned by bluetooth.gatt2.* methods.
///
/// The values correspond with those in Bluetooth 5.2 Vol. 3 Part G Table 3.4,
/// and Supplement to the Bluetooth Core Specification v9 Part B Table 1.1,
/// but this is for ease of reference only.  Clients should *not* rely on these
/// values remaining constant.  Omitted values from the spec are handled
/// internally and will not be returned to clients.
///
/// Only certain errors can be returned by LocalService methods.  Those are noted
/// in comments.
type Error = strict enum {
    // ATT Errors

    /// The attribute indicated by the handle is invalid. It may have been removed.
    ///
    /// This may be returned by a LocalService method.
    INVALID_HANDLE = 0x1;

    /// This attribute is not readable.
    READ_NOT_PERMITTED = 0x2;

    /// This attribute is not writable.
    WRITE_NOT_PERMITTED = 0x3;

    /// Indicates that the response received from the server was invalid.
    INVALID_PDU = 0x4;

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

    /// Indicates that the offset used in a read or write request exceeds the
    /// bounds of the value.
    ///
    /// This may be returned by a LocalService method.
    INVALID_OFFSET = 0x7;

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

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

    /// Indicates that the value given in a write request would exceed the maximum
    /// length allowed for the destionation characteristic or descriptor.
    ///
    /// This may be returned by a LocalService method.
    INVALID_ATTRIBUTE_VALUE_LENGTH = 0xD;

    /// A general error occurred that can not be classified as one of the more
    /// specific errors.
    ///
    /// This may be returned by a LocalService method.
    UNLIKELY_ERROR = 0xE;

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

    /// The server had insufficient resources to complete the task.
    ///
    /// This may be returned by a LocalService method.
    INSUFFICIENT_RESOURCES = 0x11;

    /// The value was not allowed.
    ///
    /// This may be returned by a LocalService method.
    VALUE_NOT_ALLOWED = 0x13;

    // Application Errors

    /// Application Errors.  The uses of these are specified at the application
    /// level.
    ///
    /// These may all be returned by a LocalService method.
    APPLICATION_ERROR_80 = 0x80;
    APPLICATION_ERROR_81 = 0x81;
    APPLICATION_ERROR_82 = 0x82;
    APPLICATION_ERROR_83 = 0x83;
    APPLICATION_ERROR_84 = 0x84;
    APPLICATION_ERROR_85 = 0x85;
    APPLICATION_ERROR_86 = 0x86;
    APPLICATION_ERROR_87 = 0x87;
    APPLICATION_ERROR_88 = 0x88;
    APPLICATION_ERROR_89 = 0x89;
    APPLICATION_ERROR_8A = 0x8A;
    APPLICATION_ERROR_8B = 0x8B;
    APPLICATION_ERROR_8C = 0x8C;
    APPLICATION_ERROR_8D = 0x8D;
    APPLICATION_ERROR_8E = 0x8E;
    APPLICATION_ERROR_8F = 0x8F;
    APPLICATION_ERROR_90 = 0x90;
    APPLICATION_ERROR_91 = 0x91;
    APPLICATION_ERROR_92 = 0x92;
    APPLICATION_ERROR_93 = 0x93;
    APPLICATION_ERROR_94 = 0x94;
    APPLICATION_ERROR_95 = 0x95;
    APPLICATION_ERROR_96 = 0x96;
    APPLICATION_ERROR_97 = 0x97;
    APPLICATION_ERROR_98 = 0x98;
    APPLICATION_ERROR_99 = 0x99;
    APPLICATION_ERROR_9A = 0x9A;
    APPLICATION_ERROR_9B = 0x9B;
    APPLICATION_ERROR_9C = 0x9C;
    APPLICATION_ERROR_9D = 0x9D;
    APPLICATION_ERROR_9E = 0x9E;
    APPLICATION_ERROR_9F = 0x9F;

    // Common Profile and Service Error Codes

    /// Write request was rejected at the profile or service level.
    WRITE_REQUEST_REJECTED = 0xFC;

    /// The Client Characteristic Configuration Descriptor was improperly
    /// configured.
    CCC_DESCRIPTOR_IMPROPERLY_CONFIGURED = 0xFD;

    /// Profile or service procedure already in progress.
    PROCEDURE_ALREADY_IN_PROGRESS = 0xFE;

    /// A value was out of range at the profile or service level.
    OUT_OF_RANGE = 0xFF;

    // Errors not specified by Bluetooth.

    /// One or more of the FIDL call parameters are invalid. See the parameter
    /// documentation.
    INVALID_PARAMETERS = 0x101;

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

/// Errors that can occur during service publication.
type PublishServiceError = flexible enum {
    /// The provided LocalService client_end was not a valid instance of the protocol.
    INVALID_LOCAL_SERVICE = 1;
    /// The service handle is invalid or already in use on the Server publishing the service.
    INVALID_SERVICE_HANDLE = 2;
    /// Invalid service UUID provided.
    INVALID_UUID = 3;
    /// The `ServiceInfo.characteristics` field was formatted invalidly or missing. If the service
    /// is meant to be empty, the vector should be empty, but present.
    INVALID_CHARACTERISTICS = 4;
    /// A general error occurred that can not be classified as one of the more specific errors.
    UNLIKELY_ERROR = 5;
};

// A Handle uniquely identifies a characteristic or descriptor.
type Handle = struct {
    value uint64;
};

// A ServiceHandle uniquely identifies a GATT service within a particular scope.
type ServiceHandle = struct {
    value uint64;
};

/// The kind ("type") of a GATT Service as outlined in Bluetooth Core Spec v5.3 Vol. 1 Part A 6.5.1.
type ServiceKind = strict enum {
    /// A "service that provides functionality of a device that can be used on its own" (Ibid)
    PRIMARY = 1;
    /// A "service that provides additional functionality [...] in association with a primary
    /// service and is included from at least one primary service" (Ibid)
    SECONDARY = 2;
};

/// Represents encryption, authentication, and authorization permissions that can
/// be assigned to a specific access permission.
type SecurityRequirements = table {
    /// If true, the physical link must be encrypted to access this attribute. If not present or
    /// false, this attribute permits unencrypted access.
    1: encryption_required bool;

    /// If true, the physical link must be authenticated to access this attribute. If not present or
    /// false, this attribute permits unauthenticated access.
    2: authentication_required bool;

    /// If true, the client needs to be authorized to access this attribute. If not present or
    /// false, this attribute permits access without authorization.
    3: authorization_required bool;
};

/// Specifies the access permissions for a specific attribute value.
type AttributePermissions = table {
    /// Specifies whether an attribute has the read permission. If not present,
    /// the attribute value cannot be read. Otherwise, it can be read only if the
    /// permissions specified in the SecurityRequirements table are satisfied.
    1: read SecurityRequirements;

    /// Specifies whether an attribute has the write permission. If not present,
    /// the attribute value cannot be written. Otherwise, it can be written only
    /// if the permissions specified in the SecurityRequirements table are satisfied.
    2: write 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 must be present. Otherwise, this field
    /// must not be present.
    ///
    /// This field is ignored for Descriptors.
    3: update SecurityRequirements;
};

/// Possible values for the characteristic properties bitfield. These specify the
/// GATT procedures that are allowed for a particular characteristic.
type CharacteristicPropertyBits = strict bits : uint16 {
    BROADCAST = 0x1;
    READ = 0x2;
    WRITE_WITHOUT_RESPONSE = 0x4;
    WRITE = 0x8;
    NOTIFY = 0x10;
    INDICATE = 0x20;
    AUTHENTICATED_SIGNED_WRITES = 0x40;
    RELIABLE_WRITE = 0x100;
    WRITABLE_AUXILIARIES = 0x200;
};

/// Represents a local or remote GATT service.
type ServiceInfo = table {
    /// Unique identifier for this GATT service.
    /// Always present if this represents a remote service, in which case this is unique across the
    /// Client that returned this ServiceInfo.
    /// Required for local services, in which case this must be unique across all services published
    /// to a single Server instance. Can be used in the `ServiceInfo.includes` of other
    /// PublishService calls to the Server where this service is published.
    1: handle ServiceHandle;

    /// Indicates whether this is a primary or secondary service.
    /// Always present for remote services. Optional for local services
    /// Default: ServiceKind::PRIMARY
    2: kind ServiceKind;

    /// The UUID that identifies the type of this service.
    /// There may be multiple services with the same UUID.
    /// Always present for remote services. Required for local services.
    3: type bt.Uuid;

    /// The characteristics of this service.
    /// Required for local services. Never present for remote services.
    4: characteristics vector<Characteristic>:MAX_CHARACTERISTIC_COUNT;

    /// Handles of other services that are included by this service.
    /// Optional for local services. Never present for remote services.
    /// TODO(fxbug.dev/685): This is not currently supported for local services.
    5: includes vector<ServiceHandle>:MAX_SERVICE_COUNT;
};

/// Represents a local or remote GATT characteristic.
type Characteristic = table {
    /// Uniquely identifies this characteristic within a service.
    /// For local characteristics, the specified handle must be unique across
    /// all characteristic and descriptor handles in this service.
    ///
    /// Always present. For local characteristics, this value is mandatory.
    1: handle Handle;

    /// The UUID that identifies the type of this characteristic.
    /// Always present. Mandatory for local characteristics.
    2: type bt.Uuid;

    /// The characteristic properties bitfield. See `CharacteristicPropertyBits`
    /// above for possible values.
    /// Always present. Mandatory for local characteristics.
    3: properties uint32;

    /// The attribute permissions of this characteristic. For remote
    /// characteristics, this value will not be present until the permissions are
    /// discovered via read and write requests.
    ///
    /// For local characteristics, this value is mandatory.
    4: permissions AttributePermissions;

    /// The descriptors of this characteristic.
    /// Present only if non-empty. Optional for local characteristics.
    5: descriptors vector<Descriptor>:MAX_DESCRIPTOR_COUNT;
};

/// Represents a local or remote GATT characteristic descriptor.
type Descriptor = table {
    /// Uniquely identifies this descriptor within a service.
    /// For local descriptors, the specified handle must be unique
    /// across all characteristic and descriptor handles in this service.
    ///
    /// Always present. For local descriptors, this value is mandatory.
    1: handle Handle;

    /// The UUID that identifies the type of this descriptor.
    /// Always present. For local descriptors, this value is mandatory.
    2: type bt.Uuid;

    /// The attribute permissions of this descriptor. For remote
    /// descriptors, this value will not be present until the permissions are
    /// discovered via read and write requests.
    ///
    /// For local descriptors, this value is mandatory.
    3: permissions AttributePermissions;
};

/// Represents the supported options to read a long characteristic or descriptor
/// value from a server. Long values are those that may not fit in a single
/// message (longer than 22 bytes).
type LongReadOptions = table {
    /// The byte to start the read at. Must be less than the length of the value.
    /// Optional.
    /// Default: 0
    1: offset uint16;
    /// The maximum number of bytes to read.
    /// Optional.
    /// Default: `MAX_VALUE_LENGTH`
    2: max_bytes uint16;
};

/// Represents the options for reading a short characteristic or descriptor
/// value from a server. Short values are those that fit in a single message,
/// which is at least 22 bytes. This is an empty placeholder for now, as there
/// are no options.
type ShortReadOptions = struct {};

/// Represents the supported options to read a characteristic or descriptor
/// value from a server.
type ReadOptions = flexible union {
    /// Perform a short read, which may be truncated (as indicated by the
    /// maybe_truncated in the result)
    /// Most reads in GATT services are short reads (<= 22 bytes).
    1: short_read ShortReadOptions;
    /// If present, perform a long read using the indicated options.
    /// Optional.
    /// Default: A short read will be performed.
    2: long_read LongReadOptions;
};

/// Represents the supported write modes for writing characteristics &
/// descriptors to the server.
type WriteMode = flexible enum {
    /// In `DEFAULT` mode, wait for a response from the server before returning
    /// and do not verify the echo response.
    /// Supported for both characteristics and descriptors.
    DEFAULT = 1;
    /// In `RELIABLE` mode, 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.
    /// Only supported for characteristics.
    RELIABLE = 2;
    /// In `WITHOUT_RESPONSE` mode, delivery will not be confirmed before
    /// returning. Writing without a response is only supported for short
    /// characteristics with the `WRITE_WITHOUT_RESPONSE` property. The value
    /// must fit into a single message. It is guaranteed that at least 20 bytes
    /// will fit into a single message. If the value does not fit, a `FAILURE`
    /// error will be produced. The value will be written at offset 0.
    /// Only supported for characteristics.
    WITHOUT_RESPONSE = 3;
};

/// Represents the supported options to write a characteristic/descriptor value
/// to a server.
type WriteOptions = table {
    /// The mode of the write operation. For descriptors, only
    /// [`WriteMode.DEFAULT`] is supported
    /// Optional.
    /// Default: [`WriteMode.DEFAULT`]
    1: write_mode WriteMode;
    /// Request a write starting at the byte indicated.
    /// Must be missing or 0 if `write_mode` is [`WriteMode.WITHOUT_RESPONSE`].
    /// Optional.
    /// Default: 0
    2: offset uint16;
};