/*
 * 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 IStreamIn;
import IStreamOut;

interface IDevice {
    /**
     * Returns whether the audio hardware interface has been initialized.
     *
     * @return retval OK on success, NOT_INITIALIZED on failure.
     */
    initCheck() generates (Result retval);

    /**
     * Sets the audio volume for all audio activities other than voice call. If
     * NOT_SUPPORTED is returned, the software mixer will emulate this
     * capability.
     *
     * @param volume 1.0f means unity, 0.0f is zero.
     * @return retval operation completion status.
     */
    setMasterVolume(float volume) generates (Result retval);

    /**
     * Get the current master volume value for the HAL, if the HAL supports
     * master volume control. For example, AudioFlinger will query this value
     * from the primary audio HAL when the service starts and use the value for
     * setting the initial master volume across all HALs. HALs which do not
     * support this method must return NOT_SUPPORTED in 'retval'.
     *
     * @return retval operation completion status.
     * @return volume 1.0f means unity, 0.0f is zero.
     */
    getMasterVolume() generates (Result retval, float volume);

    /**
     * Sets microphone muting state.
     *
     * @param mute whether microphone is muted.
     * @return retval operation completion status.
     */
    setMicMute(bool mute) generates (Result retval);

    /**
     * Gets whether microphone is muted.
     *
     * @return retval operation completion status.
     * @return mute whether microphone is muted.
     */
    getMicMute() generates (Result retval, bool mute);

    /**
     * Set the audio mute status for all audio activities. If the return value
     * is NOT_SUPPORTED, the software mixer will emulate this capability.
     *
     * @param mute whether audio is muted.
     * @return retval operation completion status.
     */
    setMasterMute(bool mute) generates (Result retval);

    /**
     * Get the current master mute status for the HAL, if the HAL supports
     * master mute control. AudioFlinger will query this value from the primary
     * audio HAL when the service starts and use the value for setting the
     * initial master mute across all HALs. HAL must indicate that the feature
     * is not supported by returning NOT_SUPPORTED status.
     *
     * @return retval operation completion status.
     * @return mute whether audio is muted.
     */
    getMasterMute() generates (Result retval, bool mute);

    /**
     * Returns audio input buffer size according to parameters passed or
     * INVALID_ARGUMENTS if one of the parameters is not supported.
     *
     * @param config audio configuration.
     * @return retval operation completion status.
     * @return bufferSize input buffer size in bytes.
     */
    getInputBufferSize(AudioConfig config)
            generates (Result retval, uint64_t bufferSize);

    /**
     * This method creates and opens the audio hardware output stream.
     * If the stream can not be opened with the proposed audio config,
     * HAL must provide suggested values for the audio config.
     *
     * Note: INVALID_ARGUMENTS is returned both in the case when the
     * HAL can not use the provided config and in the case when
     * the value of any argument is invalid. In the latter case the
     * HAL must provide a default initialized suggested config.
     *
     * @param ioHandle handle assigned by AudioFlinger.
     * @param device device type and (if needed) address.
     * @param config stream configuration.
     * @param flags additional flags.
     * @param sourceMetadata Description of the audio that will be played.
                             May be used by implementations to configure hardware effects.
     * @return retval operation completion status.
     * @return outStream created output stream.
     * @return suggestedConfig in the case of rejection of the proposed config,
     *                         a config suggested by the HAL.
     */
    openOutputStream(
            AudioIoHandle ioHandle,
            DeviceAddress device,
            AudioConfig config,
            vec<AudioInOutFlag> flags,
            SourceMetadata sourceMetadata) generates (
                    Result retval,
                    IStreamOut outStream,
                    AudioConfig suggestedConfig);

    /**
     * This method creates and opens the audio hardware input stream.
     * If the stream can not be opened with the proposed audio config,
     * HAL must provide suggested values for the audio config.
     *
     * Note: INVALID_ARGUMENTS is returned both in the case when the
     * HAL can not use the provided config and in the case when
     * the value of any argument is invalid. In the latter case the
     * HAL must provide a default initialized suggested config.
     *
     * @param ioHandle handle assigned by AudioFlinger.
     * @param device device type and (if needed) address.
     * @param config stream configuration.
     * @param flags additional flags.
     * @param sinkMetadata Description of the audio that is suggested by the client.
     *                     May be used by implementations to configure processing effects.
     * @return retval operation completion status.
     * @return inStream in case of success, created input stream.
     * @return suggestedConfig in the case of rejection of the proposed config,
     *                         a config suggested by the HAL.
     */
    openInputStream(
            AudioIoHandle ioHandle,
            DeviceAddress device,
            AudioConfig config,
            vec<AudioInOutFlag> flags,
            SinkMetadata sinkMetadata) generates (
                    Result retval,
                    IStreamIn inStream,
                    AudioConfig suggestedConfig);

    /**
     * Returns whether HAL supports audio patches. Patch represents a connection
     * between signal source(s) and signal sink(s). If HAL doesn't support
     * patches natively (in hardware) then audio system will need to establish
     * them in software.
     *
     * @return supports true if audio patches are supported.
     */
    supportsAudioPatches() generates (bool supports);

    /**
     * Creates an audio patch between several source and sink ports.  The handle
     * is allocated by the HAL and must be unique for this audio HAL module.
     *
     * Optional method. HAL must support it if 'supportsAudioPatches' returns
     * 'true'.
     *
     * @param sources patch sources.
     * @param sinks patch sinks.
     * @return retval operation completion status.
     * @return patch created patch handle.
     */
    createAudioPatch(vec<AudioPortConfig> sources, vec<AudioPortConfig> sinks)
            generates (Result retval, AudioPatchHandle patch);

    /**
     * Updates an audio patch.
     *
     * Use of this function is preferred to releasing and re-creating a patch
     * as the HAL module can figure out a way of switching the route without
     * causing audio disruption.
     *
     * Optional method. HAL must support it if 'supportsAudioPatches' returns
     * 'true'.
     *
     * @param previousPatch handle of the previous patch to update.
     * @param sources new patch sources.
     * @param sinks new patch sinks.
     * @return retval operation completion status.
     * @return patch updated patch handle.
     */
    updateAudioPatch(
            AudioPatchHandle previousPatch,
            vec<AudioPortConfig> sources,
            vec<AudioPortConfig> sinks) generates (
                    Result retval, AudioPatchHandle patch);

    /**
     * Release an audio patch.
     *
     * Optional method. HAL must support it if 'supportsAudioPatches' returns
     * 'true'.
     *
     * @param patch patch handle.
     * @return retval operation completion status.
     */
    releaseAudioPatch(AudioPatchHandle patch) generates (Result retval);

    /**
     * Returns the list of supported attributes for a given audio port.
     *
     * As input, 'port' contains the information (type, role, address etc...)
     * needed by the HAL to identify the port.
     *
     * As output, 'resultPort' contains possible attributes (sampling rates,
     * formats, channel masks, gain controllers...) for this port.
     *
     * @param port port identifier.
     * @return retval operation completion status.
     * @return resultPort port descriptor with all parameters filled up.
     */
    getAudioPort(AudioPort port)
            generates (Result retval, AudioPort resultPort);

    /**
     * Set audio port configuration.
     *
     * @param config audio port configuration.
     * @return retval operation completion status.
     */
    setAudioPortConfig(AudioPortConfig config) generates (Result retval);

    /**
     * Gets the HW synchronization source of the device. Calling this method is
     * equivalent to getting AUDIO_PARAMETER_HW_AV_SYNC on the legacy HAL.
     *
     * Optional method
     *
     * @return retval operation completion status: OK or NOT_SUPPORTED.
     * @return hwAvSync HW synchronization source
     */
    getHwAvSync() generates (Result retval, AudioHwSync hwAvSync);

    /**
     * Sets whether the screen is on. Calling this method is equivalent to
     * setting AUDIO_PARAMETER_KEY_SCREEN_STATE on the legacy HAL.
     *
     * Optional method
     *
     * @param turnedOn whether the screen is turned on.
     * @return retval operation completion status.
     */
    setScreenState(bool turnedOn) generates (Result retval);

    /**
     * Generic method for retrieving vendor-specific parameter values.
     * The framework does not interpret the parameters, they are passed
     * in an opaque manner between a vendor application and HAL.
     *
     * Multiple parameters can be retrieved at the same time.
     * The implementation should return as many requested parameters
     * as possible, even if one or more is not supported
     *
     * @param context provides more information about the request
     * @param keys keys of the requested parameters
     * @return retval operation completion status.
     *         OK must be returned if keys is empty.
     *         NOT_SUPPORTED must be returned if at least one key is unknown.
     * @return parameters parameter key value pairs.
     *         Must contain the value of all requested keys if retval == OK
     */
    getParameters(vec<ParameterValue> context, vec<string> keys)
            generates (Result retval, vec<ParameterValue> parameters);

    /**
     * Generic method for setting vendor-specific parameter values.
     * The framework does not interpret the parameters, they are passed
     * in an opaque manner between a vendor application and HAL.
     *
     * Multiple parameters can be set at the same time though this is
     * discouraged as it make failure analysis harder.
     *
     * If possible, a failed setParameters should not impact the platform state.
     *
     * @param context provides more information about the request
     * @param parameters parameter key value pairs.
     * @return retval operation completion status.
     *         All parameters must be successfully set for OK to be returned
     */
    setParameters(vec<ParameterValue> context, vec<ParameterValue> parameters)
            generates (Result retval);

    /**
     * Returns an array with available microphones in device.
     *
     * @return retval NOT_SUPPORTED if there are no microphones on this device
     *                INVALID_STATE if the call is not successful,
     *                OK otherwise.
     *
     * @return microphones array with microphones info
     */
    getMicrophones()
         generates(Result retval, vec<MicrophoneInfo> microphones);

    /**
     * Notifies the device module about the connection state of an input/output
     * device attached to it. Calling this method is equivalent to setting
     * AUDIO_PARAMETER_DEVICE_[DIS]CONNECT on the legacy HAL.
     *
     * @param address audio device specification.
     * @param connected whether the device is connected.
     * @return retval operation completion status.
     */
    setConnectedState(DeviceAddress address, bool connected)
            generates (Result retval);

    /**
     * Called by the framework to deinitialize the device and free up
     * all currently allocated resources. It is recommended to close
     * the device on the client side as soon as it is becomes unused.
     *
     * Note that all streams must be closed by the client before
     * attempting to close the device they belong to.
     *
     * @return retval OK in case the success.
     *                INVALID_STATE if the device was already closed
     *                or there are streams currently opened.
     */
    close() generates (Result retval);

    /**
     * Applies an audio effect to an audio device. The effect is inserted
     * according to its insertion preference specified by INSERT_... EffectFlags
     * in the EffectDescriptor.
     *
     * @param device identifies the sink or source device this effect must be applied to.
     *               "device" is the AudioPortHandle indicated for the device when the audio
     *                patch connecting that device was created.
     * @param effectId effect ID (obtained from IEffectsFactory.createEffect) of
     *                 the effect to add.
     * @return retval operation completion status.
     */
    addDeviceEffect(AudioPortHandle device, uint64_t effectId) generates (Result retval);

    /**
     * Stops applying an audio effect to an audio device.
     *
     * @param device identifies the sink or source device this effect was applied to.
     *               "device" is the AudioPortHandle indicated for the device when the audio
     *               patch is created at the audio HAL.
     * @param effectId effect ID (obtained from IEffectsFactory.createEffect) of
     *                 the effect.
     * @return retval operation completion status.
     */
    removeDeviceEffect(AudioPortHandle device, uint64_t effectId) generates (Result retval);
};