/*
* Copyright (c) 2004-2006 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: The CNssSpeechItemTrainer trains SpeechItem objects and later
* saves them to the database. Both in training and saving,
* SpeechItemTrainrt allows grouping several requests together
* and executing them in one run. This is crucial if we want
* training and saving to scale up.
*
*/
#ifndef NSSVASCSPEECHITEMTRAINER_H
#define NSSVASCSPEECHITEMTRAINER_H
#include "nssvasccontext.h"
#include "nssvascspeechitem.h"
#include "nssvasmcoresyncrecoveryhandler.h"
#include "nsssispeechrecognitionutilityobserver.h"
#include "nssvasctrainingactiontracker.h"
#include <badesca.h>
// FORWARD DECLARATIONS
class CNssSpeechItem;
class MNssSaveTagClient;
class MNssDeleteTagClient;
class CNssVASDatabase;
typedef enum
{
EStateIdle,
ETrainStateWaiting,
// Training states
ETrainStateSaveContext,
ETrainStateTraining,
// Saving states
ESaveStateWaiting,
ESaveStateSaving,
// Deleting states
EDeleteStateWaiting,
EDeleteStateDeleting,
// Retraining states
ERetrainStateWaiting,
ERetrainStateRetraining
} TTrainState;
/**
* The CNssSpeechItemTrainer class builds SpeechItem instances when requested.
*
* @lib NssVASApi.lib
* @since 2.8
*/
class CNssSpeechItemTrainer
: public CBase,
public MSISpeechRecognitionUtilityObserver,
private MDelayedNotifiable
{
public:
/**
* Destructor.
* The CNssSpeechItemTrainer destructor
* Destroys the speech item trainer.
*/
~CNssSpeechItemTrainer();
/**
* Creates CNssSpeechItemTrainer.
* @since 2.8
* @param aDatabase VAS database object
* @return Speech item trainer
*/
static CNssSpeechItemTrainer* NewL( CNssVASDatabase* aDatabase );
/**
* Creates CNssSpeechItemTrainer. Pushes it to the cleanup stack.
* @since 2.8
* @param aDatabase VAS database object
* @return Speech item trainer
*/
static CNssSpeechItemTrainer* NewLC( CNssVASDatabase* aDatabase );
/**
* Adds a names to the queue of names to be trained. These names are
* actually trained after a delay. Calling this function resets
* the delay timer.
* @since 2.8
* @param aEventHandler Callback after the names have been trained
* @param aTrainingParams Parameters for training
* @param aSpeechItem Speech item to be trained
* @param aContext Context, to which the speech item belongs.
* @return Success status
*/
MNssSpeechItem::TNssSpeechItemResult TrainTextDelayed(
MNssTrainTextEventHandler* aEventHandler,
CNssTrainingParameters* aTrainingParams,
CNssSpeechItem& aSpeechItem,
CNssContext& aContext
);
/**
* Adds a names to the queue of names to be trained. These names are
* actually trained after a delay. Calling this function resets
* the delay timer.
* @since 2.8
* @param aEventHandler Callback after the names have been trained
* @param aTrainingParams Parameters for training
* @param aSpeechItem Speech item to be trained
* @param aContext Context, to which the speech item belongs.
* @return Success status
*/
MNssSpeechItem::TNssSpeechItemResult RetrainTextDelayed(
MNssTrainTextEventHandler* aEventHandler,
CNssTrainingParameters* aTrainingParams,
CNssSpeechItem& aSpeechItem,
CNssContext& aContext
);
/**
* Queue a tag for saving.
* @since 2.8
* @param aSaveTagClient callback to call after saving / failing to save.
* @param aTag tag to be saved
* @return Symbian-wide error codes
*/
TInt SaveTagDelayed(
MNssSaveTagClient* aSaveTagClient,
CNssTag& aTag
);
/*
* Saves the tags, which the client has piled up
* by calling SaveTagDelayed() repeatedly
* @since 2.8
*/
void DoSaveTags();
/**
* Queue a tag for removal.
* @param aDeleteTagClient callback to call after deleting / failing to delete.
* @param aTag tag to be removed
* @return Symbian-wide error codes
*/
TInt DeleteTagDelayed(
MNssDeleteTagClient* aDeleteTagClient,
CNssTag& aTag
);
/*
* Deprecated, to be removed, when no usage for this method is confirmed
* This method is substituted with DoDeleteGroupedTags
*
* Deletes the tags, which the client has piled up
* by calling DeleteTagDelayed() repeatedly
* @since 2.8
*/
void DoDeleteTags();
/*
* Deletes the tags, which the client has piled up
* by calling DeleteTagDelayed() repeatedly
* @since 2.8
*/
void DoDeleteGroupedTags();
/*
* Sends the next RemoveRule call to SRS
* @since 2.8
*/
void DeleteNextTag();
/*
* Handles successful KAsrEventRemoveRule event after RemoveRule call to SRS.
*
* Can be obsolete method.
* @todo Check if it used in retraining tags. If not, remove it
*
* @since 2.8
*/
void HandleRemoveTagComplete();
/*
* Handles successful KAsrEventRemoveRules event after RemoveRule call to SRS.
* @since 2.8
*/
void HandleRemoveTagsComplete();
/*
* Handles failed KAsrEventRemoveRule event after RemoveRule call to SRS.
* @since 2.8
* @param aError Symbian-wide error code
*/
void HandleRemoveTagFailed( TInt aError );
/*
* Removes tags from VAS and commits SRS removals if successful.
* @since 2.8
*/
void RemoveTagsFromVAS();
/*
* Sends callbacks related to deleting tags. Also works as an error handler.
* @since 2.8
*/
void FinishDeleteTags( TInt aSuccess );
// Functions from base classes
/*
* This function is called after the action tracker decides that it is the time for
* executing the buffered actions
* @from MDelayedNotifiable
*/
void RunBufferedActionsL();
/*
* Starts the timer if it isn't running, and resets the time if it is running.
* @since 2.8
*/
void RestartTimer();
/*
* Trains names after timeout has happened.
* @since 2.8
*/
void DoTrainTextDelayed();
/*
* Checks whether training parameters are equal to previous ones.
* In queued training, all names must have the same training parameters.
* @since 2.8
* @param aParams Training parameters
* @return ETrue, if the training parameters are the same as with other tags.
*/
TBool CheckTrainingParametersL( const CNssTrainingParameters *aParams );
/*
* Checks whether the context is equal to the previous one.
* In queued training, all names must belong to the same context.
* @since 2.8
* @param aContext Context of the tag
* @return ETrue, if the context is the same as for the other tags.
*/
TBool CheckContext(CNssContext& aContext);
/*
* Cleans up, if an error happens during training.
* @since 2.8
* @param anItemArray Array of speech items
*/
void HandleTrainError( RPointerArray<CNssSpeechItem>*& anItemArray );
/*
* Splits a descriptor into an array of descriptors.
* @since 2.8
* @param aPhrase Phrase to be split.
* @param aSeparator Separator character between the parts of the string.
* @return Array, where the descriptor has been split.
*/
CDesC16ArrayFlat* SplitPhraseL( const TDesC& aPhrase, TChar aSeparator );
/*
* Callback to mediate speech recognition events
* @since 2.8
* @from MSpeechRecognitionUtilityObserver
* @param aEvent ID of the speech event
* @param aResult Success status
*/
virtual void MsruoEvent( TUid aEvent, TInt aResult );
/*
* Cleans memory allocated for training.
* @since 2.8
*/
void CleanUpTraining();
/*
* Called when training is complete.
* @since 2.8
* @param aResult Success status
*/
void HandleTrainComplete( TInt aResult );
/*
* Called when lexicon has been created.
* @since 2.8
* @param aError Success status
*/
void HandleLexiconCreated( TInt aError );
/*
* Called when grammar has been created.
* @since 2.8
* @param aError Success status
*/
void HandleGrammarCreated( TInt aError );
/**
* Initializes iSrsApi or returns an error.
* @since 2.8
* @return KErrNone or some symbian-wide error code.
*/
TInt CreateSrsApi();
/*
* Commits training to SRS database..
* @since 2.8
* @return success status
*/
TInt CommitSIUpdate();
/*
* Commits training to SRS database..
* @since 2.8
* @return success status
*/
TInt UncommitSIUpdate();
/*
* Trys to allocate a speech item buffer
* @since 2.8
* @retutn ETrue if success, EFalse if failure
*/
TBool SpeechItemBufferNeeded();
/*
* Trys to allocate a grammar id buffer
* @since 2.8
* @retutn ETrue if success, EFalse if failure
*/
TBool GrammarIdBufferNeeded();
/*
* Phase 1 of retraining: Removes old rules
* @since 2.8
*/
void DoRetrainTextDelayed();
/*
* Phase 2 of retraining: Adds new rules
* @since 2.8
*/
void DoRetrainAddVoiceTags();
/*
* Phase 3 of retraining: Updates VAS DB and makes the callbacks.
* @since 2.8
* @param aResult Success status of the AddVoiceTags call
*/
void HandleRetrainComplete( TInt aResult );
/*
* Converts an array of Speech Items to a format,
* where they can be sent to Utility for training.
* @since 2.8
* @param aSpeechItems List of speech items
* @param aPhrases Storage array for splitted phrases
* @return Success status
*/
TInt SpeechItems2Phrases(
RPointerArray<CNssSpeechItem>& aSpeechItems,
RPointerArray<MDesCArray>& aPhrases );
/**
* Cleans up training/retraining and sends the callbacks to the client.
* @since 2.8
* @param aResult Was training successful or not.
*/
void SendTrainingCallbacks( TInt aResult );
/**
* Cleanup/error handler function for Delayed Remove operation.
* @since 2.8
* @param aSuccess Success status of remove tags
*/
void RemoveTagsFinished( TInt aSuccess );
private: //function
/**
* C++ constructor
*/
CNssSpeechItemTrainer( CNssVASDatabase* aDatabase );
/**
* Symbian 2nd phase constructor
*/
void ConstructL();
/**
* Set the train state.
* This is the place to check any state-related invariants and/or
* print state switching related info in UDEB
*/
void SetState(TTrainState aState);
/*
* Splits a descriptor into an array of descriptors.
* @since 3.1
* @param aPhrase Phrase to be split. (for example "_1Adam_1Russell_2mobile")
* @param aSeparator Separator character between the parts of the string.
* @return Array, where the descriptor has been split.
*/
CDesC16ArrayFlat* SplitPhraseSindeL( const TDesC& aPhrase, TChar aSeparator );
private: //data
// Pointer to SRS Portal object.
// The SpeechItemTrainer own the SpeechItemPortal
CNssVASDatabase* iDatabase;
// Buffer for grouping the MNssSpeechItems for efficient training.
RPointerArray<CNssSpeechItem>* iSpeechItemBuffer;
// Names, which are being trained by CSpeechRecognitionUtility.
RPointerArray<CNssSpeechItem>* iSpeechItemTrainingBuffer;
// Stores grammar IDs, so we don't need to store the whole tag when deleting.
RArray<TUint32>* iGrammarIdBuffer;
// The grammar IDs for speech items, which we are currently deleting.
RArray<TUint32>* iGrammarIdDeletingBuffer;
// This buffer is sent to SRS Utility. Contains: The recognition phrase split into subwords.
RPointerArray<MDesCArray> iPhraseArray;
// State: Idle, waiting or training.
TTrainState iState;
// Training parameters
CNssTrainingParameters* iTrainingParams;
// Context
CNssContext* iContext;
// Rule ID array. Return values from AddVoiceTags() are placed here.
RArray<TUint32>* iRuleIDArray;
// Rule ID array. Rule IDs for tags scheduled for deletion are placed here
RArray<TUint32>* iDeleteRuleIDArray;
// Handle to speech services
CNssSiUtilityWrapper *iSrsApi;
MNssTrainTextEventHandler *iTrainEventHandler;
// Lexicon ID for training
TUint32 iLexiconId;
// Grammar ID for training
TUint32 iGrammarId;
/*************** Saving variables ****************/
// The tags to be saved
RPointerArray<CNssTag> *iTagBuffer;
// Callback function after saving
MNssSaveTagClient* iSaveEventHandler;
/*************** Deleting variables **************/
// Tags, which are currently being deleted
RPointerArray<CNssTag> *iTagDeleteBuffer;
// Callback function after removal
MNssDeleteTagClient* iDeleteEventHandler;
// Counter for asynchronous delete calls
TInt iTagDeleteCounter;
// decides when to execute the buffered (delayed) actions
CNssTrainingActionTracker* iActionTracker;
};
#endif // NSSVASCSPEECHITEMTRAINER_H
// End of file