srsf/vcommandhandler/inc/vcommandservices.h
changeset 0 bf1d17376201
equal deleted inserted replaced
-1:000000000000 0:bf1d17376201
       
     1 /*
       
     2 * Copyright (c) 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:  Engine, that links the VCommand application to VAS
       
    15 *
       
    16 */
       
    17 
       
    18 
       
    19  
       
    20 #ifndef VCOMMANDSERVICES_H
       
    21 #define VCOMMANDSERVICES_H
       
    22 
       
    23 #include <nssvasmrrd.h>
       
    24 #include <nssvasctrainingparameters.h>
       
    25 #include <vcommandapi.h>
       
    26 #include <nssvasmgettagclient.h>  // For MNssTagListArray
       
    27 #include <nssvasmplayeventhandler.h>
       
    28 #include "vcommandinternalapi.h"
       
    29 #include "intpropertywatcher.h"
       
    30 
       
    31 // Forward declarations
       
    32 class CNssVASDBMgr;
       
    33 class MNssContextMgr;
       
    34 class MNssTagMgr;
       
    35 class MNssTag;
       
    36 class CTagPlayer;
       
    37 
       
    38 /**
       
    39 * Key for sorting CArrayPtr<MNssTag> by the value of the
       
    40 * first element of the RRD IntArray
       
    41 */
       
    42 class TVCommandTagPtrArrayKey : public TKeyArrayFix
       
    43     {
       
    44     public:
       
    45         inline TVCommandTagPtrArrayKey( TKeyCmpNumeric aType)
       
    46             :TKeyArrayFix( 0, aType ) {}
       
    47             virtual TAny* At( TInt aIndex ) const;
       
    48         };
       
    49 
       
    50 /**
       
    51 * Engine, that links the VCommand application to VAS
       
    52 * @todo isolate the MNssPlayEventHandler dependency
       
    53 */
       
    54 class CVCommandService : public CBase, public MVCService, public MNssPlayEventHandler, 
       
    55                          private MIntChangeNotifiable
       
    56                         
       
    57     {
       
    58     public:
       
    59         // Construction/destruction
       
    60 		/**
       
    61 		 * @param aObserver Listener to be notified whenever the VCommand set is changed
       
    62          *	 by *another* instance of CVCommandHandler. I.e. lets the client know if
       
    63          *	 his understanding of the VCommand set is up to date
       
    64 	     */
       
    65         static CVCommandService* NewL( MVCommandHandlerObserver* aObserver = NULL );
       
    66         
       
    67         virtual ~CVCommandService();
       
    68 
       
    69         // From the MVCService
       
    70         
       
    71         /**
       
    72         * Synchronous. Service doesn't take the ownership, but makes an own copy
       
    73         * Duplicates can be added
       
    74         * @todo Should we check for duplicates and leave with KErrAlreadyExists?
       
    75         * @leave KErrLocked if there is an ongoing operation started by the same thread
       
    76         */
       
    77         void AddCommandL( const CVCommand& aCommand );
       
    78         
       
    79         /**
       
    80         * Synchronous. Service doesn't take the ownership, but makes an own copy
       
    81         * Duplicates can be added
       
    82         * @todo Should we check for duplicates and leave with KErrAlreadyExists?
       
    83         * @param aIgnoreErrors If ETrue, even if some commands fail to be trained,
       
    84         *        handler adds all that are trainable
       
    85         * @leave KErrLocked if there is an ongoing operation started by the same thread
       
    86         */
       
    87         void AddCommandsL( const RVCommandArray& aCommands, TBool aIgnoreErrors = EFalse );
       
    88         
       
    89         /**
       
    90         * Synchronous. Removes the command from the system
       
    91         * @param aCommand Reference to the command to be removed. Existing commands are
       
    92         *		 compared against aCommand. All the matches are removed from VAS
       
    93         * @leave KErrNotFound No such command
       
    94         * @leave KErrLocked if there is an ongoing operation started by the same thread
       
    95         */
       
    96         void RemoveCommandL( const CVCommand& aCommand );
       
    97         
       
    98         /**
       
    99         * Synchronous. 
       
   100         * @param aCommands Reference to the list of commands to be removed. Existing commands are
       
   101         *		 compared against aCommands items. All the matches are removed from VAS
       
   102         * @param aIgnoreErrors If ETrue, even if some commands fail to be removed,
       
   103         *        handler will remove as many as possible
       
   104         * @leave KErrLocked if there is an ongoing operation started by the same thread
       
   105         */
       
   106         void RemoveCommandsL( const RVCommandArray& aCommands, TBool aIgnoreErrors = EFalse );
       
   107 
       
   108         /**
       
   109         * Synchronous
       
   110         * @leave KErrLocked if there is an ongoing operation started by the same thread
       
   111         * @return an array of the commands in the system
       
   112         *         Ownership of the array is transfered to the client
       
   113         *         The returned CVCommandArray contains copies of all the 
       
   114         *         commands currently stored in this handler
       
   115         */
       
   116         CVCommandArray* ListCommandsL();
       
   117         
       
   118         /**
       
   119         * Asynchronous
       
   120         * Attempts to play back the text expected to be recognized. 
       
   121         * To be playable command has to be added to CVCommandHandler AND
       
   122         * then retrieved back. This function is asynchronous
       
   123         *
       
   124         * @param aPlayEventHandler Entity that handles the playback callbacks
       
   125         * @see NssVasMPlayEventHandler.h
       
   126         *
       
   127         * @leave KErrBadHandle if the current command has not been retrieved 
       
   128         *        from CVCommandHandler (i.e. was not trained for recognition)
       
   129         * @leave KErrNotFound if this command cannot be found in aHandler
       
   130         * @leave KErrNotReady @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult 
       
   131         *                                              EVasUnexpectedRequest
       
   132         * @leave KErrInUse @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult 
       
   133         *                                              EVasInUse
       
   134         * @leave KErrArgument @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult 
       
   135         *                                              EVasInvalidParameter
       
   136         * @leave KErrGeneral @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult 
       
   137         *                                             EVasPlayFailed
       
   138         * @leave KErrLocked if there is an ongoing operation started by the same thread
       
   139         */
       
   140         void PlaySpokenTextL( const CStoredVCommand& aCommand, 
       
   141                                       MNssPlayEventHandler& aPlayEventHandler );
       
   142         
       
   143         /**
       
   144         * Asynchronous
       
   145         * Plays back the user-specified alternative spoken text. 
       
   146         * Otherwise is identical to PlaySpokenTextL
       
   147         * @see PlaySpokenTextL
       
   148         * @leave KErrNotFound if this command cannot be found in aHandler of if 
       
   149         *        it doesn't have a user-specified text
       
   150         * @leave KErrLocked if there is an ongoing operation started by the same thread
       
   151         */ 
       
   152         void PlayAlternativeSpokenTextL( const CStoredVCommand& aCommand, 
       
   153                                       MNssPlayEventHandler& aPlayEventHandler );
       
   154         
       
   155         /**
       
   156         * This method is not intended to be called directly. 
       
   157         * Use CVCommand::CancelPlaybackL instead
       
   158         * @see CVCommand::CancelPlaybackL
       
   159         * @see CStoredVCommand::CancelPlaybackL
       
   160         */
       
   161         void CancelPlaybackL( const CStoredVCommand& aCommand );
       
   162         
       
   163     public:
       
   164     
       
   165         // From MNssPlayEventHandler                                      
       
   166         /**
       
   167         * The HandlePlayStarted method is a virtual method implemented by the
       
   168         * client and is called when play is started
       
   169         * @param aDuration - the duration of the utterance data
       
   170         */       
       
   171         virtual void HandlePlayStarted( TTimeIntervalMicroSeconds32 aDuration );
       
   172 
       
   173         /**
       
   174         * The HandlePlayComplete method is a virtual method implemented by the
       
   175         * client and is called when play is completed
       
   176         * @param aErrorCode EVasErrorNone if playing was successfull
       
   177         */       
       
   178         virtual void HandlePlayComplete( TNssPlayResult aErrorCode );
       
   179                                       
       
   180     private:
       
   181         CVCommandService( MVCommandHandlerObserver* aObserver );
       
   182         
       
   183         void ConstructL();
       
   184         
       
   185         /**
       
   186         * Returns the VCommand context. Creates one on demand if none exists yet
       
   187         * @return VCommand context. Ownership is transfered to the client
       
   188         */
       
   189         MNssContext* GetVCommandContextLC() const;
       
   190         
       
   191         /**
       
   192         * Constructs a set of new VAS tags from a command and a context. 
       
   193         * Does not save to VAS, just creates. Ownership on the created tag is 
       
   194         * passed to the client
       
   195         */
       
   196         CArrayPtr<MNssTag>* CreateTagsLC2( const CVCommand& aCommand, 
       
   197                                            const MNssContext& aContext );
       
   198         
       
   199         /**
       
   200         * Constructs training related parameters. Like language to be used
       
   201         * @leave negated TNssSpeechItemResult
       
   202         * @todo Is it ok to mix system-wide codes with the TNssSpeechItemResult codes
       
   203         */
       
   204         CNssTrainingParameters* ConstructTrainingParametersLC() const;
       
   205 
       
   206         /**
       
   207 		* Retrieves the list of tags for a given context. Synchronous.
       
   208 		* Leaves two objects on the cleanup stack!
       
   209 		* First PopAndDestroy will ResetAndDestroy content
       
   210 		* Second one will destroy the MNsstagListArray itself
       
   211 		*/
       
   212         MNssTagListArray* GetTagListLC2( const MNssContext& aContext ) const;
       
   213         
       
   214         /**
       
   215 		* Retrieves the list of tags for a given context and voice command id. 
       
   216 		* Synchronous. Leaves two objects on the cleanup stack!
       
   217 		* First PopAndDestroy will ResetAndDestroy content
       
   218 		* Second one will destroy the MNsstagListArray itself
       
   219 		*/
       
   220         MNssTagListArray* GetTagListLC2( const MNssContext& aContext, TInt aCommandId ) const;
       
   221         
       
   222         /**
       
   223         * Resets iCommands and fills them with the commands from VAS
       
   224         */
       
   225         void RefreshCommandListL();
       
   226         
       
   227         /**
       
   228         * Marks the iCommands as an invalid reflection of the VAS content.
       
   229         * To make iCommands reflect the real VAS content a call to 
       
   230         * RefreshCommandsL is needed
       
   231         */
       
   232         void InvalidateCacheL();
       
   233         
       
   234         /**
       
   235         * Marks the iCommands as the valid reflection of the VAS content.
       
   236         */
       
   237         void MarkCacheValidL();
       
   238         
       
   239         /**
       
   240         * Tells if the iCommands reflect the content of the VAS DB correctly
       
   241         * @return ETrue if the cache is valid, EFalse otherwise
       
   242         */
       
   243         TBool IsCacheValidL();
       
   244         
       
   245         /**
       
   246         * Generates new command id to be used for identifying voice tags, that
       
   247         * belong to the same VCommand
       
   248         */
       
   249         TInt NewCommandIdL();
       
   250         
       
   251         /** 
       
   252         * Sets the given aId as a VCommand id for all the tags in the given list
       
   253         * This id is set as a first RRD int element of all the given MNssTags.
       
   254         * If the RRD int array has no elements yet, one element is added
       
   255         */
       
   256         void SetVCommandIdL( CArrayPtr<MNssTag>& aTags, TInt aId ) const;
       
   257         
       
   258         /**
       
   259         * Searches vcommand tags for the tag, that corresponds to the given
       
   260         * commandId and is trained against the given text
       
   261         * @param aCommandId Command id to search for
       
   262         * @param aText
       
   263         * @return ANY of the voice tags corresponding to the given aCommandId
       
   264         *         and aText. Typically there will be one such tag only. However,
       
   265         *         if there are several it is not specified which one will be 
       
   266         *         returned
       
   267         * @return NULL if no satisfying tag is found
       
   268         */
       
   269         MNssTag* TagByCommandIdTextL( TInt aCommandId, const TDesC& aText );
       
   270         
       
   271         /**
       
   272         * Synchronous. Service doesn't take the ownership, but makes an own copy
       
   273         * Duplicates can be added
       
   274         * Is not the atomic operation
       
   275         * @see AddCommandsL
       
   276         */
       
   277         void DoAddCommandsL( const RVCommandArray& aCommands, 
       
   278                              TBool aIgnoreErrors = EFalse );
       
   279 
       
   280 		/**
       
   281 		 * Synchronous
       
   282 		 * @see RemoveCommandsL
       
   283 		 */                             
       
   284         void DoRemoveCommandsL( const RVCommandArray& aCommands,
       
   285         						TBool aIgnoreErrors = EFalse );
       
   286         
       
   287         /**
       
   288         * Starts the section of the code, that can be simultaneously executed
       
   289         * only by a single instance of this class. Other instances have to wait
       
   290         * Same as starting the Java "synchronized" method. Puts the function
       
   291         * EndAtomicOperation to cleanup stack to make the use leave safe. Subsequent
       
   292         * call to CleanupStack::PopAndDestroy will run EndAtomicOperation.
       
   293         */
       
   294         void StartAtomicOperationLC();
       
   295         
       
   296         /**
       
   297         * Ends the section of the code, that can be simultaneously executed
       
   298         * only by a single instance of this class. Other instances have to wait
       
   299         * Same as exiting the Java "synchronized" method
       
   300         * @leave KErrNotReady if atomic operation hasn't been started
       
   301         */
       
   302         void EndAtomicOperation();
       
   303         
       
   304         /**
       
   305         * Runs the EndAtomicOperation when calling CleanupStack::PopAndDestroy after
       
   306         * a call to StartAtomicOperationLC
       
   307         */ 
       
   308         static void CleanupEndAtomicOperation( TAny* aService );
       
   309         
       
   310         /**
       
   311         * Creates and pushes to cleanup stack a TCleanupItem that calls
       
   312         * EndAtomicOperation when CleanupStack::PopAndDestroy is called
       
   313         */
       
   314         void CreateAndPushEndAtomicCleanupItemL();
       
   315         
       
   316     private:
       
   317         // From MIntChangeNotifiable
       
   318         /**
       
   319          * Is called by the P&S property watcher to let this object know that
       
   320          * the global tick property has been changed
       
   321          */
       
   322         void IntValueChanged( TInt aNewValue );
       
   323         
       
   324     private:
       
   325         // Main access point to VAS
       
   326         CNssVASDBMgr*               iVasDbManager;      // Owned
       
   327         MNssTagMgr*                 iTagManager;        // Not owned.
       
   328         
       
   329         // Stores the local tick count. When local tick count
       
   330         // is equal to the global tick count, this object is aware
       
   331         // of all the VAS updates
       
   332         TInt						iLocalTickCount;
       
   333         
       
   334         // Commands in the system
       
   335         RVCommandArray              iCommands;        
       
   336         
       
   337         // Maximal used command id
       
   338         TInt                        iMaxCommandId;
       
   339         
       
   340         // Utility that plays back the voice commands
       
   341         CTagPlayer*                 iTagPlayer;
       
   342         
       
   343         RMutex                      iLock;
       
   344         
       
   345         // Client that should be notified about the playback events
       
   346         MNssPlayEventHandler*       iPlaybackHandler;
       
   347         
       
   348         // Is used to check the global "tick count", i.e.
       
   349         // number of operations performed by this
       
   350         // and another instances of VCommand handler
       
   351         RProperty                   iGlobalTickProperty;
       
   352         
       
   353         MVCommandHandlerObserver*	iObserver;
       
   354         
       
   355         // Watches for the global tick property to let the services observer
       
   356         // know when the local cache is out of date
       
   357         CIntPropertyWatcher*        iGlobalTickWatcher;
       
   358         
       
   359         // Last time when this instance set the global tick count
       
   360         // it was this value.
       
   361         // Is used to distinguish own global tick changes from external global tick changes
       
   362         TInt                        iLastSetGlobalTickCount;
       
   363     };
       
   364 
       
   365 #endif // VCOMMANDSERVICES_H