// 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;

/// Wrapper around a possible truncated value received from the server.
type ReadValue = table {
    /// Characteristic or descriptor handle. Always present.
    1: handle Handle;
    /// The value of the characteristic or descriptor. Always present.
    2: value bytes:MAX_VALUE_LENGTH;
    /// True if `value` might be truncated (the buffer was completely filled
    /// by the server). `ReadCharacteristic` or `ReadDescriptor` should be used
    /// to read the complete value.
    /// Always present.
    3: maybe_truncated bool;
};

/// A result returned by `RemoteService.ReadByType`.
type ReadByTypeResult = table {
    /// Characteristic or descriptor handle.
    1: handle Handle;
    /// The value of the characteristic or descriptor, if it was read successfully.
    2: value ReadValue;
    /// Reason the value could not be read, if reading it resulted in an error.
    3: error Error;
};

/// Listens to characteristic notifications & indications.
protocol CharacteristicNotifier {
    /// Called when a characteristic value notification or indication is
    /// received from the server.
    ///
    /// + request `value` the value of the updated characteristic.
    /// - response An empty response should be sent immediately as an
    ///   acknowledgement that the notification was received (for flow control).
    OnNotification(struct {
        value ReadValue;
    }) -> ();
};

protocol RemoteService {
    /// Returns the characteristics and characteristic descriptors that belong to
    /// this service.
    DiscoverCharacteristics() -> (struct {
        characteristics vector<Characteristic>:MAX_CHARACTERISTIC_COUNT;
    });

    /// Reads characteristics and descriptors with the given `uuid`.
    ///
    /// This method is useful for reading values before discovery has completed,
    /// thereby reducing latency.
    ///
    /// + request `uuid` The UUID of the characteristics/descriptors to read.
    /// - response `results` The results of the read. May be empty if no
    ///            matching values are read. If reading a value results in a
    ///            permission error, the handle and error will be included.
    /// * error Returns `INVALID_PARAMETERS` if `uuid` refers to an internally
    ///         reserved descriptor type (e.g. the Client Characteristic
    ///         Configuration descriptor).
    /// * error Returns `TOO_MANY_RESULTS` if more results were read than can fit
    ///         in a FIDL response. Consider reading characteristics/descriptors
    ///         individually after performing discovery.
    /// * error Returns `FAILURE` if the server returns an error not specific to
    ///         a single result.
    ReadByType(struct {
        uuid bt.Uuid;
    }) -> (struct {
        results vector<ReadByTypeResult>:MAX_ATTRIBUTE_COUNT;
    }) error Error;

    /// Reads the value of a characteristic with the given `handle`.
    ///
    /// + request `handle` The characteristic handle to read.
    /// + request `options` Options that apply to the read.
    /// - response `value` The value of the characteristic.
    /// * error Returns `INVALID_HANDLE` if `handle` is invalid.
    /// * error Returns `INVALID_PARAMETERS` if `options` is invalid.
    /// * error Returns `READ_NOT_PERMITTED` or `INSUFFICIENT_*` if the server
    ///         rejects the read request.
    /// * error Returns `FAILURE` if the server returns an error.
    ReadCharacteristic(struct {
        handle Handle;
        options ReadOptions;
    }) -> (struct {
        value ReadValue;
    }) error Error;

    /// Writes `value` to the characteristic with `handle` using the provided
    /// `options`.
    ///
    /// It is not recommended to send additional writes while a write is already
    /// in progress (the server may receive simultaneous writes in any order).
    ///
    /// + request `handle` The characteristic to be written to.
    /// + request `value` The value to be written.
    /// + request `options` Options that apply to the write.
    /// - response An empty response will be sent when a success response is
    ///            received from the server (or immediately if
    ///            `options.with_response` is false)
    /// * error Returns `INVALID_HANDLE` if `handle` is invalid.
    /// * error Returns `INVALID_PARAMETERS` if `options` is invalid.
    /// * error Returns `WRITE_NOT_PERMITTED` or `INSUFFICIENT_*`if the server
    ///         rejects the write request with a reason.
    /// * error Returns `FAILURE` if the server returns an error.
    WriteCharacteristic(struct {
        handle Handle;
        value bytes:MAX_VALUE_LENGTH;
        options WriteOptions;
    }) -> (struct {}) error Error;

    /// Reads the value of the characteristic descriptor with `handle` and
    /// returns it in the reply.
    ///
    /// + request `handle` The descriptor handle to read.
    /// + request `options` Options that apply to the read.
    /// - response `value` The value of the descriptor.
    /// * error Returns `INVALID_HANDLE` if `handle` is invalid.
    /// * error Returns `INVALID_PARAMETERS` if `options` is invalid.
    /// * error Returns `READ_NOT_PERMITTED` or `INSUFFICIENT_*` if the server
    ///         rejects the read request.
    /// * error Returns `FAILURE` if the server returns an error.
    ReadDescriptor(struct {
        handle Handle;
        options ReadOptions;
    }) -> (struct {
        value ReadValue;
    }) error Error;

