/*
 * 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<ParamIndex> 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<SettingResult> 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<ParamDescriptor> 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<FieldSupportedValuesQuery> inFields,
            bool mayBlock
        ) generates (
            Status status,
            vec<FieldSupportedValuesQueryResult> outFields
        );

};