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:  Voice command with the link to the VAS

    15 *

    16 */

    17 

    18 

    19 

    20 #include <e32def.h>

    21 #include "vcommandinternalapi.h"

    22 #include "rubydebug.h"

    23 

    24  /**

    25 * Factory function. Create a const snapshop of exe-ui-vastext collection

    26 * @param aText Text to be trained by VAS. Can be of any length, however

    27 *        only first KNssVasDbTagName characters will be trained by VAS

    28 * @see KNssVasDbTagName in nssvasdbkonsts.h

    29 * @param aRunnable Executable to be fired when the command is recognized. 

    30 *        VCommand takes the ownership on the aRunnable

    31 * @param aUi visible strings to be displayed in VC App. VCommand takes 

    32 *        the ownership on the aUi

    33 */

    34 CStoredVCommand* CStoredVCommand::NewL( const TDesC& aText, const CVCRunnable& aRunnable, 

    35                                  const CVCCommandUi& aUi, TInt aCommandId )

    36     {

    37     CStoredVCommand* self = new (ELeave) CStoredVCommand;

    38     CleanupStack::PushL( self );

    39     self->ConstructL( aText, aRunnable, aUi, aCommandId );

    40     CleanupStack::Pop( self );

    41     return self;

    42     }

    43 

    44 /** 

    45 * Internalizes the command from stream 

    46 * @leave KErrNotSupported if the stream data format is unsupported

    47 *        e.g. if it has been written by newer implementation

    48 */

    49 CStoredVCommand* CStoredVCommand::NewL( RReadStream &aStream, TInt aCommandId )

    50     {

    51     CStoredVCommand* self = new (ELeave) CStoredVCommand;

    52     CleanupStack::PushL( self );

    53     self->ConstructL( aStream, aCommandId );

    54     CleanupStack::Pop( self );

    55     return self;

    56     }

    57     

    58 /**

    59 * @see CVCommand::ConstructL

    60 */ 

    61 void CStoredVCommand::ConstructL( const TDesC& aText, const CVCRunnable& aRunnable, 

    62                  const CVCCommandUi& aUi, TInt aCommandId ) 

    63     {

    64     CVCommand::ConstructL( aText, aRunnable, aUi );

    65     iCommandId = aCommandId;

    66     }

    67     

    68 /**

    69 * @see CVCommand::ConstructL

    70 */

    71 void CStoredVCommand::ConstructL( RReadStream& aStream, TInt aCommandId )

    72     {

    73     CVCommand::ConstructL( aStream );

    74     iCommandId = aCommandId;

    75     }

    76     

    77 /**

    78 * Clone itself

    79 * Is used for copying via NewL( CVCommand& aOriginal )

    80 */

    81 CVCommand* CStoredVCommand::CloneL() const

    82     {

    83     CVCommand* clone = CStoredVCommand::NewL( SpokenText(), Runnable(), 

    84                                                 CommandUi(), CommandId() );

    85     return clone;

    86     }

    87 

    88 /**

    89 * @return CommandId

    90 */

    91 TInt CStoredVCommand::CommandId() const

    92     {

    93     return iCommandId;

    94     }

    95 

    96 /**

    97 * Asynchronous

    98 * Attempts to play back the text expected to be recognized. 

    99 * To be playable command has to be added to CVCommandHandler AND

   100 * then retrieved back

   101 *

   102 * @param aHandler CVCommandHandler where the command is stored

   103 * @todo Consider storing link to CVCommandHandler within the CStoredVCommand

   104 *       Pros: No clumsy aHandler argument for the playback

   105 *       Pros: No need to remember in which handler the command is stored

   106 *             and why specifying storage is needed during the playback

   107 *       Cons: In case of internal link the linked handler should still

   108 *             exist. It cannot be e.g. destroyed and recreated later even

   109 *             if the latter one is using the same VAS

   110 *

   111 * @param aPlayEventHandler Entity that handles the playback callbacks

   112 * @see NssVasMPlayEventHandler.h

   113 *

   114 * @leave KErrBadHandle if the current command has not been retrieved 

   115 *        from CVCommandHandler (i.e. was not trained for recognition)

   116 * @leave KErrNotFound if this command cannot be found in aHandler

   117 * @leave KErrNotReady @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult 

   118 *                                              EVasUnexpectedRequest

   119 * @leave KErrInUse @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult 

   120 *                                              EVasInUse

   121 * @leave KErrArgument @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult 

   122 *                                              EVasInvalidParameter

   123 * @leave KErrGeneral @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult 

   124 *                                             EVasPlayFailed

   125 */

   126 void CStoredVCommand::PlaySpokenTextL( const CVCommandHandler& aHandler, 

   127                           MNssPlayEventHandler& aPlayEventHandler ) const

   128     {

   129     RUBY_DEBUG_BLOCK( "CStoredVCommand::PlaySpokenTextL" );

   130     aHandler.PlaySpokenTextL( *this, aPlayEventHandler );

   131     }

   132 

   133 /**

   134 * Plays back the user-specified alternative spoken text. 

   135 * Otherwise is identical to PlaySpokenTextL

   136 * @see PlaySpokenTextL

   137 * @leave KErrNotFound if this command cannot be found in aHandler of if 

   138 *        it doesn't have a user-specified text

   139 */     

   140 void CStoredVCommand::PlayAlternativeSpokenTextL( const CVCommandHandler& aHandler, 

   141                           MNssPlayEventHandler& aPlayEventHandler ) const

   142     {

   143     RUBY_DEBUG_BLOCK( "CStoredVCommand::PlaySpokenTextL" );

   144     aHandler.PlayAlternativeSpokenTextL( *this, aPlayEventHandler );

   145     }

   146     

   147 /**

   148 * Cancels playback of a spoken or alternative spoken text

   149 * To be playable command has to be added to CVCommandHandler AND

   150 * then retrieved back. After this function neither HandlePlayStarted,

   151 * nor HandlePlayComplete will be called

   152 *

   153 * @param aHandler CVCommandHandler where the command is stored

   154 *

   155 * @leave KErrBadHandle if the current command has not been retrieved 

   156 *        from CVCommandHandler (i.e. was not trained for recognition)

   157 * @leave KErrNotReady if playback has never been started

   158 *

   159 */

   160 void CStoredVCommand::CancelPlaybackL( const CVCommandHandler& aHandler ) const

   161     {

   162     aHandler.CancelPlaybackL( *this );

   163     }

   164     

   165 //End of file