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 [email protected]; 18 19/** 20 * Generic configuration interface used by all configurable Codec 2.0 21 * components. 22 * 23 * This interface must be supported in all states of the inheriting 24 * object, and must not change the state of the inheriting object. 25 */ 26interface IConfigurable { 27 /** 28 * Returns the name of this object. This must match the name that was 29 * supplied during the creation of the object. 30 * 31 * @return name Name of this object. 32 */ 33 getName() generates (string name); 34 35 /** 36 * Queries a set of parameters from the object. Querying is performed at 37 * best effort: the object must query all supported parameters and skip 38 * unsupported ones, or parameters that could not be allocated. Any errors 39 * are communicated in the return value. 40 * 41 * \note Parameter values do not depend on the order of query. 42 * 43 * This method must return within 1ms if \p mayBlock is DONT_BLOCK, and 44 * within 5ms otherwise. 45 * 46 * @param indices List of param indices for params to be queried. 47 * @param mayBlock Whether this call may block or not. 48 * @return status Status of the call, which may be 49 * - OK - All parameters could be queried. 50 * - BAD_INDEX - All supported parameters could be queried, but some 51 * parameters were not supported. 52 * - NO_MEMORY - Could not allocate memory for a supported parameter. 53 * - BLOCKING - Querying some parameters requires blocking. 54 * - CORRUPTED - Some unknown error prevented the querying of the 55 * parameters. (unexpected) 56 * @return params List of params queried corresponding to \p indices. 57 */ 58 query( 59 vec<ParamIndex> indices, 60 bool mayBlock 61 ) generates ( 62 Status status, 63 Params params 64 ); 65 66 /** 67 * Sets a set of parameters for the object. Tuning is performed at best 68 * effort: the object must update all supported configuration at best 69 * effort and skip unsupported parameters. Any errors are communicated in 70 * the return value and in \p failures. 71 * 72 * \note Parameter tuning DOES depend on the order of the tuning parameters. 73 * E.g. some parameter update may allow some subsequent parameter update. 74 * 75 * This method must return within 1ms if \p mayBlock is false, and within 76 * 5ms otherwise. 77 * 78 * @param inParams Requested parameter updates. 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 updated successfully. 82 * - BAD_INDEX - All supported parameters could be updated successfully, 83 * but some parameters were not supported. 84 * - NO_MEMORY - Some supported parameters could not be updated 85 * successfully because they contained unsupported values. 86 * These are returned in \p failures. 87 * - BLOCKING - Setting some parameters requires blocking. 88 * - CORRUPTED - Some unknown error prevented the update of the 89 * parameters. (unexpected) 90 * @return failures List of parameter failures. 91 * @return outParams Resulting values for the configured parameters. 92 */ 93 config( 94 Params inParams, 95 bool mayBlock 96 ) generates ( 97 Status status, 98 vec<SettingResult> failures, 99 Params outParams 100 ); 101 102 // REFLECTION MECHANISM 103 // ========================================================================= 104 105 /** 106 * Returns a selected range of the set of supported parameters. 107 * 108 * The set of supported parameters are represented in a vector with a 109 * start index of 0, and the selected range are indices into this vector. 110 * Fewer than \p count parameters are returned if the selected range is 111 * not fully/not at all part of the available vector indices. 112 * 113 * This method must return within 1ms. 114 * 115 * @param start start index of selected range 116 * @param count size of the selected 117 * @return status Status of the call, which may be 118 * - OK - The operation completed successfully. 119 * - NO_MEMORY - Not enough memory to complete this method. 120 * @return params Vector containing the selected range of supported 121 * parameters. 122 */ 123 querySupportedParams( 124 uint32_t start, 125 uint32_t count 126 ) generates ( 127 Status status, 128 vec<ParamDescriptor> params 129 ); 130 131 /** 132 * Retrieves the supported values for the queried fields. 133 * 134 * Upon return the object must fill in the supported 135 * values for the fields listed as well as a status for each field. 136 * Object shall process all fields queried even if some queries fail. 137 * 138 * This method must return within 1ms if \p mayBlock is false, and within 139 * 5ms otherwise. 140 * 141 * @param inFields Vector of field queries. 142 * @param mayBlock Whether this call may block or not. 143 * @return status Status of the call, which may be 144 * - OK - The operation completed successfully. 145 * - BLOCKING - Querying some parameters requires blocking. 146 * - NO_MEMORY - Not enough memory to complete this method. 147 * - BAD_INDEX - At least one field was not recognized as a component 148 * field. 149 * @return outFields Vector containing supported values and query result 150 * for the selected fields. 151 */ 152 querySupportedValues( 153 vec<FieldSupportedValuesQuery> inFields, 154 bool mayBlock 155 ) generates ( 156 Status status, 157 vec<FieldSupportedValuesQueryResult> outFields 158 ); 159 160}; 161 162