/*
 * Copyright 2017 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.1;

import @2.0::ISoundTriggerHw;
import @2.0::ISoundTriggerHwCallback.CallbackCookie;
import @2.0::SoundModelHandle;

import ISoundTriggerHwCallback;

/**
 * SoundTrigger HAL interface. Used for hardware recognition of hotwords.
 */
interface ISoundTriggerHw extends @2.0::ISoundTriggerHw {

    /**
     * Base sound model descriptor. This struct is the header of a larger block
     * passed to loadSoundModel_2_1() and contains the binary data of the
     * sound model.
     */
    struct SoundModel {
        /** Sound model header. Any data contained in the 'header.data' field
         * is ignored */
        @2.0::ISoundTriggerHw.SoundModel header;
        /** Opaque data transparent to Android framework */
        memory data;
    };

    /**
     * Specialized sound model for key phrase detection.
     * Proprietary representation of key phrases in binary data must match
     * information indicated by phrases field.
     */
    struct PhraseSoundModel {
        /** Common part of sound model descriptor */
        SoundModel  common;
        /** List of descriptors for key phrases supported by this sound model */
        vec<Phrase> phrases;
    };

    /**
     * Configuration for sound trigger capture session passed to
     * startRecognition_2_1() method.
     */
    struct RecognitionConfig {
        /** Configuration header. Any data contained in the 'header.data' field
         * is ignored */
        @2.0::ISoundTriggerHw.RecognitionConfig header;
        /** Opaque capture configuration data transparent to the framework */
        memory data;
    };

    /**
     * Load a sound model. Once loaded, recognition of this model can be
     * started and stopped. Only one active recognition per model at a time.
     * The SoundTrigger service must handle concurrent recognition requests by
     * different users/applications on the same model.
     * The implementation returns a unique handle used by other functions
     * (unloadSoundModel(), startRecognition*(), etc...
     *
     * Must have the exact same semantics as loadSoundModel from
     * ISoundTriggerHw@2.0 except that the SoundModel uses shared memory
     * instead of data.
     *
     * @param soundModel A SoundModel structure describing the sound model
     *     to load.
     * @param callback The callback interface on which the soundmodelCallback*()
     *     method must be called upon completion.
     * @param cookie The value of the cookie argument passed to the completion
     *     callback. This unique context information is assigned and
     *     used only by the framework.
     * @return retval Operation completion status: 0 in case of success,
     *     -EINVAL in case of invalid sound model (e.g 0 data size),
     *     -ENOSYS in case of invalid operation (e.g max number of models
     *             exceeded),
     *     -ENOMEM in case of memory allocation failure,
     *     -ENODEV in case of initialization error.
     * @return modelHandle A unique handle assigned by the HAL for use by the
     *     framework when controlling activity for this sound model.
     */
    @callflow(next={"startRecognition_2_1", "unloadSoundModel"})
    loadSoundModel_2_1(SoundModel soundModel,
                   ISoundTriggerHwCallback callback,
                   CallbackCookie cookie)
            generates (int32_t retval, SoundModelHandle modelHandle);

    /**
     * Load a key phrase sound model. Once loaded, recognition of this model can
     * be started and stopped. Only one active recognition per model at a time.
     * The SoundTrigger service must handle concurrent recognition requests by
     * different users/applications on the same model.
     * The implementation returns a unique handle used by other functions
     * (unloadSoundModel(), startRecognition*(), etc...
     *
     * Must have the exact same semantics as loadPhraseSoundModel from
     * ISoundTriggerHw@2.0 except that the PhraseSoundModel uses shared memory
     * instead of data.
     *
     * @param soundModel A PhraseSoundModel structure describing the sound model
     *     to load.
     * @param callback The callback interface on which the soundmodelCallback*()
     *     method must be called upon completion.
     * @param cookie The value of the cookie argument passed to the completion
     *     callback. This unique context information is assigned and
     *     used only by the framework.
     * @return retval Operation completion status: 0 in case of success,
     *     -EINVAL in case of invalid sound model (e.g 0 data size),
     *     -ENOSYS in case of invalid operation (e.g max number of models
     *             exceeded),
     *     -ENOMEM in case of memory allocation failure,
     *     -ENODEV in case of initialization error.
     * @return modelHandle A unique handle assigned by the HAL for use by the
     *     framework when controlling activity for this sound model.
     */
    @callflow(next={"startRecognition_2_1", "unloadSoundModel"})
    loadPhraseSoundModel_2_1(PhraseSoundModel soundModel,
                   ISoundTriggerHwCallback callback,
                   CallbackCookie cookie)
            generates (int32_t retval, SoundModelHandle modelHandle);

    /**
     * Start recognition on a given model. Only one recognition active
     * at a time per model. Once recognition succeeds of fails, the callback
     * is called.
     *
     * Must have the exact same semantics as startRecognition from
     * ISoundTriggerHw@2.0 except that the RecognitionConfig uses shared memory
     * instead of data.
     *
     * @param modelHandle the handle of the sound model to use for recognition
     * @param config A RecognitionConfig structure containing attributes of the
     *     recognition to perform
     * @param callback The callback interface on which the recognitionCallback()
     *     method must be called upon recognition.
     * @param cookie The value of the cookie argument passed to the recognition
     *     callback. This unique context information is assigned and
     *     used only by the framework.
     * @return retval Operation completion status: 0 in case of success,
     *     -EINVAL in case of invalid recognition attributes,
     *     -ENOSYS in case of invalid model handle,
     *     -ENOMEM in case of memory allocation failure,
     *     -ENODEV in case of initialization error.
     */
    @callflow(next={"stopRecognition", "stopAllRecognitions"})
    startRecognition_2_1(SoundModelHandle modelHandle,
                     RecognitionConfig config,
                     ISoundTriggerHwCallback callback,
                     CallbackCookie cookie)
            generates (int32_t retval);
};