soundtrigger/2.3/ISoundTriggerHw.hal

/*
 * Copyright 2019 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.soundtrigger@2.3;

import @2.0::SoundModelHandle;
import @2.2::ISoundTriggerHw;

/**
 * SoundTrigger HAL interface. Used for hardware recognition of hotwords
 * and other sounds.
 */
interface ISoundTriggerHw extends @2.2::ISoundTriggerHw {

    /**
     * Retrieve extended implementation properties.
     * The returned properties includes what is returned from the
     * getProperties along with expanded implementation details.
     *
     * @return retval Operation completion status: 0 in case of success,
     *                -ENODEV in case of initialization error.
     * @return properties A Properties structure containing implementation
     *                    description and capabilities.
     */
    getProperties_2_3() generates (int32_t retval, Properties properties);

    /**
     * Set a model specific parameter with the given value. This parameter
     * will keep its value for the duration the model is loaded regardless of starting and stopping
     * recognition. Once the model is unloaded, the value will be lost.
     * It is expected to check if the handle supports the parameter via the queryParameter
     * API prior to calling this method.
     *
     * @param modelHandle The sound model handle indicating which model to modify parameters
     * @param modelParam Parameter to set which will be validated against the
     *                   ModelParameter type. Not putting ModelParameter type
     *                   directly in the definition and validating internally
     *                   allows for forward compatibility.
     * @param value The value to set for the given model parameter
     * @return status Operation completion status: 0 in case of success,
     *                -ENODEV if the native service cannot be reached
     *                -EINVAL invalid input parameter
     */
    setParameter(SoundModelHandle modelHandle, ModelParameter modelParam, int32_t value)
            generates (int32_t status);

    /**
     * Get a model specific parameter. This parameter will keep its value
     * for the duration the model is loaded regardless of starting and stopping recognition.
     * Once the model is unloaded, the value will be lost. If the value is not set, a default
     * value is returned. See ModelParameter for parameter default values.
     * It is expected to check if the handle supports the parameter via the queryParameter
     * API prior to calling this method.
     *
     * @param modelHandle The sound model associated with given modelParam
     * @param modelParam Parameter to set which will be validated against the
     *                   ModelParameter type. Not putting ModelParameter type
     *                   directly in the definition and validating internally
     *                   allows for forward compatibility.
     * @return status Operation completion status: 0 in case of success,
     *                -ENODEV if the native service cannot be reached
     *                -EINVAL invalid input parameter
     * @return value Value set to the requested parameter. Value is only set when status
     *                indicates success.
     */
    getParameter(SoundModelHandle modelHandle, ModelParameter modelParam)
            generates (int32_t status, int32_t value);

    /**
     * Get supported parameter attributes with respect to the provided model
     * handle. Along with determining the valid range, this API is also used
     * to determine if a given parameter ID is supported at all by the
     * modelHandle for use with getParameter and setParameter APIs.
     *
     * @param modelHandle The sound model handle indicating which model to query
     * @param modelParam Parameter to set which will be validated against the
     *                   ModelParameter type
     * @return status Operation completion status: 0 in case of success
     *                -ENODEV if the native service cannot be reached
     *                -EINVAL invalid input parameter
     * @return retval ModelParameter structure indicating supported attributes
     *                of the parameter for the given model handle
     */
    queryParameter(SoundModelHandle modelHandle, ModelParameter modelParam)
            generates (int32_t status, OptionalModelParameterRange retval);
};