/*
 * Copyright (C) 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.audio@7.0;

import android.hardware.audio.common@7.0;
import IStream;

interface IStreamIn extends IStream {
    /**
     * Returns the source descriptor of the input stream. Calling this method is
     * equivalent to getting AUDIO_PARAMETER_STREAM_INPUT_SOURCE on the legacy
     * HAL.
     * Optional method
     *
     * @return retval operation completion status.
     * @return source audio source.
     */
    getAudioSource() generates (Result retval, AudioSource source);

    /**
     * Set the input gain for the audio driver.
     * Optional method
     *
     * @param gain 1.0f is unity, 0.0f is zero.
     * @result retval operation completion status.
     */
    setGain(float gain) generates (Result retval);

    /**
     * Called when the metadata of the stream's sink has been changed.
     * Optional method
     *
     * @param sinkMetadata Description of the audio that is suggested by the clients.
     * @return retval operation completion status.
     *        If any of the metadata fields contains an invalid value,
     *        returns INVALID_ARGUMENTS.
     *        If method isn't supported by the HAL returns NOT_SUPPORTED.
     */
    updateSinkMetadata(SinkMetadata sinkMetadata) generates (Result retval);

    /**
     * Commands that can be executed on the driver reader thread.
     */
    enum ReadCommand : int32_t {
        READ,
        GET_CAPTURE_POSITION
    };

    /**
     * Data structure passed to the driver for executing commands
     * on the driver reader thread.
     */
    struct ReadParameters {
        ReadCommand command;  // discriminator
        union Params {
            uint64_t read;    // READ command, amount of bytes to read, >= 0.
            // No parameters for GET_CAPTURE_POSITION.
        } params;
    };

    /**
     * Data structure passed back to the client via status message queue
     * of 'read' operation.
     *
     * Possible values of 'retval' field:
     *  - OK, read operation was successful;
     *  - INVALID_ARGUMENTS, stream was not configured properly;
     *  - INVALID_STATE, stream is in a state that doesn't allow reads.
     */
    struct ReadStatus {
        Result retval;
        ReadCommand replyTo;  // discriminator
        union Reply {
            uint64_t read;    // READ command, amount of bytes read, >= 0.
            struct CapturePosition { // same as generated by getCapturePosition.
                uint64_t frames;
                uint64_t time;
            } capturePosition;
        } reply;
    };

    /**
     * Set up required transports for receiving audio buffers from the driver.
     *
     * The transport consists of three message queues:
     *  -- command queue is used to instruct the reader thread what operation
     *     to perform;
     *  -- data queue is used for passing audio data from the driver
     *     to the client;
     *  -- status queue is used for reporting operation status
     *     (e.g. amount of bytes actually read or error code).
     *
     * The driver operates on a dedicated thread. The client must ensure that
     * the thread is given an appropriate priority and assigned to correct
     * scheduler and cgroup. For this purpose, the method returns the identifier
     * of the driver thread.
     *
     * @param frameSize the size of a single frame, in bytes.
     * @param framesCount the number of frames in a buffer.
     * @param threadPriority priority of the driver thread.
     * @return retval OK if both message queues were created successfully.
     *                INVALID_STATE if the method was already called.
     *                INVALID_ARGUMENTS if there was a problem setting up
     *                                  the queues.
     * @return commandMQ a message queue used for passing commands.
     * @return dataMQ a message queue used for passing audio data in the format
     *                specified at the stream opening.
     * @return statusMQ a message queue used for passing status from the driver
     *                  using ReadStatus structures.
     * @return threadId identifier of the driver's dedicated thread; the caller
     *                  may adjust the thread priority to match the priority
     *                  of the thread that provides audio data.
     */
    prepareForReading(uint32_t frameSize, uint32_t framesCount)
    generates (
            Result retval,
            fmq_sync<ReadParameters> commandMQ,
            fmq_sync<uint8_t> dataMQ,
            fmq_sync<ReadStatus> statusMQ,
            int32_t threadId);

    /**
     * Return the amount of input frames lost in the audio driver since the last
     * call of this function.
     *
     * Audio driver is expected to reset the value to 0 and restart counting
     * upon returning the current value by this function call. Such loss
     * typically occurs when the user space process is blocked longer than the
     * capacity of audio driver buffers.
     *
     * @return framesLost the number of input audio frames lost.
     */
    getInputFramesLost() generates (uint32_t framesLost);

    /**
     * Return a recent count of the number of audio frames received and the
     * clock time associated with that frame count.
     *
     * @return retval INVALID_STATE if the device is not ready/available,
     *                NOT_SUPPORTED if the command is not supported,
     *                OK otherwise.
     * @return frames the total frame count received. This must be as early in
     *                the capture pipeline as possible. In general, frames
     *                must be non-negative and must not go "backwards".
     * @return time is the clock monotonic time when frames was measured. In
     *              general, time must be a positive quantity and must not
     *              go "backwards".
     */
    getCapturePosition()
            generates (Result retval, uint64_t frames, uint64_t time);

    /**
     * Returns an array with active microphones in the stream.
     *
     * @return retval INVALID_STATE if the call is not successful,
     *                OK otherwise.
     *
     * @return microphones array with microphones info
     */
    getActiveMicrophones()
               generates(Result retval, vec<MicrophoneInfo> microphones);

    /**
     * Specifies the logical microphone (for processing).
     *
     * If the feature is not supported an error should be returned
     * If multiple microphones are present, this should be treated as a preference
     * for their combined direction.
     *
     * Optional method
     *
     * @param Direction constant
     * @return retval OK if the call is successful, an error code otherwise.
     */
    setMicrophoneDirection(MicrophoneDirection direction)
               generates(Result retval);

    /**
     * Specifies the zoom factor for the selected microphone (for processing).
     *
     * If the feature is not supported an error should be returned
     * If multiple microphones are present, this should be treated as a preference
     * for their combined field dimension.
     *
     * Optional method
     *
     * @param the desired field dimension of microphone capture. Range is from -1 (wide angle),
     * though 0 (no zoom) to 1 (maximum zoom).
     *
     * @return retval OK if the call is not successful, an error code otherwise.
     */
    setMicrophoneFieldDimension(float zoom) generates(Result retval);
};