    /// Writes `value` to the characteristic descriptor with `handle`.
    /// It is not recommended to send additional writes while a write is already
    /// in progress (the server may receive simultaneous writes in any order).
    ///
    /// + request `handle` The descriptor handle to written to.
    /// + request `value` The value to be written.
    /// + request `options` Options that apply to the write.
    /// - response An empty response will be sent when a success response is
    ///            received from the server (or immediately if
    ///            `options.with_response` is false)
    /// * error Returns `INVALID_HANDLE` if `handle` is invalid or refers to an
    ///         internally reserved descriptor type (e.g. the Client
    ///         Characteristic Configuration descriptor).
    /// * error Returns `INVALID_PARAMETERS` if `options` is invalid.
    /// * error Returns `WRITE_NOT_PERMITTED` or `INSUFFICIENT_*` if the server
    ///         rejects the write with a reason.
    /// * error Returns `FAILURE` if the server returns an error.
    WriteDescriptor(struct {
        handle Handle;
        value bytes:MAX_VALUE_LENGTH;
        options WriteOptions;
    }) -> (struct {}) error Error;

    /// Subscribe to notifications & indications from the characteristic with
    /// the given `handle`.
    ///
    /// Either notifications or indications will be enabled depending on
    /// characteristic properties. Indications will be preferred if they are
    /// supported. This operation fails if the characteristic does not have the
    /// "notify" or "indicate" property.
    ///
    /// A write request will be issued to configure the characteristic for
    /// notifications/indications if it contains a Client Characteristic
    /// Configuration descriptor. This method fails if an error occurs while
    /// writing to the descriptor.
    ///
    /// On success, the `notifier` protocol can be used to be notified when
    /// the peer sends a notification or indication. Indications are
    /// automatically confirmed. When the protocol is dropped, the subscription
    /// may end if no other local client is receiving notifications.
    ///
    /// + request `handle` the characteristic handle.
    /// + request `notifier` the protocol used for notifications.
    /// - response An empty response will be sent immediately if registration
    ///            succeeds.
    /// * error Returns a `FAILURE` if the characteristic does not support
    ///         notifications or indications.
    /// * error Returns a `INVALID_HANDLE` if `handle` is invalid.
    /// * error Returns a `WRITE_NOT_PERMITTED`  or `INSUFFICIENT_*`for a
    ///         descriptor write error.
    RegisterCharacteristicNotifier(resource struct {
        handle Handle;
        notifier client_end:CharacteristicNotifier;
    }) -> (struct {}) error Error;
};

protocol Client {
    /// Enumerates services found on the peer that this Client represents.
    ///
    /// Results can be filtered by specifying a list of UUIDs in `uuids`. This
    /// method follows the hanging get pattern. On the initial request, a
    /// complete snapshot will be returned. Subsequent calls with the same set
    /// of `uuids` receive a response only when one or more services have been
    /// added, modified, or removed from the entries reported since the most
    /// recent call. Calls with new values of `uuids` will reset the filter and
    /// receive a complete snapshot.
    ///
    /// Handles may be reused across services, so a handle may be in both
    /// `updated` and `removed`. For this reason, it is recommended to process
    /// removed services before updated services.
    ///
    /// To further interact with services, clients must obtain a RemoteService
    /// protocol by calling ConnectToService().
    ///
    /// + request `uuids` the UUID allowlist. If empty, all services will be
    ///   returned.
    /// - response `updated` the services that have been added or modified since
    ///   WatchServices() was last called. The returned ServiceInfo tables will
    ///   contain only basic information about each service and the
    ///   `characteristics` and `includes` fields will be null. If a service has
    ///   been added/modified and then removed since the last call, it will only
    ///   be present in `removed`, not `updated`.
    /// - response `removed` the handles of the services that have been removed
    ///   since the last call to WatchServices().
    WatchServices(struct {
        uuids vector<bt.Uuid>:MAX;
    }) -> (struct {
        updated vector<ServiceInfo>:MAX_SERVICE_COUNT;
        removed vector<Handle>:MAX_SERVICE_COUNT;
    });

    /// Connects the RemoteService with the given identifier. Only 1 connection
    /// per service is allowed.
    ///
    /// `service` will be closed on error, with an epitaph that provides a
    /// reason.
    /// * error Returns a `ZX_ERR_INVALID_ARGS` if `handle` is invalid.
    /// * error Returns a `ZX_ERR_NOT_FOUND` if the service is not found.
    /// * error Returns a `ZX_ERR_CONNECTION_RESET` if the service is removed.
    /// * error Returns a `ZX_ERR_NOT_CONNECTED` if the peer disconnects.
    /// * error Returns a `ZX_ERR_ALREADY_EXISTS` if the service is already connected.
    ConnectToService(resource struct {
        handle ServiceHandle;
        service server_end:RemoteService;
    });
};