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