// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#ifndef __DEVASR_H__

#define __DEVASR_H__

//  INCLUDES

#include <e32base.h>

#include <mmf/common/speechrecognitiondatadevasr.h>

#include <mmf/devasr/devasrcommon.h>

// FORWARD DECLARATION

class CSRSAlgorithmManager;

class TMMFPrioritySettings;

/**

*  Interface for the DevASR callbacks that are implemented by DevASR observers.

*

*  @publishedAll

*  @released

*  @since 8.0

*/

class MDevASRObserver

	{

    public:

        /**

        * DevASR notifies object implementing this interface whenever a spontaneous or non-spontaneous

		* event occurs in DevASR.

        * @since 8.0

        * @param aEvent DevASR event code

        * @param aError DevASR error code

        */

		virtual void DevASREvent(TDevASREvent aEvent, TDevASRError aError)=0;

		/**

        * DevASR notifies object implementing this interface when feature vectors are available.

        * @since 8.0

        * @param aFV Buffer containing the feature vector data

        * @param aSNR Signal-to-noise ratio

		* @param aPosition Indicates whether the feature vector is the first, middle, or end.

        */

		virtual void FeatureVectorDataRcvd(const TDesC16& aFV, TInt32 aSNR, TInt32 aPosition)=0;

        /**

        * DevASR calls this method to send a message in response to a custom command.

        * @since 8.0

        * @param aMsg Buffer containing the message

        */

		virtual void DevASRMessage(TDesC8& aMsg)=0;

    };

/**

*  Interface Class for the DevASR API.

*

*  @publishedAll

*  @released

*  @since 8.0

*/

