/* * Copyright (C) 2018 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.hardware.media.c2@1.0; /** * Generic configuration interface presented by all configurable Codec2 objects. * * This interface must be supported in all states of the owning object, and must * not change the state of the owning object. */ interface IConfigurable { /** * Returns the id of the object. This must be unique among all objects of * the same type hosted by the same store. * * @return id Id of the object. */ getId() generates (uint32_t id); /** * Returns the name of the object. * * This must match the name that was supplied during the creation of the * object. * * @return name Name of the object. */ getName() generates (string name); /** * Queries a set of parameters from the object. * * Querying is performed at best effort: the object must query all supported * parameters and skip unsupported ones (which may include parameters that * could not be allocated). Any errors are communicated in the return value. * * If @p mayBlock is false, this method must not block. All parameter * queries that require blocking must be skipped. * * If @p mayBlock is true, a query may block, but the whole method call * has to complete in a timely manner, or `status = TIMED_OUT` is returned. * * If @p mayBlock is false, this method must not block. Otherwise, this * method is allowed to block for a certain period of time before completing * the operation. If the operation is not completed in a timely manner, * `status = TIMED_OUT` is returned. * * @note The order of C2Param objects in @p param does not depend on the * order of C2Param structure indices in @p indices. * * \par For IComponent * * When the object type is @ref IComponent, this method must be supported in * any state except released. This call must not change the state nor the * internal configuration of the component. * * The blocking behavior of this method differs among states: * - In the stopped state, this must be non-blocking. @p mayBlock is * ignored. (The method operates as if @p mayBlock was false.) * - In any of the running states, this method may block momentarily if * @p mayBlock is true. However, if the call cannot be completed in a * timely manner, `status = TIMED_OUT` is returned. * * @param indices List of C2Param structure indices to query. * @param mayBlock Whether this call may block or not. * @return status Status of the call, which may be * - `OK` - All parameters could be queried. * - `BAD_INDEX` - All supported parameters could be queried, but some * parameters were not supported. * - `NO_MEMORY` - Could not allocate memory for a supported parameter. * - `BLOCKING` - Querying some parameters requires blocking, but * @p mayBlock is false. * - `TIMED_OUT` - The operation cannot be finished in a timely manner. * - `CORRUPTED` - Some unknown error occurred. * @return params Flattened representation of C2Param objects. * * @sa Params. */ query( vec indices, bool mayBlock ) generates ( Status status, Params params ); /** * Sets a set of parameters for the object. * * Tuning is performed at best effort: the object must update all supported * configurations at best effort and skip unsupported parameters. Any errors * are communicated in the return value and in @p failures. * * A non-strict parameter update with an unsupported value shall cause an * update to the closest supported value. A strict parameter update with an * unsupported value shall be skipped and a failure shall be returned. * * If @p mayBlock is false, this method must not block. An update that * requires blocking shall be skipped and a failure shall be returned. * * If @p mayBlock is true, an update may block, but the whole method call * has to complete in a timely manner, or `status = TIMED_OUT` is returned. * * The final values for all parameters set are propagated back to the caller * in @p params. * * \par For IComponent * * When the object type is @ref IComponent, this method must be supported in * any state except released. * * The blocking behavior of this method differs among states: * - In the stopped state, this must be non-blocking. @p mayBlock is * ignored. (The method operates as if @p mayBlock was false.) * - In any of the running states, this method may block momentarily if * @p mayBlock is true. However, if the call cannot be completed in a * timely manner, `status = TIMED_OUT` is returned. * * @note Parameter tuning @e does depend on the order of the tuning * parameters, e.g., some parameter update may enable some subsequent * parameter update. * * @param inParams Requested parameter updates. * @param mayBlock Whether this call may block or not. * @return status Status of the call, which may be * - `OK` - All parameters could be updated successfully. * - `BAD_INDEX` - All supported parameters could be updated successfully, * but some parameters were not supported. * - `NO_MEMORY` - Some supported parameters could not be updated * successfully because they contained unsupported values. * These are returned in @p failures. * - `BLOCKING` - Setting some parameters requires blocking, but * @p mayBlock is false. * - `TIMED_OUT` - The operation cannot be finished in a timely manner. * - `CORRUPTED` - Some unknown error occurred. * @return failures List of update failures. * @return outParams Flattened representation of configured parameters. The * order of parameters in @p outParams is based on the order of * requested updates in @p inParams. * * @sa SettingResult. */ config( Params inParams, bool mayBlock ) generates ( Status status, vec failures, Params outParams ); // REFLECTION MECHANISM // ========================================================================= /** * Returns a list of supported parameters within a selected range of C2Param * structure indices. * * @param start The first index of the selected range. * @param count The length of the selected range. * @return status Status of the call, which may be * - `OK` - The operation completed successfully. * - `NO_MEMORY` - Not enough memory to complete this method. * @return params List of supported parameters in the selected range. This * list may have fewer than @p count elements if some indices in the * range are not supported. * * @sa ParamDescriptor. */ querySupportedParams( uint32_t start, uint32_t count ) generates ( Status status, vec params ); /** * Retrieves the supported values for the queried fields. * * The object must process all fields queried even if some queries fail. * * If @p mayBlock is false, this method must not block. Otherwise, this * method is allowed to block for a certain period of time before completing * the operation. If the operation cannot be completed in a timely manner, * `status = TIMED_OUT` is returned. * * \par For IComponent * * When the object type is @ref IComponent, this method must be supported in * any state except released. * * The blocking behavior of this method differs among states: * - In the stopped state, this must be non-blocking. @p mayBlock is * ignored. (The method operates as if @p mayBlock was false.) * - In any of the running states, this method may block momentarily if * @p mayBlock is true. However, if the call cannot be completed in a * timely manner, `status = TIMED_OUT` is returned. * * @param inFields List of field queries. * @param mayBlock Whether this call may block or not. * @return status Status of the call, which may be * - `OK` - The operation completed successfully. * - `BLOCKING` - Querying some parameters requires blocking, but * @p mayBlock is false. * - `NO_MEMORY` - Not enough memory to complete this method. * - `BAD_INDEX` - At least one field was not recognized as a component * field. * - `BLOCKING` - Querying some fields requires blocking, but @p mayblock * is false. * - `TIMED_OUT` - The operation cannot be finished in a timely manner. * - `CORRUPTED` - Some unknown error occurred. * @return outFields List of supported values and results for the * supplied queries. * * @sa FieldSupportedValuesQuery, FieldSupportedValuesQueryResult. */ querySupportedValues( vec inFields, bool mayBlock ) generates ( Status status, vec outFields ); };