1/* 2 * Copyright (C) 2018 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.media.c2@1.0; 18 19/** 20 * Generic configuration interface presented by all configurable Codec2 objects. 21 * 22 * This interface must be supported in all states of the owning object, and must 23 * not change the state of the owning object. 24 */ 25interface IConfigurable { 26 /** 27 * Returns the id of the object. This must be unique among all objects of 28 * the same type hosted by the same store. 29 * 30 * @return id Id of the object. 31 */ 32 getId() generates (uint32_t id); 33 34 /** 35 * Returns the name of the object. 36 * 37 * This must match the name that was supplied during the creation of the 38 * object. 39 * 40 * @return name Name of the object. 41 */ 42 getName() generates (string name); 43 44 /** 45 * Queries a set of parameters from the object. 46 * 47 * Querying is performed at best effort: the object must query all supported 48 * parameters and skip unsupported ones (which may include parameters that 49 * could not be allocated). Any errors are communicated in the return value. 50 * 51 * If @p mayBlock is false, this method must not block. All parameter 52 * queries that require blocking must be skipped. 53 * 54 * If @p mayBlock is true, a query may block, but the whole method call 55 * has to complete in a timely manner, or `status = TIMED_OUT` is returned. 56 * 57 * If @p mayBlock is false, this method must not block. Otherwise, this 58 * method is allowed to block for a certain period of time before completing 59 * the operation. If the operation is not completed in a timely manner, 60 * `status = TIMED_OUT` is returned. 61 * 62 * @note The order of C2Param objects in @p param does not depend on the 63 * order of C2Param structure indices in @p indices. 64 * 65 * \par For IComponent 66 * 67 * When the object type is @ref IComponent, this method must be supported in 68 * any state except released. This call must not change the state nor the 69 * internal configuration of the component. 70 * 71 * The blocking behavior of this method differs among states: 72 * - In the stopped state, this must be non-blocking. @p mayBlock is 73 * ignored. (The method operates as if @p mayBlock was false.) 74 * - In any of the running states, this method may block momentarily if 75 * @p mayBlock is true. However, if the call cannot be completed in a 76 * timely manner, `status = TIMED_OUT` is returned. 77 * 78 * @param indices List of C2Param structure indices to query. 79 * @param mayBlock Whether this call may block or not. 80 * @return status Status of the call, which may be 81 * - `OK` - All parameters could be queried. 82 * - `BAD_INDEX` - All supported parameters could be queried, but some 83 * parameters were not supported. 84 * - `NO_MEMORY` - Could not allocate memory for a supported parameter. 85 * - `BLOCKING` - Querying some parameters requires blocking, but 86 * @p mayBlock is false. 87 * - `TIMED_OUT` - The operation cannot be finished in a timely manner. 88 * - `CORRUPTED` - Some unknown error occurred. 89 * @return params Flattened representation of C2Param objects. 90 * 91 * @sa Params. 92 */ 93 query( 94 vec<ParamIndex> indices, 95 bool mayBlock 96 ) generates ( 97 Status status, 98 Params params 99 ); 100 101 /** 102 * Sets a set of parameters for the object. 103 * 104 * Tuning is performed at best effort: the object must update all supported 105 * configurations at best effort and skip unsupported parameters. Any errors 106 * are communicated in the return value and in @p failures. 107 * 108 * A non-strict parameter update with an unsupported value shall cause an 109 * update to the closest supported value. A strict parameter update with an 110 * unsupported value shall be skipped and a failure shall be returned. 111 * 112 * If @p mayBlock is false, this method must not block. An update that 113 * requires blocking shall be skipped and a failure shall be returned. 114 * 115 * If @p mayBlock is true, an update may block, but the whole method call 116 * has to complete in a timely manner, or `status = TIMED_OUT` is returned. 117 * 118 * The final values for all parameters set are propagated back to the caller 119 * in @p params. 120 * 121 * \par For IComponent 122 * 123 * When the object type is @ref IComponent, this method must be supported in 124 * any state except released. 125 * 126 * The blocking behavior of this method differs among states: 127 * - In the stopped state, this must be non-blocking. @p mayBlock is 128 * ignored. (The method operates as if @p mayBlock was false.) 129 * - In any of the running states, this method may block momentarily if 130 * @p mayBlock is true. However, if the call cannot be completed in a 131 * timely manner, `status = TIMED_OUT` is returned. 132 * 133 * @note Parameter tuning @e does depend on the order of the tuning 134 * parameters, e.g., some parameter update may enable some subsequent 135 * parameter update. 136 * 137 * @param inParams Requested parameter updates. 138 * @param mayBlock Whether this call may block or not. 139 * @return status Status of the call, which may be 140 * - `OK` - All parameters could be updated successfully. 141 * - `BAD_INDEX` - All supported parameters could be updated successfully, 142 * but some parameters were not supported. 143 * - `NO_MEMORY` - Some supported parameters could not be updated 144 * successfully because they contained unsupported values. 145 * These are returned in @p failures. 146 * - `BLOCKING` - Setting some parameters requires blocking, but 147 * @p mayBlock is false. 148 * - `TIMED_OUT` - The operation cannot be finished in a timely manner. 149 * - `CORRUPTED` - Some unknown error occurred. 150 * @return failures List of update failures. 151 * @return outParams Flattened representation of configured parameters. The 152 * order of parameters in @p outParams is based on the order of 153 * requested updates in @p inParams. 154 * 155 * @sa SettingResult. 156 */ 157 config( 158 Params inParams, 159 bool mayBlock 160 ) generates ( 161 Status status, 162 vec<SettingResult> failures, 163 Params outParams 164 ); 165 166 // REFLECTION MECHANISM 167 // ========================================================================= 168 169 /** 170 * Returns a list of supported parameters within a selected range of C2Param 171 * structure indices. 172 * 173 * @param start The first index of the selected range. 174 * @param count The length of the selected range. 175 * @return status Status of the call, which may be 176 * - `OK` - The operation completed successfully. 177 * - `NO_MEMORY` - Not enough memory to complete this method. 178 * @return params List of supported parameters in the selected range. This 179 * list may have fewer than @p count elements if some indices in the 180 * range are not supported. 181 * 182 * @sa ParamDescriptor. 183 */ 184 querySupportedParams( 185 uint32_t start, 186 uint32_t count 187 ) generates ( 188 Status status, 189 vec<ParamDescriptor> params 190 ); 191 192 /** 193 * Retrieves the supported values for the queried fields. 194 * 195 * The object must process all fields queried even if some queries fail. 196 * 197 * If @p mayBlock is false, this method must not block. Otherwise, this 198 * method is allowed to block for a certain period of time before completing 199 * the operation. If the operation cannot be completed in a timely manner, 200 * `status = TIMED_OUT` is returned. 201 * 202 * \par For IComponent 203 * 204 * When the object type is @ref IComponent, this method must be supported in 205 * any state except released. 206 * 207 * The blocking behavior of this method differs among states: 208 * - In the stopped state, this must be non-blocking. @p mayBlock is 209 * ignored. (The method operates as if @p mayBlock was false.) 210 * - In any of the running states, this method may block momentarily if 211 * @p mayBlock is true. However, if the call cannot be completed in a 212 * timely manner, `status = TIMED_OUT` is returned. 213 * 214 * @param inFields List of field queries. 215 * @param mayBlock Whether this call may block or not. 216 * @return status Status of the call, which may be 217 * - `OK` - The operation completed successfully. 218 * - `BLOCKING` - Querying some parameters requires blocking, but 219 * @p mayBlock is false. 220 * - `NO_MEMORY` - Not enough memory to complete this method. 221 * - `BAD_INDEX` - At least one field was not recognized as a component 222 * field. 223 * - `BLOCKING` - Querying some fields requires blocking, but @p mayblock 224 * is false. 225 * - `TIMED_OUT` - The operation cannot be finished in a timely manner. 226 * - `CORRUPTED` - Some unknown error occurred. 227 * @return outFields List of supported values and results for the 228 * supplied queries. 229 * 230 * @sa FieldSupportedValuesQuery, FieldSupportedValuesQueryResult. 231 */ 232 querySupportedValues( 233 vec<FieldSupportedValuesQuery> inFields, 234 bool mayBlock 235 ) generates ( 236 Status status, 237 vec<FieldSupportedValuesQueryResult> outFields 238 ); 239 240}; 241 242