/*
 * Copyright (c) 2017  STMicroelectronics – All rights reserved
 * The STMicroelectronics corporate logo is a trademark of STMicroelectronics
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice, this list of conditions
 *   and the following disclaimer.
 *
 * - Redistributions in binary form must reproduce the above copyright notice, this list of
 *   conditions and the following disclaimer in the documentation and/or other materials provided
 *   with the distribution.
 *
 * - Neither the name nor trademarks of STMicroelectronics International N.V. nor any other
 *   STMicroelectronics company nor the names of its contributors may be used to endorse or
 *   promote products derived from this software without specific prior written permission.
 *
 * - All of the icons, pictures, logos and other images that are provided with the source code
 *   in a directory whose title begins with st_images may only be used for internal purposes and
 *   shall not be redistributed to any third party or modified in any way.
 *
 * - Any redistributions in binary form shall not include the capability to display any of the
 *   icons, pictures, logos and other images that are provided with the source code in a directory
 *   whose title begins with st_images.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 */

package com.st.BlueMS.demos.BlueVoice.ASRServices;

import android.app.DialogFragment;
import android.support.annotation.Nullable;

import com.st.BlueMS.demos.BlueVoice.util.AudioBuffer;

/**
 * Interface which defines a generic ASR Engine
 */
public interface ASREngine {

    /**
     * It reveals if this engine needs an authentication key or not.
     * @return true if this service needs an activation key, false otherwise.
     */
    boolean needAuthKey();

    /**
     * It reveals if this engine has already loaded an authentication key or not.
     * @return true if this service has loaded an activation key, false otherwise.
     */
    boolean hasLoadedAuthKey();

    /**
     * It provide a dialog for ASR key insertion.
     * @return a {@link DialogFragment} which allows the insertion of the
     * ASR service activation key. It return null if the service doesn't need any key.
     */
    @Nullable DialogFragment getAuthKeyDialog();

    /**
     * It allows to make an audio recognition request of the {@code audio}
     * provided as parameter. The result should be returned using {@code callback}
     * which is a {@link ASRRequestCallback}.
     * @param audio It contains the audio you want to be recognized.
     * @param callback a callback used to catch the response.
     * @return true is request is correctly done, false otherwise.
     */
    boolean sendASRRequest(AudioBuffer audio, ASRRequestCallback callback);

    /**
     * It reveals if this engine has a continuous recognizer or not.
     * @return true if this engine implements a continuous speech recognition service,
     * false otherwise.
     */
    boolean hasContinuousRecognizer();

    /**
     * Start the recognizer listener
     */
    void startListener();

    /**
     * Stop the recognizer listener
     */
    void stopListener();

    /**
     * Destroy the recognizer listener
     */
    void destroyListener();

    /**
     * Engine name shown to the user
     * @return engine name
     */
    String getName();
}
