// Copyright 2022 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.test.audio.recording;

using zx;

/// Maximum number of bytes in a audio input payload
const AUDIO_INPUT_BYTES_MAX uint32 = 8192;

/// Status code for Audio Recording FIDL
type AudioRecordingError = strict enum {
    FAIL = 1;
};

/// A protocol that supports audio input injection and audio capture.
@discoverable
closed protocol AudioRecordingControl {

    /// Writes and appends `audio_data` at `index`.
    ///
    /// The first time this is called, an empty vector will be created, subsequent calls will
    /// append to `audio_data` to the same vector.
    ///
    /// Use `ClearInputAudio` to clear audio input data stored at `index`.
    ///
    /// + request `index` refers a specific `audio_data` input record. We can have multiple records.
    /// + request `audio_data` vector containing audio_data bytes.
    /// - response `byte_count` the total number of bytes stored.
    strict PutInputAudio(resource struct {
        index int32;
        audio_data vector<uint8>:AUDIO_INPUT_BYTES_MAX;
    }) -> (struct {
        byte_count int32;
    });

    /// Clears audio data stored at `index`.
    ///
    /// If no data exists at `index` nothing will get cleaned.
    ///
    /// + request `index` refers a specific `audio_data` input record to clear.
    /// - response `error` a AudioRecordingError value indicating success or failure.
    strict ClearInputAudio(resource struct {
        index int32;
    }) -> () error AudioRecordingError;

    /// Returns the captured audio data in `zx.Handle.VMO`.
    ///
    /// User should have first called `StartOutputSave` and `StopOutputSave`.
    ///
    /// + request `audio_data` vmo containing the full captured audio data.
    strict GetOutputAudio() -> (resource struct {
        audio_data zx.Handle:VMO;
    });

    /// Starts inject audio data stored at `index`.
    /// Use `PutInputAudio` to store audio data.
    ///
    /// + request `index` refers a specific `audio_data` input record to clear.
    /// - response `error` a AudioRecordingError value indicating success or failure.
    strict StartInputInjection(resource struct {
        index int32;
    }) -> () error AudioRecordingError;

    /// Stops inject audio data.
    ///
    /// - response `error` a AudioRecordingError value indicating success or failure.
    strict StopInputInjection() -> () error AudioRecordingError;

    /// Start capturing audio output
    ///
    /// - response `error` a AudioRecordingError value indicating success or failure.
    strict StartOutputSave() -> () error AudioRecordingError;

    /// Stops capturing the audio output.
    ///
    /// Use `GetOutputAudio` to get the latest audio capture.
    ///
    /// - response `error` a AudioRecordingError value indicating success or failure.
    strict StopOutputSave() -> () error AudioRecordingError;
};