/*
 * Copyright (C) 2022 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.1;

import @7.0::IDevicesFactory;
import @7.0::Result;
import IDevice;
import IPrimaryDevice;

/**
 * This factory allows a HAL implementation to be split in multiple independent
 * devices (called module in the pre-treble API). Note that this division is
 * arbitrary and implementation are free to only have a Primary. The framework
 * will query the devices according to audio_policy_configuration.xml
 *
 * Each device name is arbitrary, provided by the vendor's audio_policy_configuration.xml
 * and only used to identify a device in this factory.
 * The framework must not interpret the name, treating it as a vendor opaque data
 * with the following exception:
 * - the "r_submix" device that must be present to support policyMixes (Eg: Android projected).
 *   Note that this Device is included by default in a build derived from AOSP.
 */
interface IDevicesFactory extends @7.0::IDevicesFactory {

    /**
     * Opens an audio device. To close the device, it is necessary to call
     * 'close' method on the returned device object.
     *
     * Important note: due to rules of HIDL, @7.1::IPrimaryDevice extends
     * @7.0::IPrimaryDevice, rather than @7.1::IDevice. Thus the returned
     * IDevice interface can not be up-casted to @7.1::IPrimaryDevice for the
     * primary device. The client needs to use IPrimaryDevice instead of this
     * method if it needs full functionality of the IPrimaryDevice interface.
     *
     * @param device device name.
     * @return retval operation completion status. Returns INVALID_ARGUMENTS
     *         if there is no corresponding hardware module found,
     *         NOT_INITIALIZED if an error occurred while opening the hardware
     *         module.
     * @return result the interface for the created device.
     */
    openDevice_7_1(string device) generates (Result retval, IDevice result);

    /**
     * Opens the Primary audio device that must be present.
     * This function is not optional and must return successfully the primary device.
     *
     * This device must have the name "primary".
     *
     * The telephony stack uses this device to control the audio during a voice call.
     *
     * @return retval operation completion status. Must be SUCCESS.
     *         For debugging, return INVALID_ARGUMENTS if there is no corresponding
     *         hardware module found, NOT_INITIALIZED if an error occurred
     *         while opening the hardware module.
     * @return result the interface for the created device.
     */
    openPrimaryDevice_7_1() generates (Result retval, IPrimaryDevice result);
};