1 /*
2  * Copyright (C) 2023 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 
17 package android.media.audio;
18 
19 import android.hardware.audio.core.VendorParameter;
20 
21 /**
22  * This interface is used by the HAL adapter of the Audio Server. Implementation
23  * is optional. Vendors may provide an implementation on the system_ext
24  * partition. The default instance of this interface, if provided, must be
25  * registered prior to the moment when the audio server connects to HAL modules.
26  * Vendors need to set the system property `ro.audio.ihaladaptervendorextension_enabled`
27  * to `true` for the framework to bind to this service.
28  *
29  * {@hide}
30  */
31 interface IHalAdapterVendorExtension {
32     enum ParameterScope {
33         MODULE = 0,
34         STREAM = 1,
35     }
36 
37     /**
38      * Parse raw parameter keys into vendor parameter ids.
39      *
40      * This method prepares arguments for a call to the 'getVendorParameters'
41      * method of an 'IModule' or an 'IStreamCommon' interface instance,
42      * depending on the provided scope.
43      *
44      * The client calls this method in order to prepare arguments for a call to
45      * the particular Core HAL interface. The result returned by the HAL is then
46      * processed using the 'processVendorParameters' method. It is not required
47      * to maintain a 1:1 correspondence between the provided raw keys and the
48      * elements of the parsed result. If the returned list is empty, the call of
49      * 'getVendorParameters' is skipped. The implementation can either ignore
50      * keys which it does not recognize, or throw an error. The latter is
51      * preferred as it can help in discovering malformed key names.
52      *
53      * @param scope The scope of all raw parameter keys.
54      * @param rawKeys Raw parameter keys, joined into a string using a semicolon
55      *                (';') as the delimiter.
56      * @return A list of vendor parameter IDs, see android.hardware.audio.core.VendorParameter.
57      * @throws EX_ILLEGAL_ARGUMENT If the implementation can not parse the raw keys
58      *                             and prefers to signal an error.
59      */
parseVendorParameterIds( ParameterScope scope, in @utf8InCpp String rawKeys)60     @utf8InCpp String[] parseVendorParameterIds(
61             ParameterScope scope, in @utf8InCpp String rawKeys);
62 
63     /**
64      * Parse raw parameter key-value pairs into vendor parameters.
65      *
66      * This method prepares arguments for a call to the 'setVendorParameters'
67      * method of an 'IModule' or an 'IStreamCommon' interface instance,
68      * depending on the provided scope.
69      *
70      * The vendor parameters returned using 'syncParameters' argument is then
71      * used to call the 'setVendorParameters' method with 'async = false', and
72      * 'asyncParameters' is used in a subsequent call to the same method, but
73      * with 'async = true'. It is not required to maintain a 1:1 correspondence
74      * between the provided key-value pairs and the elements of parsed
75      * results. If any of the returned lists of vendor parameters is empty, then
76      * the corresponding call is skipped. The implementation can either ignore
77      * keys which it does not recognize, and invalid values, or throw an
78      * error. The latter is preferred as it can help in discovering malformed
79      * key names and values.
80      *
81      * @param scope The scope of all raw key-value pairs.
82      * @param rawKeys Raw key-value pairs, separated by the "equals" sign ('='),
83      *                joined into a string using a semicolon (';') as the delimiter.
84      * @param syncParameters A list of vendor parameters to be set synchronously.
85      * @param asyncParameters A list of vendor parameters to be set asynchronously.
86      * @throws EX_ILLEGAL_ARGUMENT If the implementation can not parse raw key-value
87      *                             pairs and prefers to signal an error.
88      */
parseVendorParameters( ParameterScope scope, in @utf8InCpp String rawKeysAndValues, out VendorParameter[] syncParameters, out VendorParameter[] asyncParameters)89     void parseVendorParameters(
90             ParameterScope scope, in @utf8InCpp String rawKeysAndValues,
91             out VendorParameter[] syncParameters, out VendorParameter[] asyncParameters);
92 
93     /**
94      * Parse raw value of the parameter for BT A2DP reconfiguration.
95      *
96      * This method may return any number of vendor parameters (including zero)
97      * which will be passed to the 'IBluetoothA2dp.reconfigureOffload' method.
98      *
99      * @param rawValue An unparsed value of the legacy parameter.
100      * @return A list of vendor parameters.
101      * @throws EX_ILLEGAL_ARGUMENT If the implementation can not parse the raw value.
102      */
parseBluetoothA2dpReconfigureOffload(in @tf8InCpp String rawValue)103     VendorParameter[] parseBluetoothA2dpReconfigureOffload(in @utf8InCpp String rawValue);
104 
105     /**
106      * Parse raw value of the parameter for BT LE reconfiguration.
107      *
108      * This method may return any number of vendor parameters (including zero)
109      * which will be passed to the 'IBluetoothLe.reconfigureOffload' method.
110      *
111      * @param rawValue An unparsed value of the legacy parameter.
112      * @return A list of vendor parameters.
113      * @throws EX_ILLEGAL_ARGUMENT If the implementation can not parse the raw value.
114      */
parseBluetoothLeReconfigureOffload(in @tf8InCpp String rawValue)115     VendorParameter[] parseBluetoothLeReconfigureOffload(in @utf8InCpp String rawValue);
116 
117     /**
118      * Process vendor parameters returned by the Audio Core HAL.
119      *
120      * This processes the result returned from a call to the
121      * 'getVendorParameters' method of an 'IModule' or an 'IStreamCommon'
122      * interface instance, depending on the provided scope.
123      *
124      * See 'parseVendorParameterIds' method for the flow description.  It is not
125      * required to maintain a 1:1 correspondence between the elements of the
126      * provided list and the emitted key-value pairs. The returned string with
127      * raw key-value pairs is passed back to the framework.
128      *
129      * @param scope The scope of vendor parameters.
130      * @param parameters Vendor parameters, see android.hardware.audio.core.VendorParameter.
131      * @return Key-value pairs, separated by the "equals" sign ('='),
132      *         joined into a string using a semicolon (';') as the delimiter.
133      * @throws EX_ILLEGAL_ARGUMENT If the implementation can not emit raw key-value
134      *                             pairs and prefers to signal an error.
135      */
processVendorParameters( ParameterScope scope, in VendorParameter[] parameters)136     @utf8InCpp String processVendorParameters(
137             ParameterScope scope, in VendorParameter[] parameters);
138 }
139