// Copyright 2024 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.le;

using fuchsia.bluetooth as bt;
using zx;

/// Parameters related to a single direction of transmission in an established CIS.
@available(added=HEAD)
type CisUnidirectionalParams = table {
    /// Transport latency, in the range [234, 8388607] microseconds
    ///
    /// This field is always present.
    1: transport_latency zx.Duration;

    /// Burst number for transmissions in this direction.
    ///
    /// This field is always present.
    2: burst_number uint8;

    /// Flush timeout for each payload, in multiples of the ISO interval.
    ///
    /// This field is always present.
    3: flush_timeout uint8;
};

/// Established configuration for a single CIS.
@available(added=HEAD)
type CisEstablishedParameters = table {
    /// Maximum time for transmission of PDUs of all CISes in a CIG event.
    /// In the range [234, 8388607] microseconds.
    ///
    /// This field is always present.
    1: cig_sync_delay zx.Duration;

    /// The maximum time for transmission of PDUs of the specified CIS in a CIG
    /// event. In the range [234, 8388607] microseconds.
    ///
    /// This field is always present.
    2: cis_sync_delay zx.Duration;

    /// Maximum number of subevents in each CIS event.
    ///
    /// This field is always present.
    3: max_subevents uint8;

    /// Time between two consecutive CIS anchor points, in the range [5ms, 4s]
    ///
    /// This field is always present.
    4: iso_interval zx.Duration;

    /// Parameters for Central => Peripheral transmissions, if applicable.
    ///
    /// This field is present if the stream includes isochronous data transmission from the
    /// Central to the Peripheral.
    5: central_to_peripheral_params CisUnidirectionalParams;

    /// Parameters for Peripheral => Central transmissions, if applicable.
    ///
    /// This field is present if the stream includes isochronous data transmission from the
    /// Peripheral to the Central.
    6: peripheral_to_central_params CisUnidirectionalParams;
};

/// Flags indicating validity of data received from an isochronous channel.
@available(added=HEAD)
type IsoPacketStatusFlag = strict enum : uint8 {
    /// Valid data. The complete SDU was received correctly.
    VALID_DATA = 0;

    /// Possibly invalid data. One ore more of the fragments received may contain errors or part of
    /// the packet may be missing.
    DATA_WITH_POSSIBLE_ERRORS = 1;

    /// Parts of the packet were not received correctly.
    LOST_DATA = 2;
};

@available(added=HEAD)
open protocol IsochronousStream {
    /// Provide notification when a CIS is established, as initiated by a Central
    /// (from CigServer::CreateCis()), or a Peripheral (from CisRequestManager::Accept()).
    flexible -> OnEstablished(table {

        /// A result of ZX_ERR_INTERNAL indicates that the controller received a request
        /// but was unable to establish the stream.
        1: result zx.Status;

        /// This field is always present if a stream was successfully established.
        2: established_params CisEstablishedParameters;
    });

    /// Create an isochronous data path with the specified parameters. Only in-band (HCI) ISO
    /// transport is currently supported.
    ///
    /// Returns ZX_ERR_ALREADY_EXISTS if a ISO stream has already been created for this
    /// direction.
    ///
    /// Returns ZX_ERR_BAD_STATE if issued on a peripheral before a CIS request has been
    /// accepted.
    ///
    /// Returns ZX_ERR_INVALID_ARGS if the codec arguments are invalid or outside of the
    /// controller's supported range.
    flexible SetupDataPath(table {
        /// Directions in which data will flow.
        /// Required.
        1: data_direction bt.DataDirection;

        /// Specifies the coding format used over the air.
        /// Required.
        2: codec_attributes bt.CodecAttributes;

        /// The delay provided must be within the controller's supported range and should not
        /// exceed 4 seconds.
        /// Required.
        3: controller_delay zx.Duration;
    }) -> () error zx.Status;

    /// Receive data from an output (controller => host) ISO stream that has been established and
    /// set up. Designed to be used with a hanging get pattern.
    ///
    /// Can be invoked before the ISO data stream has been established and set up, but will not
    /// return until after it has been set up and data has been received.
    flexible Read() -> (table {
        /// The data frame itself.
        /// Required.
        1: data vector<uint8>:MAX;

        /// The sequence number associated with the frame.
        /// Required.
        2: sequence_number uint16;

        /// Status flags of packet, as reported by the controller.
        /// Required.
        3: status_flag IsoPacketStatusFlag;

        /// Reception timestamp, as reported by the controller.
        /// Optional.
        4: timestamp zx.Duration;
    });
};