1/*
2 * Copyright (C) 2020 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.0;
18
19import android.hardware.audio.common@7.0;
20import IDevice;
21import IPrimaryDevice;
22
23/** This factory allows a HAL implementation to be split in multiple independent
24 *  devices (called module in the pre-treble API).
25 *  Note that this division is arbitrary and implementation are free
26 *  to only have a Primary.
27 *  The framework will query the devices according to audio_policy_configuration.xml
28 *
29 *  Each device name is arbitrary, provided by the vendor's audio_policy_configuration.xml
30 *  and only used to identify a device in this factory.
31 *  The framework must not interpret the name, treating it as a vendor opaque data
32 *  with the following exception:
33 *  - the "r_submix" device that must be present to support policyMixes (Eg: Android projected).
34 *    Note that this Device is included by default in a build derived from AOSP.
35 *
36 *  Note that on AOSP Oreo (including MR1) the "a2dp" module is not using this API
37 *  but is loaded directly from the system partition using the legacy API
38 *  due to limitations with the Bluetooth framework.
39 */
40interface IDevicesFactory {
41
42    /**
43     * Opens an audio device. To close the device, it is necessary to release
44     * references to the returned device object.
45     *
46     * @param device device name.
47     * @return retval operation completion status. Returns INVALID_ARGUMENTS
48     *         if there is no corresponding hardware module found,
49     *         NOT_INITIALIZED if an error occurred while opening the hardware
50     *         module.
51     * @return result the interface for the created device.
52     */
53    openDevice(string device) generates (Result retval, IDevice result);
54
55    /**
56     * Opens the Primary audio device that must be present.
57     * This function is not optional and must return successfully the primary device.
58     *
59     * This device must have the name "primary".
60     *
61     * The telephony stack uses this device to control the audio during a voice call.
62     *
63     * @return retval operation completion status. Must be SUCCESS.
64     *         For debugging, return INVALID_ARGUMENTS if there is no corresponding
65     *         hardware module found, NOT_INITIALIZED if an error occurred
66     *         while opening the hardware module.
67     * @return result the interface for the created device.
68     */
69    openPrimaryDevice() generates (Result retval, IPrimaryDevice result);
70};
71