class CDevASR : public CBase

    {

    public:  // Constructors and destructor

        /**

        * Two-phased constructor.

        *

        * @param aObserver The observer to call back when events occur

        *

        * @return pointer to object of type CDevASR

        */

        IMPORT_C static CDevASR* NewL(MDevASRObserver& aObserver);

        /**

        * Two-phased constructor.

        *

        * @param aObserver The observer to call back when events occur        

        *

        * @return pointer to object of type CDevASR

        */

        IMPORT_C static CDevASR* NewLC(MDevASRObserver& aObserver);

        /**

        * Destructor.

        */

        IMPORT_C virtual ~CDevASR();

    public: // New functions

		/**

        * Cancels the current or started tasks.

        * @since 8.0

        */

        IMPORT_C void Cancel();

		/**

        * Use to request a custom interface implementation from the component.

		* through the DevASR API.

        * @since 8.0

        * @param aInterfaceId - Interface UID, defined with the custom interface.

		* @return a pointer to the interface implementation, or NULL if the requested interface is

		* not implemented. The return value must be cast to the correct type by the user.

        */

		IMPORT_C TAny* CustomInterface(TUid aInterfaceId);

		/**

        * This method is used to indicate the end of a recognition session. All loaded grammars,

		* lexicon, and models become invalid after this call.

        * @since 8.0

        */

		IMPORT_C void EndRecSession();

		/**

        Retreive the properties of the underlying speech recognition engine.

        @param  aPropertyId

		        An array of identifiers being querried

        @param  aPropertyValue

		        An array of values corresponding to the querried identifiers

        @since  8.0

        */

        IMPORT_C void GetEnginePropertiesL(const RArray<TInt>& aPropertyId, RArray<TInt>& aPropertyValue);

		/**

        * Initializes the front-end module in the speech recognition engine.

		* The frontend module used during training/recognition functions is started

		* as a result. This method is intended to be used in conjunction with InitTrainBE().

        * @since 8.0

        * @param aMode - Mode of the recognizer

        */

        IMPORT_C void InitFrontEnd(TRecognizerMode aMode);

		/**

        * Perform any necessary initialization or allocation of the audio resource

		* for playing a voice sample. A buffer to hold audio data to play is allocated.

		* If allocation fails, this method will leave. Client is responsible for filling

		* the buffer with their audio data and invoke Play() on DevASR.

        * @since 8.0

        * @param aPlayDuration - Specifies the duration of playback in microseconds

		* @return A reference to the buffer to be filled with source audio data.

        */

		IMPORT_C TDes8& InitPlayL(TTimeIntervalMicroSeconds32 aPlayDuration);

		/**

        * Initialize the recognition engine back-end. The module responsible for recognition

		* function is started as a result. This method must be used before any recognition

		* operations and intended to be used in conjunction with InitFrontEnd().

        * @since 8.0

        * @param aResult - a reference to an object where the recognition result will be written

        */

        IMPORT_C void InitRecognizerBE(CSDResultSet& aResult);

		/**

        * Initializes the back-end module in the speech recognition engine.

		* The back-end module responsible for training functions is started as a result.

		* This method is intended to be used in conjunction with InitFrontEnd().

        * @since 8.0

        * @param aModel	- Buffer in which the newly created model will be written

        */

        IMPORT_C void InitTrainBE(CSDModel& aModel);

		/**

        * Load the specified recognizer parameter(s). These parameters are used to alter the

        * recognizer's default parameters. The parameters are specified as attribute-value pairs.

        * @since 8.0

        * @param aParameterId - An array of parameter identifiers

        * @param aParameterValue - An array of parameter values

        */

        IMPORT_C void LoadEngineParametersL(const RArray<TInt>& aParameterId, const RArray<TInt>& aParameterValue);

		/**

        * Load the specified grammar into the recognizer.

        * @since 8.0

        * @param aGrammar - A reference to a grammar in an internal format

        */

        IMPORT_C void LoadGrammar(const CSDGrammar& aGrammar);

		/**

        * Load the specified grammar into the recognizer.

        * @since 8.0

        * @param aLexicon - A reference to a lexicon in an internal format

        */

        IMPORT_C void LoadLexicon(const CSDLexicon& aLexicon);

		/**

        * Load the specified Lexicon into the recognizer.

        * @since 8.0

        * @param aModels - A reference to a model bank

        */

        IMPORT_C void LoadModels(const CSDModelBank& aModels);

		/**

        * Request DevASR to play the contents of its own buffer. The buffer was previously

		* allocated by invoking method InitPlay().

        * @since 8.0

        */

        IMPORT_C void Play();

		/**

        * Request to begin recording.

        * @since 8.0

        * @param aRecordDuration - Length of time to record, expressed in microseconds

        */

        IMPORT_C void Record(TTimeIntervalMicroSeconds32 aRecordDuration);

		/**

        * Use to set the priority of the sound device

        * @since 8.0

        * @param aPrioritySettings Priority settings structure

        */

		IMPORT_C void SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings);

		/**

        * This method is used to start a recognition session with the recognition engine.

        * @since 8.0

		* @param aMode Mode of the recognizer

		* @return result code of operation

        */

        IMPORT_C TInt StartRecSession(TRecognizerMode aMode);

		/**

        * Request to unload the specified rule in the grammar from recognizer.

        * @since 8.0

        * @param aGrammarID - Identifer of the grammar to operate on

		* @param aRuleID - Identifier of the rule to remove

        */

        IMPORT_C void UnloadRule(TGrammarID aGrammarID, TRuleID aRuleID);

		/**

        * Retreive the raw audio data accumulated during recording.

        * @since 8.0

		* @param aBuffer Reference to a buffer containing the data

		* @param aDuration Duration of the utterance

        */

        IMPORT_C void GetUtteranceData(TDes8* aBuffer, TTimeIntervalMicroSeconds32& aDuration);

    private:

        /**

        * C++ default constructor.

        */

        CDevASR();

        /**

        * By default Symbian 2nd phase constructor is private.

        */

        void ConstructL(MDevASRObserver& aObserver);

    private:    // Data

        // Pointer to algorithm manager

   		CSRSAlgorithmManager* iSRSAlgorithmManager;

    };

#endif // __DEVASR_H__

// End of File