/*
 * 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 hardware.google.media.c2@1.0;

/**
 * Generic configuration interface used by all configurable Codec 2.0
 * components.
 *
 * This interface must be supported in all states of the inheriting
 * object, and must not change the state of the inheriting object.
 */
interface IConfigurable {
    /**
     * Returns the name of this object. This must match the name that was
     * supplied during the creation of the object.
     *
     * @return name Name of this 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, or parameters that could not be allocated. Any errors
     * are communicated in the return value.
     *
     * \note Parameter values do not depend on the order of query.
     *
     * This method must return within 1ms if \p mayBlock is DONT_BLOCK, and
     * within 5ms otherwise.
     *
     * @param indices List of param indices for params to be queried.
     * @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.
     *   - CORRUPTED - Some unknown error prevented the querying of the
     *                 parameters. (unexpected)
     * @return params List of params queried corresponding to \p indices.
     */
    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 configuration at best
     * effort and skip unsupported parameters. Any errors are communicated in
     * the return value and in \p failures.
     *
     * \note Parameter tuning DOES depend on the order of the tuning parameters.
     * E.g. some parameter update may allow some subsequent parameter update.
     *
     * This method must return within 1ms if \p mayBlock is false, and within
     * 5ms otherwise.
     *
     * @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.
     *   - CORRUPTED - Some unknown error prevented the update of the
     *                 parameters. (unexpected)
     * @return failures List of parameter failures.
     * @return outParams Resulting values for the configured parameters.
     */
    config(
            Params inParams,
            bool mayBlock
        ) generates (
            Status status,
            vec<SettingResult> failures,
            Params outParams
        );

    // REFLECTION MECHANISM
    // =========================================================================

    /**
     * Returns a selected range of the set of supported parameters.
     *
     * The set of supported parameters are represented in a vector with a
     * start index of 0, and the selected range are indices into this vector.
     * Fewer than \p count parameters are returned if the selected range is
     * not fully/not at all part of the available vector indices.
     *
     * This method must return within 1ms.
     *
     * @param start start index of selected range
     * @param count size of the selected
     * @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 Vector containing the selected range of supported
     *     parameters.
     */
    querySupportedParams(
            uint32_t start,
            uint32_t count
        ) generates (
            Status status,
            vec<ParamDescriptor> params
        );

    /**
     * Retrieves the supported values for the queried fields.
     *
     * Upon return the object must fill in the supported
     * values for the fields listed as well as a status for each field.
     * Object shall process all fields queried even if some queries fail.
     *
     * This method must return within 1ms if \p mayBlock is false, and within
     * 5ms otherwise.
     *
     * @param inFields Vector 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.
     *   - NO_MEMORY - Not enough memory to complete this method.
     *   - BAD_INDEX - At least one field was not recognized as a component
     *                 field.
     * @return outFields Vector containing supported values and query result
     *     for the selected fields.
     */
    querySupportedValues(
            vec<FieldSupportedValuesQuery> inFields,
            bool mayBlock
        ) generates (
            Status status,
            vec<FieldSupportedValuesQueryResult> outFields
        );

};