diff -r cad71a31b7fc -r e36f3802f733 speechsrv_plat/nss_devasr_api/inc/nssdevasr.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/speechsrv_plat/nss_devasr_api/inc/nssdevasr.h Wed Sep 01 12:29:17 2010 +0100 @@ -0,0 +1,450 @@ +/* +* Copyright (c) 2004-2007 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: This file contains definition of the DevASR API. +* +*/ + + +#ifndef NSSDEVASRAPI_H +#define NSSDEVASRAPI_H + +//#define AUDIOBUFFER_TO_FILE + +// INCLUDES +#include +#include +#include + +// FORWARD DECLARATIONS +class CSRSAlgorithmManager; +class CVMAlgorithmManager; +class TMMFPrioritySettings; + +/** +* Interface for the DevASR callbacks that are implemented by DevASR observers. +* +* @lib NssDevASR.lib +* @since 2.8 +*/ +class MDevASRObserver + { + public: + /** + * DevASR calls this method to get configuration data. + * + * @since 2.8 + * @param "TUint32 aPackageType" Type identifier. + * @param "TUint32 aPackageID" Identifier of package. + * @param "TUint32 aStartPosition" Starting position within package in bytes. + * @param "TUint32 aEndPosition" Ending position within package in bytes. + * @return Pointer to created buffer containing the request data. + */ + virtual HBufC8* ConfigurationData( TUint32 aPackageType, + TUint32 aPackageID, + TUint32 aStartPosition = 0, + TUint32 aEndPosition = KMaxTUint32 ) = 0; + + /** + * DevASR notifies object implementing this interface whenever a spontaneous or non-spontaneous + * event occurs in DevASR. + * + * @since 2.8 + * @param "TDevASREvent aEvent" DevASR event code. + * @param "TDevASRError aError" DevASR error code. + */ + virtual void DevASREvent( TDevASREvent aEvent, TDevASRError aError ) = 0; + + /** + * DevASR notifies object implementing this interface when feature vectors are available. + * + * @since 2.8 + * @param "TDesC16& aFV" Buffer containing the feature vector data. + * @param "TInt32 aSNR" Signal-to-noise ratio. + * @param "TInt32 aPosition" Indicates whether the feature vector is the first, middle, or end. + */ + virtual void FeatureVectorDataRcvd( const TDesC8& aFV, TInt32 aSNR, TInt32 aPosition ) = 0; + + /** + * DevASR calls this method to send a message in response to a custom command. + * + * @since 2.8 + * @param "TDesC8& aMsg" Buffer containing the message. + */ + virtual void DevASRMessage( TDesC8& aMsg ) = 0; + + /** + * Called when DevASR needs a SI lexicon. + * + * @since 2.8 + * @param "TSILexiconID aLexiconID" Lexicon ID of requested lexicon. + * @return Pointer to created lexicon. + */ + virtual CSILexicon* SILexiconL( TSILexiconID aLexiconID ) = 0; + + /** + * Invoked by DevASR when it needs utterance data. The response is sent + * using SendSpeechData(). + * + * @since 2.8 + */ + virtual void RequestSpeechData() = 0; + }; + +/** +* Interface Class for the DevASR API. +* +* @lib NssDevASR.lib +* @since 2.8 +*/ +class CDevASR : public CBase + { + public: // Constructors and destructor + + /** + * Two-phased constructors. + * + * @param "MDevASRObserver& aObserver" Reference to callback observer. + */ + IMPORT_C static CDevASR* NewL( MDevASRObserver& aObserver ); + IMPORT_C static CDevASR* NewLC( MDevASRObserver& aObserver ); + + /** + * Destructor. + */ + IMPORT_C virtual ~CDevASR(); + + public: // New functions + + /** + * Activates a grammar. + * + * @since 2.8 + * @param "TSIGrammarID aGrammarID" A grammar identifier. + */ + IMPORT_C void ActivateGrammarL( TSIGrammarID aGrammarID ); + + /** + * Adapts vocabulary and models after successful recognition. + * + * @since 2.8 + * @param "CSIResultSet& aResultSet" Reco result set. + * @param "TInt aResultIndex" Index of correct result. + */ + IMPORT_C void AdaptL( const CSIResultSet& aResultSet, TInt aResultIndex ); + + /** + * Cancels the current or started tasks. + * @since 2.8 + */ + IMPORT_C void Cancel(); + + /** + * Compiles an SI grammar. + * + * @since 2.8 + * @param "CSICompiledGrammar& aGrammar" Reference to a grammar to be compiled. + */ + IMPORT_C void CompileGrammarL( CSICompiledGrammar& aGrammar ); + + /** + * Computes number of rule variants for grammar. + * + * @since 2.8 + * @param "CSIGrammar& aGrammar" A grammar where to add new rules. + * @param "TUint32 aTargetNRuleVariants" Preferable target number of all + * rule variants after adding new rule variants. + * @param "TUint32 aMaxNRuleVariants" Maximum number of all rule variants. + * @param "RArray& aNewRuleScores" Scores for each new rule. The + * size of array tells also how many new rules will be added. + * Based on the scores some rules can get more rule variants than + * others. If there is no scores available, the array should + * initialize with constant values. + * @param "RArray& aNewRuleVariants" Array where to add number + * of new rule variants for new rules. The order is equivalent + * to aNewRuleScores. + * @param "TUint32& aNPrune" Number of rule variants which should be + * pruned before adding new rule variants. + */ + IMPORT_C void ComputeNewGrammarSizeL( const CSIGrammar& aGrammar, + const TUint32 aTargetNRuleVariants, + const TUint32 aMaxNRuleVariants, + const RArray& aNewRuleScores, + RArray& aNewRuleVariants, + TUint32& aNPrune ); + + /** + * Use to request a custom interface implementation from the component. + * through the DevASR API. + * + * @since 2.8 + * @param "TUid 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 ); + + /** + * Deactivates a grammar. + * + * @since 2.8 + * @param "TSIGrammarID aGrammarID" A grammar identifier. + */ + IMPORT_C void DeactivateGrammarL( TSIGrammarID aGrammarID ); + + /** + * Requests to end recording and a result will be resolved. + * + * @since 2.8 + */ + IMPORT_C void EndRecord(); + + /** + * This method is used to indicate the end of a recognition session. All loaded grammars, + * lexicon, and models become invalid after this call. + * + * @since 2.8 + */ + IMPORT_C void EndRecSession(); + + /** + * Retreive the properties of the underlying speech recognition engine. + * + * @since 2.8 + * @param "RArray& aPropertyId" An array of identifiers being querried. + * @param "RArray& aPropertyValue" An array of values corresponding + * to the querried identifiers. + */ + IMPORT_C void GetEnginePropertiesL( const RArray& aPropertyId, + RArray& aPropertyValue ); + + /** + * Retreive the raw audio data accumulated during recording. + * + * @since 2.8 + * @param "TDes8* aBuffer" The buffer where utterance data will be + * written. + * @param "TTimeIntervalMicroSeconds32& aDuration" Duration of the + * utterance. + */ + IMPORT_C void GetUtteranceData( TDes8* aBuffer, + TTimeIntervalMicroSeconds32& aDuration ); + + /** + * 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 2.8 + * @param "TRecognizerMode aMode" Mode of the recognizer. + */ + IMPORT_C void InitFrontEnd( TRecognizerMode aMode ); + + /** + * 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 2.8 + * @param "CSIResultSet& aResult" A reference to an object where the + * recognition result will be written. + */ + IMPORT_C void InitRecognizerBE( CSIResultSet& aResult ); + + /** + * 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 2.8 + * @param "RArray& aParameterId" An array of parameter identifiers. + * @param "RArray& aParameterValue" An array of parameter values. + */ + IMPORT_C void LoadEngineParametersL( const RArray& aParameterId, + const RArray& aParameterValue ); + + /** + * Load the specified grammar into the recognizer. + * + * @since 2.8 + * @param "CSIGrammar& aGrammar" A reference to a SI grammar. + */ + IMPORT_C void LoadGrammar( const CSIGrammar& aGrammar ); + + /** + * Load the specified grammar into the recognizer. + * + * @since 2.8 + * @param "CSICompiledGrammar& aGrammar" A reference to a compiled + * SI grammar + */ + IMPORT_C void LoadGrammar( const CSICompiledGrammar& aGrammar ); + + /** + * Unloads the specified grammar from the recognizer. + * + * @since 2.8 + * @param "CSIGrammar& aGrammar" A reference to a SI grammar. + */ + IMPORT_C void UnloadGrammar( const CSIGrammar& aGrammar ); + + /** + * Unloads the specified grammar from the recognizer. + * + * @since 2.8 + * @param "CSICompiledGrammar& aGrammar" A reference to a compiled + * SI grammar + */ + IMPORT_C void UnloadGrammar( const CSICompiledGrammar& aGrammar ); + + /** + * Load the specified SI lexicon into the recognizer. + * + * @since 2.8 + * @param "CSILexicon& aLexicon" A reference to a SI lexicon. + */ + IMPORT_C void LoadLexicon( const CSILexicon& aLexicon ); + + /** + * Load the specified model bank into the recognizer. + * + * @since 2.8 + * @param "CSIModelBank& aModels" A reference to a SI model bank. + */ + IMPORT_C void LoadModels( const CSIModelBank& aModels ); + + /** + * Determines which rule variants can be removed. + * + * @since 2.8 + * @param "CSIGrammar& aGrammar" A grammar to be pruned. + * @param "TUint32 aMinNumber" Minimum number of pruned items. + * @param "RArray" A array where to put information + * which variants can be pruned. + */ + IMPORT_C TBool PruneGrammar( const CSIGrammar& aGrammar, + const TUint32 aMinNumber, + RArray& aPrunedRuleVariants ); + + /** + * Request to begin recognition. + * + * @since 2.8 + * @param "TTimeIntervalMicroSeconds32 aRecordDuration" Length of time + * to record, expressed in microseconds. Zero means infinite + * duration. + */ + IMPORT_C void Record( TTimeIntervalMicroSeconds32 aRecordDuration ); + + /** + * Starts sampling before Record call. + * + * @since 3.2 + */ + IMPORT_C void PreStartSamplingL(); + + /** + * Use to send the utterance data as a response to the RequestSpeechData(). + * + * @since 2.8 + * @param "TDesC8& aBuffer" Buffer containing utterance data. + * @param "TBool aEnd" Flag to tell if given buffer is the last one. + */ + IMPORT_C void SendSpeechData( TPtrC8& aBuffer, TBool aEnd ); + + /** + * Use to set the priority of the sound device. + * + * @since 2.8 + * @param "TMMFPrioritySettings& 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 2.8 + * @param "TRecognizerMode aMode" Mode of the recognizer. + * @return Result code of operation. + */ + IMPORT_C TInt StartRecSession( TRecognizerMode aMode ); + + /** + * Starts training from text + * + * @since 2.8 + * @param "CSITtpWordList& aWordList" List of text entries for training. + * @param "RArray& aDefaultLanguage" Default language for + * pronunciations. + * @param "RArray& aMaxNPronunsForWord" Maximum number of + * pronunciation per word. + */ + IMPORT_C void StartTrainingFromTextL( CSITtpWordList& aWordList, + const RArray& aDefaultLanguage, + const RArray& aMaxNPronunsForWord ); + + /** + * Request to unload the specified rule in the grammar from recognizer. + * + * @since 2.8 + * @param "TSIGrammarID aGrammarID" Identifer of the grammar to operate on. + * @param "TSIRuleID aRuleID" Identifier of the rule to remove. + */ + IMPORT_C void UnloadRule( TSIGrammarID aGrammarID, TSIRuleID aRuleID ); + + /** + * Checks if grammar is loaded or not + * + * @since 2.8 + * @param "TSIGrammarID aGrammarID" Grammar ID + * @return ETrue if grammar is currently loaded, EFalse otherwise. + */ + IMPORT_C TBool IsGrammarLoaded( TSIGrammarID aGrammarID ); + + /** + * Checks if grammar is active or not + * + * @since 2.8 + * @param "TSIGrammarID aGrammarID" Grammar ID + * @return ETrue if grammar is active, EFalse otherwise. + */ + IMPORT_C TBool IsGrammarActive( TSIGrammarID aGrammarID ); + + private: + + /** + * C++ default constructor. + */ + CDevASR(); + + /** + * By default Symbian 2nd phase constructor is private. + */ + void ConstructL(MDevASRObserver& aObserver); + + private: // Data + + // Pointer to recognition algorithm manager + CSRSAlgorithmManager* iSRSAlgorithmManager; + + // Reserved for future use + TAny* iReserved1; + TAny* iReserved2; + + }; + +#endif // NSSDEVASRAPI_H + +// End of File