1/*
2 * Copyright (C) 2022 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.audio@7.1;
18
19import @7.0::IDevicesFactory;
20import @7.0::Result;
21import IDevice;
22import IPrimaryDevice;
23
24/**
25 * This factory allows a HAL implementation to be split in multiple independent
26 * devices (called module in the pre-treble API). Note that this division is
27 * arbitrary and implementation are free to only have a Primary. The framework
28 * will query the devices according to audio_policy_configuration.xml
29 *
30 * Each device name is arbitrary, provided by the vendor's audio_policy_configuration.xml
31 * and only used to identify a device in this factory.
32 * The framework must not interpret the name, treating it as a vendor opaque data
33 * with the following exception:
34 * - the "r_submix" device that must be present to support policyMixes (Eg: Android projected).
35 *   Note that this Device is included by default in a build derived from AOSP.
36 */
37interface IDevicesFactory extends @7.0::IDevicesFactory {
38
39    /**
40     * Opens an audio device. To close the device, it is necessary to call
41     * 'close' method on the returned device object.
42     *
43     * Important note: due to rules of HIDL, @7.1::IPrimaryDevice extends
44     * @7.0::IPrimaryDevice, rather than @7.1::IDevice. Thus the returned
45     * IDevice interface can not be up-casted to @7.1::IPrimaryDevice for the
46     * primary device. The client needs to use IPrimaryDevice instead of this
47     * method if it needs full functionality of the IPrimaryDevice interface.
48     *
49     * @param device device name.
50     * @return retval operation completion status. Returns INVALID_ARGUMENTS
51     *         if there is no corresponding hardware module found,
52     *         NOT_INITIALIZED if an error occurred while opening the hardware
53     *         module.
54     * @return result the interface for the created device.
55     */
56    openDevice_7_1(string device) generates (Result retval, IDevice result);
57
58    /**
59     * Opens the Primary audio device that must be present.
60     * This function is not optional and must return successfully the primary device.
61     *
62     * This device must have the name "primary".
63     *
64     * The telephony stack uses this device to control the audio during a voice call.
65     *
66     * @return retval operation completion status. Must be SUCCESS.
67     *         For debugging, return INVALID_ARGUMENTS if there is no corresponding
68     *         hardware module found, NOT_INITIALIZED if an error occurred
69     *         while opening the hardware module.
70     * @return result the interface for the created device.
71     */
72    openPrimaryDevice_7_1() generates (Result retval, IPrimaryDevice result);
73};
74