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 CSeechItem provides speech mechanism to request services from SRS.

    15 *

    16 */

    17 

    18 

    19 #ifndef NSSVASCSPEECHITEM_H

    20 #define NSSVASCSPEECHITEM_H

    21 

    22 // INCLUDE FILES

    23 #include <nsssispeechrecognitiondatacommon.h>

    24 #include <nsssispeechrecognitionutilityobserver.h>

    25 #include <nssttscommon.h>

    26 

    27 #include "srsfbldvariant.hrh"

    28 #include "nssvascoreconstant.h"

    29 #include "nssvasmspeechitem.h"

    30 #include "nssvasmtrainvoiceeventhandler.h"

    31 #include "nssvasmtraintexteventhandler.h"

    32 #include "nssvasmplayeventhandler.h"

    33 #include "nssvasmcoresrsdbeventhandler.h"

    34 #include "nssvasmsavetagclient.h"

    35 #include "nssvasmdeletetagclient.h"

    36 #include "nssvasccontext.h"

    37 #include "nssvascspeechitemsrsportal.h"

    38 #include "nssvastspeechitemconstant.h"

    39 #include "nssvasttsutilitywrapper.h"

    40 

    41 // FORWARD DECLARATIONS

    42 class CNssSpeechItemTrainer;

    43 class CNssTag;

    44 

    45 /**

    46 * The CNssSpeechItem class provides a realization of the MNssSpeechItem client

    47 * interface. The CNssSpeechItem methods use the CSpeechRecognitionUtility Api 

    48 * to implement client speech requests.

    49 *

    50 * @lib nssvasapi.lib

    51 * @since 2.8

    52 */

    53 class CNssSpeechItem : public CBase, 

    54                        public MNssSpeechItem, 

    55                        public MSISpeechRecognitionUtilityObserver,

    56                        public MTtsClientUtilityObserver

    57 {

    58 

    59   public:   // Constructors and destructor

    60 

    61     /**

    62     * Destructor.

    63     */ 

    64     ~CNssSpeechItem();

    65 

    66     /**

    67     * Two-phased CNssSpeechItem constructor

    68     *

    69     * @since 2.0

    70     * @param aContext A reference to Context object

    71     * @param aPortal A reference to SpeechItem Portal object

    72     * @return a pointer to the new SpeechItem object

    73     */   

    74     static CNssSpeechItem* NewL( CNssContext& aContext, 

    75                                  CNssSpeechItemSrsPortal& aPortal, 

    76                                  CNssSpeechItemTrainer& aTrainer );

    77 

    78 

    79     /**

    80     * Two-phased CNssSpeechItem constructor

    81     *

    82     * @since 2.0

    83     * @param aContext A reference to Context object

    84     * @param aPortal A reference to SpeechItem Portal object

    85     * @param aRuleID A rule ID value

    86     * @param aText A reference to the TDesc text 

    87     * @return a pointer to the new SpeechItem object

    88     */   

    89     static CNssSpeechItem* NewL( CNssContext& aContext,

    90                                  CNssSpeechItemSrsPortal& aPortal,

    91                                  CNssSpeechItemTrainer& aTrainer,

    92                                  TUint32 aRuleID,

    93                                  const TDesC& aText );

    94 

    95     /**

    96     * Two-phased CNssSpeechItem constructor

    97     *

    98     * @since 2.0

    99     * @param aContext A reference to Context object

   100     * @param aPortal A reference to SpeechItem Portal object

   101     * @param aRuleID A rule ID value

   102     * @param aText A reference to the TDesc text 

   103     * @return a pointer to the new SpeechItem object

   104     */   

   105     static CNssSpeechItem* NewLC( CNssContext& aContext,

   106                                   CNssSpeechItemSrsPortal& aPortal, 

   107                                   CNssSpeechItemTrainer& aTrainer,

   108                                   TUint32 aRuleID,

   109                                   const TDesC& aText );

   110 

   111 

   112   public: // New functions

   113 

   114     /**

   115     * Method to return the rule ID

   116     *

   117     * @since 2.0

   118     * @param 

   119     * @return the rule ID.

   120     */   

   121     TUint32 RuleID();

   122 

   123     /**

   124     * Method to set the rule ID

   125     *

   126     * @since 2.0

   127     * @param aRuleID Rule ID 

   128     */   

   129     void SetRuleID( TUint32 aRuleID );

   130 

   131     /**

   132     * Method to set the Training Type

   133     *

   134     * @since 2.0

   135     * @param aTrainType Training Type

   136     */   

   137     void SetTrainedType( TNssVasCoreConstant::TNssTrainedType aTrainType );

   138 

   139 	/**

   140     * Create a copy of the SpeechItem object. 

   141 	* This cunction creates a new SpeechItem by allocating memory for

   142 	* a new SpeechItem, and deep copying the members of the SpeechItem 

   143 	* on which this fucntion is called. Old SpeechItem and new SpeechItem

   144     * exist. Client need to deallocate memory for both.

   145     *

   146     * @param aContext a pointer to a Context

   147     * @return pointer the newly created SpeechItem.

   148     */

   149 	CNssSpeechItem* CopyL( CNssContext* aContext );

   150 

   151 

   152 

   153   public: // Functions from base classes

   154 

   155 

   156     /**

   157     * Function inherited from MSISpeechRecognitionUtilityObserver to

   158     * handle the events from SRS Utility object

   159     *

   160     * @since 2.0

   161     * @param aEvent an event from the SRS utility object

   162     * @param aResult the result from aEvent operation

   163     */   

   164     void MsruoEvent( TUid aEvent, TInt aResult );

   165 

   166  

   167     /**

   168     * The Record method is used by the client in the train voice sequence

   169     * for SRS to record input speech.

   170     *

   171     * @since 2.0

   172     * @param aTrainVoiceEventHandler a reference to TrainVoiceEventHandler

   173     * @return a fail or success result from processing this method.

   174     */   

   175     TNssSpeechItemResult RecordL( MNssTrainVoiceEventHandler* aTrainVoiceEventHandler );

   176 

   177 

   178     /**

   179     * Method called by the client to indicate to SRS that a playback is

   180     * needed.

   181     *

   182     * @since 2.0

   183     * @param aPlayEventHandler a reference to PlayEventHandler

   184     * @return a fail or success result from processing this method.

   185     */   

   186     TNssSpeechItemResult PlayL( MNssPlayEventHandler* aPlayEventHandler );

   187 

   188     /**

   189     * Method called by the client to indicate to SRS that a playback is

   190     * needed with a certain language.

   191     *

   192     * @since 2.8

   193     * @param aPlayEventHandler a call back object to handle the play events

   194     * @param aLanguage language which will be used in playback

   195     * @return TNssSpeechItemResult synchronous return value to identify whether the

   196     *         synchronous process is success or fail

   197     */    

   198     TNssSpeechItemResult PlayL( MNssPlayEventHandler* aPlayEventHandler,

   199                                 TLanguage aLanguage );

   200 

   201     /**

   202     * Method called by the client to indicate to SRS that training is

   203     * needed.

   204     *

   205     * @since 2.0

   206     * @param aTrainVoiceEventHandler a reference to TrainVoiceEventHandler

   207     * @return a fail or success result from processing this method.

   208     */   

   209     TNssSpeechItemResult TrainVoiceL(MNssTrainVoiceEventHandler* aTrainVoiceEventHandler);

   210 

   211     /**

   212     * Method called by the client to  cancel the previous operation.

   213     *

   214     * @since 2.0

   215     * @return a fail or success result from processing this method.

   216     */   

   217     TNssSpeechItemResult CancelL();

   218  

   219     /**

   220     * The TrainingCapabilities member fucntion is used by the client 

   221     * to get training capabilities to beused in Speaker Independent voice 

   222     * recognition.

   223     *

   224     * @since 2.0

   225     * @return a pointer to the Training Capability array object

   226     */   

   227     CArrayFixFlat<TNssVasCoreConstant::TNssTrainingCapability>* TrainingCapabilities();

   228  

   229     /**

   230     * Method to return the Training Type

   231     *

   232     * @since 2.0

   233     * @return the Training Type

   234     */   

   235     TNssVasCoreConstant::TNssTrainedType TrainedType();

   236 

   237     /**

   238     * Method to return the Text

   239     *

   240     * @since 2.0

   241     * @return the Text

   242     */   

   243     TDesC& Text();

   244 

   245     /**

   246     * Returns the raw training text from where escape characters are not removed.

   247     * Should not be used by clients who want to display the string.

   248     *

   249     * @since 3.2

   250     * @return Reference to the text buffer

   251     */    

   252     TDesC& RawText();

   253     

   254     /**

   255     * Returns the part of text which identified with the given id.

   256     * If RawText() is for example "_1Amy_1Harris_2mobile" then 

   257     * PartialTextL( _L( "1" ) ) call will return "Amy Harris".

   258     *

   259     * @since 3.2

   260     * @param aIdentifier ID of the text part to return

   261     * @reuturn Text or KNullDesC if identifier is not found

   262     */

   263     HBufC* PartialTextL( const TDesC& aIdentifier );

   264     

   265     /**

   266     * Method to set the training text

   267     *

   268     * @since 2.0

   269     * @param aText Text which will be trained

   270     * @return

   271     */   

   272     void SetTextL( const TDesC& aText );

   273 

   274     /**

   275     * Method to query playing support.

   276     *

   277     * @since 2.8

   278     * @return TBool True if playing is supported.

   279     */

   280     TBool IsPlayingSupported();

   281 

   282     /**

   283     * Method to train a speech model from text.

   284     *

   285     * @since 2.8

   286     * @param aEventHandler Event handler

   287     * @param aTrainingParams Training options, NULL uses default ones.

   288     * @return TNssSpeechItemResult Success status

   289     */

   290     TNssSpeechItemResult TrainTextL( MNssTrainTextEventHandler* aEventHandler,

   291                                      CNssTrainingParameters* aTrainingParams );

   292 

   293     /**

   294     * Unused method for future extensions of MTtsClientUtilityObserver.

   295     *

   296     * @from MTtsClientUtilityObserver

   297     * @since 2.8

   298     * @param aEvent event ID

   299     * @param aError result

   300     */

   301 	void MapcCustomCommandEvent( TInt aEvent, TInt aError );

   302 

   303     /**

   304     * Method to signal that playing has been initialized.

   305     *

   306     * @from MTtsClientUtilityObserver

   307     * @since 2.8

   308     * @param aError Successful or not

   309     * @param aDuration Length of the TTS waveform

   310     */

   311 	void MapcInitComplete( TInt aError, const TTimeIntervalMicroSeconds& aDuration);

   312 

   313     /**

   314     * Method to signal that playing has been completed.

   315     *

   316     * @from MTtsClientUtilityObserver

   317     * @since 2.8

   318     * @param aError Successful or not

   319     */

   320 	void MapcPlayComplete( TInt aError );

   321 

   322   public: // New Functions 

   323 

   324     /**

   325     * Method to start transaction for saving the data into the SRS.

   326     *

   327     * @since 2.0

   328     * @param aSaveTagClient Callback after we made it or died trying

   329     * @param aTag Tag to be deleted

   330     * @return a fail or success result from processing this method.

   331     */   

   332     MNssCoreSrsDBEventHandler::TNssSrsDBResult 

   333         NSSBeginSaveToSrs( MNssSaveTagClient* aSaveTagClient, CNssTag* aTag );

   334 

   335     /**

   336     * Method to start transaction for deleting tags from SRS and VAS DB.

   337     *

   338     * @since 2.0

   339     * @param aDeleteTagClient Callback after we made it or died trying

   340     * @param aTag Tag to be deleted

   341     * @return a fail or success result from processing this method.

   342     */   

   343     MNssCoreSrsDBEventHandler::TNssSrsDBResult 

   344         NSSBeginDeleteFromSrs( MNssDeleteTagClient* aDeleteTagClient, CNssTag* aTag );

   345 

   346     /**

   347     * Method to commit the transaction to the SRS.

   348     * This is a SYNCHRONOUS method.

   349     * @since 2.0

   350     * @return a fail or success result from processing this method.

   351     */   

   352     MNssCoreSrsDBEventHandler::TNssSrsDBResult CommitSrsChanges();

   353 

   354 

   355     /**

   356     * Method to end the transaction without committing..

   357     * This is a SYNCHRONOUS method.

   358     * @since 2.8

   359     * @return a fail or success result from processing this method.

   360     */   

   361     MNssCoreSrsDBEventHandler::TNssSrsDBResult RollbackSrsChanges();

   362 

   363     /**

   364     * Method to set the Tag ID

   365     * @since 2.0

   366     * @param aTagId a Tag ID 

   367     */   

   368 	void SetTagId( TInt aTagId );

   369 

   370     /**

   371     * Method to return the Tag ID

   372     *

   373     * @since 2.0

   374     * @return the Tag ID.

   375     */   

   376     TInt TagId();

   377 

   378     /**

   379     * Method to return the Grammar ID from the context of the speech item.

   380     *

   381     * @since 2.8

   382     * @return the Grammar ID.

   383     */

   384     TUint32 GrammarId();

   385 

   386     /**

   387     * Method to set the Trained flag for True or False

   388     *

   389     * @since 2.0

   390     * @param aTrained Trained flag

   391     */   

   392 	void SetTrained( TBool aTrained );

   393 

   394     /**

   395     * Method to return the Trained flag

   396     *

   397     * @since 2.0

   398     * @return the Trained flag

   399     */   

   400     TBool Trained();

   401 

   402     /**

   403     * Updates the speech item after training.

   404     *

   405     * @since 2.8

   406     * @param aRuleID Rule ID.

   407     */

   408     void DelayedTrainingComplete( TUint32 aRuleID );

   409 

   410 

   411   private: //function

   412 

   413     /**

   414     * C++ constructor

   415     *

   416     * @param aContext reference to Context object

   417     * @param aPortal reference to SpeechItem Portal object

   418     * @param aTrainer reference to speech item trainer

   419     */   

   420     CNssSpeechItem( CNssContext& aContext, 

   421                     CNssSpeechItemSrsPortal& aPortal, 

   422                     CNssSpeechItemTrainer& aTrainer );

   423 

   424     /**

   425     * Symbian 2nd phase constructor 

   426     *

   427     * @param aRuleID Rule ID value

   428     * @param aText Reference to the TDesc text 

   429     */   

   430     void ConstructL( TUint32 aRuleID, const TDesC& aText );

   431 

   432     /**

   433     * Method to copy utterance data from current to transient values

   434     */   

   435     void CopyUtteranceData();

   436 

   437     /**

   438     * Method to handle the "GetUtteranceDurationEvent" complete from SRS

   439     */   

   440     void DoGetUtteranceDurationCompleteEvent();

   441 

   442     /**

   443     * Method to handle the "PlayEvent" complete from SRS

   444     */   

   445     void DoPlayCompleteEvent();

   446 

   447     /**

   448     * Method to handle the "PlayEvent" fail from SRS

   449     *

   450     * @param aResult - a Result value from the Play operation

   451     */   

   452     void DoPlayFailEvent( TInt aResult );

   453 

   454     /**

   455     * Method to process the SRS play error 

   456     *

   457     * @param aResult the result value from SRS which indicates an error

   458     * @return a converted error code to identify the VAS play error

   459     */   

   460     MNssPlayEventHandler::TNssPlayResult DoPlayResult( TInt aResult );

   461     

   462     /**

   463     * Method to handle the "GetAvailableStorageEvent" complete from SRS

   464     */   

   465     void DoGetAvailableStorageCompleteEvent();

   466 

   467     /**

   468     * Method to handle the "TrainEvent" complete from SRS

   469     */   

   470     void DoTrainCompleteEvent();

   471 

   472     /**

   473     * Method to process the various train failed events from SRS'

   474     *

   475     * @param aResult the result value to indicate an error

   476     */   

   477     void DoTrainFailEvent( TInt aResult );

   478 

   479     /**

   480     * Method to process the SRS train error

   481     *

   482     * @param aResult the result value from SRS which indicates an error

   483     * @return a converted error code to identify the VAS train error

   484     */   

   485     MNssTrainVoiceEventHandler::TNssTrainResult DoTrainResult( TInt aResult );

   486     

   487     /**

   488     * Method to handle the "AddPronunciation" complete from SRS

   489     */   

   490     void DoAddPronunciationCompleteEvent();

   491 

   492     /**

   493     * Method to handle the "AddPronunciation" fail from SRS

   494     *

   495     * @param aResult a Result value from the event

   496     */   

   497     void DoAddPronounciationFailEvent( TInt aResult );

   498     

   499     /**

   500     * Method to handle the "RemoveModel" complete from SRS

   501     */   

   502     void DoRemoveModelCompleteEvent();

   503 

   504     /**

   505     * Method to handle the "RemoveModel" fail from SRS

   506     *

   507     * @param aResult a Result value from the event

   508     */   

   509     void DoRemoveModelFailEvent( TInt aResult );

   510 

   511     /**

   512     * Method to process the SRS DB error 

   513     *

   514     * @param aResult the result value from SRS to indicate an error

   515     * @return an error code to identify the DB error

   516     */   

   517     MNssCoreSrsDBEventHandler::TNssSrsDBResult DoSrsDBResult( TInt aResult );

   518 

   519     /**

   520     * Method to notify the event handler for receiving the Unexpected Event

   521     */  

   522     void NotifyHandlerForUnexpectedEvent();

   523 

   524     /**

   525     * Method to do clean up

   526     */   

   527     void CleanUp();

   528     

   529     /**

   530     * Method to verify whether it is ok to retry

   531     *

   532     * @return ETrue is ok to retry, EFalse stops retry 

   533     */   

   534     TBool DoRetry();

   535  

   536     /**

   537     * This method starts playback with CTtsUtility.

   538     */

   539     void DoPlayL();

   540 

   541     /**

   542     * This method releases resources, which were reserved for playing,

   543     * and updated the state from PlayingStrated to Idle.

   544     */

   545     void CleanPlayback();

   546 

   547     /**

   548     * Makes the callback after playing has completed or failed.

   549     *

   550     * @param Symbian standard error code

   551     */

   552     void MakePlayCallback( TInt aResult );

   553 

   554   private: //data

   555 

   556     // The rule ID.

   557     TUint32 iRuleID;

   558 

   559     // The transient rule ID.

   560     TUint32 iTransientRuleID;

   561 

   562     // The text data.

   563     HBufC* iText;

   564 

   565     // The trained type.

   566     TNssVasCoreConstant::TNssTrainedType iTrainedType;

   567 

   568     // Need to keep track the training state.

   569     TNssSpeechItemConstant::TNssState iState;

   570     TNssSpeechItemConstant::TNssState iOldState;

   571 

   572     // Reference to Context object

   573     CNssContext& iContext;

   574 

   575     // Reference to SRS Portal object.

   576     CNssSpeechItemSrsPortal& iPortal;

   577 

   578     // Reference to SRS Trainer object. Used for delayed text training.

   579     CNssSpeechItemTrainer& iTrainer;

   580 

   581     // Pointer to Play Event Handler object.

   582     MNssPlayEventHandler* iPlayEventHandler; 

   583 

   584     // Pointer to Train Event Handler object

   585 	MNssTrainVoiceEventHandler* iTrainVoiceEventHandler;

   586 

   587     // The Tag ID for internal use by Vas Database,

   588 	TInt iTagId; 

   589 

   590     // The Trained flag for re-training operation

   591     TBool iTrained;

   592 

   593     // The duration for the play utterance

   594     TTimeIntervalMicroSeconds32 iPlayDuration;

   595 

   596     // The flag to identify recovery is in progress

   597     TBool iRecover;

   598 

   599     // Retry counter

   600     TInt iRetry;

   601 

   602     // Memory is allocated for TTS data only when plaing the tag.

   603     // This is because CNssSpeechItem may have thousands of copies.

   604     struct TTtsData

   605         {

   606         // TTS speech style

   607         TTtsStyle iStyle;

   608 

   609         // TTS speech style handle

   610         TTtsStyleID iStyleID;

   611 

   612         // TTS speech segment

   613         TTtsSegment iSegment;

   614 

   615         // TTS player

   616         CNssTtsUtilityWrapper* iTts;

   617 

   618         // Parsed text

   619         CTtsParsedText* iParsedText;

   620 

   621         // Initializes everyting to zero.

   622         TTtsData();

   623         };

   624 

   625     // TTS Data

   626     TTtsData* iTtsData;

   627     

   628     // Cleaned text data where escape characters have been removed

   629     HBufC* iTrimmedText;

   630 };

   631 

   632 #endif // NSSVASCSPEECHITEM_H

   633 

   634 // End of file