1 /*

     2 * Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  The CNssSpeechItemTrainer trains SpeechItem objects and later

    15 *               saves them to the database. Both in training and saving,

    16 *               SpeechItemTrainrt allows grouping several requests together

    17 *               and executing them in one run. This is crucial if we want

    18 *               training and saving to scale up.

    19 *

    20 */

    21 

    22 

    23 

    24 #ifndef NSSVASCSPEECHITEMTRAINER_H

    25 #define NSSVASCSPEECHITEMTRAINER_H

    26 

    27 #include "nssvasccontext.h"

    28 #include "nssvascspeechitem.h"

    29 

    30 #include "nssvasmcoresyncrecoveryhandler.h"

    31 #include "nsssispeechrecognitionutilityobserver.h"

    32 #include "nssvasctrainingactiontracker.h"

    33 

    34 #include <badesca.h>

    35 

    36 // FORWARD DECLARATIONS

    37 class CNssSpeechItem;

    38 class MNssSaveTagClient;

    39 class MNssDeleteTagClient;

    40 class CNssVASDatabase;

    41 

    42 

    43 typedef enum

    44     {

    45     EStateIdle,

    46     ETrainStateWaiting,

    47 

    48     // Training states

    49     ETrainStateSaveContext,

    50     ETrainStateTraining,

    51 

    52     // Saving states

    53     ESaveStateWaiting,

    54     ESaveStateSaving,

    55 

    56     // Deleting states

    57     EDeleteStateWaiting,

    58     EDeleteStateDeleting,

    59 

    60     // Retraining states

    61     ERetrainStateWaiting,

    62     ERetrainStateRetraining

    63 

    64     } TTrainState;

    65 

    66 /**

    67 * The CNssSpeechItemTrainer class builds SpeechItem instances when requested.

    68 *

    69 *  @lib NssVASApi.lib

    70 *  @since 2.8

    71 */

    72 class CNssSpeechItemTrainer

    73 : public CBase,

    74   public MSISpeechRecognitionUtilityObserver,

    75   private MDelayedNotifiable

    76 {

    77     public:

    78 

    79     /**

    80     * Destructor.

    81     * The CNssSpeechItemTrainer destructor

    82     * Destroys the speech item trainer.

    83     */   

    84     ~CNssSpeechItemTrainer();

    85 

    86     /**

    87     * Creates CNssSpeechItemTrainer.

    88     * @since 2.8

    89     * @param aDatabase VAS database object

    90     * @return Speech item trainer

    91     */       

    92     static CNssSpeechItemTrainer* NewL( CNssVASDatabase* aDatabase );

    93 

    94     /**

    95     * Creates CNssSpeechItemTrainer. Pushes it to the cleanup stack.

    96     * @since 2.8

    97     * @param aDatabase VAS database object

    98     * @return Speech item trainer

    99     */       

   100     static CNssSpeechItemTrainer* NewLC( CNssVASDatabase* aDatabase );

   101     

   102     /**

   103     * Adds a names to the queue of names to be trained. These names are

   104     * actually trained after a delay. Calling this function resets

   105     * the delay timer.

   106     * @since 2.8

   107     * @param aEventHandler Callback after the names have been trained

   108     * @param aTrainingParams Parameters for training

   109     * @param aSpeechItem Speech item to be trained

   110     * @param aContext Context, to which the speech item belongs.

   111     * @return Success status

   112     */       

   113     MNssSpeechItem::TNssSpeechItemResult TrainTextDelayed(

   114         MNssTrainTextEventHandler* aEventHandler,

   115 	    CNssTrainingParameters*    aTrainingParams,

   116         CNssSpeechItem& aSpeechItem,

   117         CNssContext& aContext

   118         );

   119 

   120     /**

   121     * Adds a names to the queue of names to be trained. These names are

   122     * actually trained after a delay. Calling this function resets

   123     * the delay timer.

   124     * @since 2.8

   125     * @param aEventHandler Callback after the names have been trained

   126     * @param aTrainingParams Parameters for training

   127     * @param aSpeechItem Speech item to be trained

   128     * @param aContext Context, to which the speech item belongs.

   129     * @return Success status

   130     */       

   131     MNssSpeechItem::TNssSpeechItemResult RetrainTextDelayed(

   132         MNssTrainTextEventHandler* aEventHandler,

   133 	    CNssTrainingParameters*    aTrainingParams,

   134         CNssSpeechItem& aSpeechItem,

   135         CNssContext& aContext

   136         );

   137 

   138     /**

   139     * Queue a tag for saving.

   140     * @since 2.8

   141     * @param aSaveTagClient callback to call after saving / failing to save.

   142     * @param aTag           tag to be saved

   143     * @return Symbian-wide error codes

   144     */

   145     TInt SaveTagDelayed(

   146         MNssSaveTagClient* aSaveTagClient,

   147         CNssTag& aTag

   148         );

   149 

   150     /*

   151     * Saves the tags, which the client has piled up

   152     * by calling SaveTagDelayed() repeatedly

   153     * @since 2.8

   154     */

   155     void DoSaveTags();

   156 

   157     /**

   158     * Queue a tag for removal.

   159     * @param aDeleteTagClient callback to call after deleting / failing to delete.

   160     * @param aTag           tag to be removed

   161     * @return Symbian-wide error codes

   162     */

   163     TInt DeleteTagDelayed(

   164         MNssDeleteTagClient* aDeleteTagClient,

   165         CNssTag& aTag

   166         );

   167 

   168     /*

   169     * Deprecated, to be removed, when no usage for this method is confirmed

   170     * This method is substituted with DoDeleteGroupedTags

   171     *

   172     * Deletes the tags, which the client has piled up

   173     * by calling DeleteTagDelayed() repeatedly

   174     * @since 2.8

   175     */

   176     void DoDeleteTags();

   177     

   178     /*

   179     * Deletes the tags, which the client has piled up

   180     * by calling DeleteTagDelayed() repeatedly

   181     * @since 2.8

   182     */

   183     void DoDeleteGroupedTags();

   184 

   185     /*

   186     * Sends the next RemoveRule call to SRS

   187     * @since 2.8

   188     */

   189     void DeleteNextTag();

   190 

   191     /*

   192     * Handles successful KAsrEventRemoveRule event after RemoveRule call to SRS.

   193     *

   194     * Can be obsolete method.

   195     * @todo Check if it used in retraining tags. If not, remove it

   196     *

   197     * @since 2.8

   198     */

   199     void HandleRemoveTagComplete();

   200     

   201     /*

   202     * Handles successful KAsrEventRemoveRules event after RemoveRule call to SRS.

   203     * @since 2.8

   204     */

   205     void HandleRemoveTagsComplete();

   206 

   207     /*

   208     * Handles failed KAsrEventRemoveRule event after RemoveRule call to SRS.

   209     * @since 2.8

   210     * @param aError Symbian-wide error code

   211     */

   212     void HandleRemoveTagFailed( TInt aError );

   213 

   214     /*

   215     * Removes tags from VAS and commits SRS removals if successful.

   216     * @since 2.8

   217     */

   218     void RemoveTagsFromVAS();

   219 

   220     /*

   221     * Sends callbacks related to deleting tags. Also works as an error handler.

   222     * @since 2.8

   223     */

   224     void FinishDeleteTags( TInt aSuccess );

   225 

   226     // Functions from base classes

   227 

   228     /*

   229     * This function is called after the action tracker decides that it is the time for

   230     * executing the buffered actions

   231     * @from MDelayedNotifiable

   232     */

   233     void RunBufferedActionsL();

   234 

   235     /*

   236     * Starts the timer if it isn't running, and resets the time if it is running.

   237     * @since 2.8

   238     */

   239     void RestartTimer();

   240 

   241     /*

   242     * Trains names after timeout has happened.

   243     * @since 2.8

   244     */

   245     void DoTrainTextDelayed();

   246 

   247     /*

   248     * Checks whether training parameters are equal to previous ones.

   249     * In queued training, all names must have the same training parameters.

   250     * @since 2.8

   251     * @param aParams Training parameters

   252     * @return ETrue, if the training parameters are the same as with other tags.

   253     */

   254     TBool CheckTrainingParametersL( const CNssTrainingParameters *aParams );

   255 

   256     /*

   257     * Checks whether the context is equal to the previous one.

   258     * In queued training, all names must belong to the same context.

   259     * @since 2.8

   260     * @param aContext Context of the tag

   261     * @return ETrue, if the context is the same as for the other tags.

   262     */

   263     TBool CheckContext(CNssContext& aContext);

   264 

   265     /*

   266     * Cleans up, if an error happens during training.

   267     * @since 2.8

   268     * @param anItemArray Array of speech items

   269     */

   270     void HandleTrainError( RPointerArray<CNssSpeechItem>*& anItemArray );

   271 

   272     /*

   273     * Splits a descriptor into an array of descriptors.

   274     * @since 2.8

   275     * @param aPhrase Phrase to be split.

   276     * @param aSeparator Separator character between the parts of the string.

   277     * @return Array, where the descriptor has been split.

   278     */

   279     CDesC16ArrayFlat* SplitPhraseL( const TDesC& aPhrase, TChar aSeparator );

   280 

   281     /*

   282     * Callback to mediate speech recognition events

   283     * @since 2.8

   284     * @from MSpeechRecognitionUtilityObserver

   285     * @param aEvent ID of the speech event

   286     * @param aResult Success status

   287     */

   288     virtual void MsruoEvent( TUid aEvent, TInt aResult );

   289 

   290     /*

   291     * Cleans memory allocated for training.

   292     * @since 2.8

   293     */

   294     void CleanUpTraining();

   295 

   296     /*

   297     * Called when training is complete.

   298     * @since 2.8

   299     * @param aResult Success status

   300     */

   301     void HandleTrainComplete( TInt aResult );

   302 

   303     /*

   304     * Called when lexicon has been created.

   305     * @since 2.8

   306     * @param aError Success status

   307     */

   308     void HandleLexiconCreated( TInt aError );

   309 

   310     /*

   311     * Called when grammar has been created.

   312     * @since 2.8

   313     * @param aError Success status

   314     */

   315     void HandleGrammarCreated( TInt aError );

   316 

   317     /**

   318     * Initializes iSrsApi or returns an error.

   319     * @since 2.8

   320     * @return KErrNone or some symbian-wide error code.

   321     */

   322     TInt CreateSrsApi();

   323 

   324     /*

   325     * Commits training to SRS database..

   326     * @since 2.8

   327     * @return success status

   328     */

   329     TInt CommitSIUpdate();

   330 

   331     /*

   332     * Commits training to SRS database..

   333     * @since 2.8

   334     * @return success status

   335     */

   336     TInt UncommitSIUpdate();

   337 

   338     /*

   339     * Trys to allocate a speech item buffer

   340     * @since 2.8

   341     * @retutn ETrue if success, EFalse if failure

   342     */

   343     TBool SpeechItemBufferNeeded();

   344 

   345     /*

   346     * Trys to allocate a grammar id buffer

   347     * @since 2.8

   348     * @retutn ETrue if success, EFalse if failure

   349     */

   350     TBool GrammarIdBufferNeeded();

   351 

   352     /*

   353     * Phase 1 of retraining: Removes old rules

   354     * @since 2.8

   355     */

   356     void DoRetrainTextDelayed();

   357 

   358     /*

   359     * Phase 2 of retraining: Adds new rules

   360     * @since 2.8

   361     */

   362     void DoRetrainAddVoiceTags();

   363 

   364     /*

   365     * Phase 3 of retraining: Updates VAS DB and makes the callbacks.

   366     * @since 2.8

   367     * @param aResult Success status of the AddVoiceTags call

   368     */

   369     void HandleRetrainComplete( TInt aResult );

   370 

   371     /*

   372     * Converts an array of Speech Items to a format,

   373     * where they can be sent to Utility for training.

   374     * @since 2.8

   375     * @param aSpeechItems List of speech items

   376     * @param aPhrases Storage array for splitted phrases

   377     * @return Success status

   378     */

   379     TInt SpeechItems2Phrases(

   380         RPointerArray<CNssSpeechItem>& aSpeechItems,

   381         RPointerArray<MDesCArray>& aPhrases );

   382 

   383     /**

   384     * Cleans up training/retraining and sends the callbacks to the client.

   385     * @since 2.8

   386     * @param aResult Was training successful or not.

   387     */

   388     void SendTrainingCallbacks( TInt aResult );

   389 

   390     /**

   391     * Cleanup/error handler function for Delayed Remove operation.

   392     * @since 2.8

   393     * @param aSuccess Success status of remove tags

   394     */

   395     void RemoveTagsFinished( TInt aSuccess );

   396 

   397   private: //function

   398 

   399 

   400    /**

   401     * C++ constructor

   402     */ 

   403     CNssSpeechItemTrainer( CNssVASDatabase* aDatabase );

   404 

   405 

   406     /**

   407     * Symbian 2nd phase constructor 

   408     */      

   409     void ConstructL();

   410     

   411     /**

   412     * Set the train state.

   413     * This is the place to check any state-related invariants and/or

   414     * print state switching related info in UDEB

   415     */

   416     void SetState(TTrainState aState);

   417 

   418     /*

   419     * Splits a descriptor into an array of descriptors.

   420     * @since 3.1

   421     * @param aPhrase Phrase to be split. (for example "_1Adam_1Russell_2mobile")

   422     * @param aSeparator Separator character between the parts of the string.

   423     * @return Array, where the descriptor has been split.

   424     */

   425     CDesC16ArrayFlat* SplitPhraseSindeL( const TDesC& aPhrase, TChar aSeparator );

   426 

   427   private: //data

   428 

   429     // Pointer to SRS Portal object.

   430     // The SpeechItemTrainer own the SpeechItemPortal

   431     CNssVASDatabase* iDatabase;

   432 

   433     // Buffer for grouping the MNssSpeechItems for efficient training.

   434     RPointerArray<CNssSpeechItem>* iSpeechItemBuffer;

   435 

   436     // Names, which are being trained by CSpeechRecognitionUtility.

   437     RPointerArray<CNssSpeechItem>* iSpeechItemTrainingBuffer;

   438 

   439     // Stores grammar IDs, so we don't need to store the whole tag when deleting.

   440     RArray<TUint32>* iGrammarIdBuffer;

   441 

   442     // The grammar IDs for speech items, which we are currently deleting.

   443     RArray<TUint32>* iGrammarIdDeletingBuffer;

   444 

   445     // This buffer is sent to SRS Utility. Contains: The recognition phrase split into subwords.

   446     RPointerArray<MDesCArray> iPhraseArray;

   447 

   448     // State: Idle, waiting or training.

   449     TTrainState iState;

   450 

   451     // Training parameters

   452     CNssTrainingParameters* iTrainingParams;

   453 

   454     // Context

   455     CNssContext* iContext;

   456 

   457     // Rule ID array. Return values from AddVoiceTags() are placed here.

   458     RArray<TUint32>* iRuleIDArray;

   459     

   460     // Rule ID array. Rule IDs for tags scheduled for deletion are placed here

   461     RArray<TUint32>* iDeleteRuleIDArray;

   462 

   463     // Handle to speech services

   464     CNssSiUtilityWrapper *iSrsApi;

   465 

   466     MNssTrainTextEventHandler *iTrainEventHandler;

   467 

   468     // Lexicon ID for training

   469     TUint32 iLexiconId;

   470 

   471     // Grammar ID for training

   472     TUint32 iGrammarId;

   473 

   474     /*************** Saving variables ****************/

   475     // The tags to be saved

   476     RPointerArray<CNssTag> *iTagBuffer;

   477 

   478     // Callback function after saving

   479     MNssSaveTagClient* iSaveEventHandler;

   480 

   481     /*************** Deleting variables **************/

   482     // Tags, which are currently being deleted

   483     RPointerArray<CNssTag> *iTagDeleteBuffer;

   484 

   485     // Callback function after removal

   486     MNssDeleteTagClient* iDeleteEventHandler;

   487 

   488     // Counter for asynchronous delete calls

   489     TInt iTagDeleteCounter;

   490     

   491     // decides when to execute the buffered (delayed) actions

   492     CNssTrainingActionTracker* iActionTracker;

   493 

   494 };

   495 

   496 

   497 

   498 #endif // NSSVASCSPEECHITEMTRAINER_H

   499 

   500 // End of file