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:  Implementation of the VCommand class

    15 *

    16 */

    17 

    18 

    19 

    20 #include <e32def.h>

    21 #include <vcommandapi.h>

    22 #include "rubydebug.h"

    23 

    24 /**

    25 * The version of the streamed data protocol

    26 * It is rather likely, that the format of the data streamed changes in the future.

    27 * Using the protocol version, the code can check if it knows how to parse the 

    28 * input stream

    29 */

    30 const TInt32 KVCommandProtocolVersion = 1;

    31 

    32 /**

    33 * Create a const snapshop of exe-ui-vastext collection

    34 * @param aText Text to be trained by VAS. No longer, than KMaxVCTextLength. 

    35 *        CVCommand doesn't take the ownership

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

    37 *        VCommand doesn't take the ownership

    38 * @param aUi visible strings to be displayed in VC App. 

    39 *        VCommand doesn't take the ownership

    40 */

    41 EXPORT_C CVCommand* CVCommand::NewL( const TDesC& aText, const CVCRunnable& aRunnable, 

    42                             const CVCCommandUi& aUi )

    43     {

    44     RUBY_DEBUG_BLOCKL( "CVCCommand::NewL with args" );

    45     CVCommand* self = new (ELeave) CVCommand;

    46     CleanupStack::PushL( self );

    47     self->ConstructL( aText, aRunnable, aUi );

    48     CleanupStack::Pop( self );

    49     return self;

    50     }

    51     

    52 /** 

    53 * Internalizes the command from stream 

    54 */

    55 EXPORT_C CVCommand* CVCommand::NewL( RReadStream &aStream )

    56     {

    57     CVCommand* self = new (ELeave) CVCommand;

    58     CleanupStack::PushL( self );

    59     self->ConstructL( aStream );

    60     CleanupStack::Pop( self );

    61     return self;    

    62     }

    63 

    64 EXPORT_C CVCommand* CVCommand::NewL( const CVCommand& aOriginal )

    65     {

    66     // Original knows better how to copy itself

    67     return aOriginal.CloneL();    

    68     }

    69 

    70 void CVCommand::ConstructL( RReadStream &aStream )

    71 	{

    72 	TInt32 ver;

    73     aStream >> ver;

    74     __ASSERT_ALWAYS( ver == KVCommandProtocolVersion, User::Leave( KErrNotSupported  ) );

    75     iSpokenText = HBufC::NewL( aStream.ReadInt32L() );

    76     TPtr pSpokenText = iSpokenText->Des();

    77     aStream >> pSpokenText;

    78     iRunnable = CVCRunnable::NewL( aStream );

    79     iCommandUi = CVCCommandUi::NewL( aStream );

    80 	}

    81 	

    82 void CVCommand::ConstructL( const TDesC& aText, const CVCRunnable& aRunnable, 

    83                             const CVCCommandUi& aUi )

    84     {

    85     __ASSERT_ALWAYS( aText.Length() > 0, User::Leave( KErrUnderflow ) );

    86     iSpokenText = HBufC::NewL( aText.Length() );

    87     *iSpokenText = aText;

    88   	iRunnable = CVCRunnable::NewL( aRunnable );

    89     iCommandUi = CVCCommandUi::NewL( aUi );    

    90     }

    91 	

    92 	

    93 EXPORT_C CVCommand::~CVCommand()

    94     {

    95     delete iCommandUi;

    96     delete iRunnable;

    97     delete iSpokenText;

    98     }

    99 

   100 CVCommand* CVCommand::CloneL() const

   101     {

   102     CVCommand* clone = CVCommand::NewL( SpokenText(), Runnable(), CommandUi() );

   103     return clone;

   104     }

   105     

   106 /**

   107 * Saves the command to stream 

   108 * Format: <protocol version: int32><SpokenTextLength: int32><SpokenText descriptor>

   109 *         <runnable><commandui>

   110 */

   111 EXPORT_C void CVCommand::ExternalizeL( RWriteStream &aStream ) const

   112     {

   113     aStream << KVCommandProtocolVersion;

   114     aStream << static_cast<TInt32>( iSpokenText->Length() );

   115     aStream << *iSpokenText;

   116     aStream << *iRunnable;

   117     aStream << *iCommandUi;

   118     }

   119     

   120 EXPORT_C TBool CVCommand::operator==( const CVCommand& aCommand ) const

   121     {

   122     return (

   123             ( *iSpokenText == aCommand.SpokenText() ) &&

   124             ( *iRunnable == aCommand.Runnable() ) &&

   125             ( *iCommandUi == aCommand.CommandUi() ) 

   126            );

   127     

   128     }	

   129 

   130 

   131 /**

   132 * @return the Runnable component of the command

   133 */

   134 EXPORT_C const CVCRunnable& CVCommand::Runnable() const

   135     {

   136     return *iRunnable;

   137     }

   138 

   139 /**

   140 * @return the UI-related component of the command

   141 */

   142 EXPORT_C const CVCCommandUi& CVCommand::CommandUi() const

   143     {

   144     return *iCommandUi;

   145     }

   146 

   147 /**

   148 * @return the text, that user is expected to pronounce

   149 */

   150 EXPORT_C const TDesC& CVCommand::SpokenText() const

   151     {

   152     return *iSpokenText;

   153     }

   154     

   155 /**

   156 * @return the user specified text, that user can pronounce to

   157 *         recognize the command. Is always identical to the 

   158 *         CVCommandUi::UserText()

   159 *         Can be KNullDesC

   160 */

   161 EXPORT_C const TDesC& CVCommand::AlternativeSpokenText() const

   162     {

   163     return iCommandUi->UserText();

   164     }

   165     

   166 /**

   167 * Asynchronous

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

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

   170 * then retrieved back

   171 *

   172 * @param aHandler CVCommandHandler where the command is stored

   173 * @todo Consider storing link to CVCommandHandler within the CVCommand (CStoredVCommand)

   174 *       Pros: No clumsy aHandler argument for the playback

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

   176 *             and why specifying storage is needed during the playback

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

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

   179 *             if the latter one is using the same VAS

   180 *

   181 * @param aPlayEventHandler Entity that handles the playback callbacks

   182 * @see NssVasMPlayEventHandler.h

   183 *

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

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

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

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

   188 *                                              EVasUnexpectedRequest

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

   190 *                                              EVasInUse

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

   192 *                                              EVasInvalidParameter

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

   194 *                                             EVasPlayFailed

   195 */

   196 EXPORT_C void CVCommand::PlaySpokenTextL( const CVCommandHandler& /*aHandler*/, 

   197                           MNssPlayEventHandler& /*aPlayEventHandler*/ ) const

   198     {

   199     RUBY_DEBUG_BLOCK( "CVCommand::PlaySpokenTextL" );

   200     RUBY_ERROR0( "Attempt to play never added command" );

   201     User::Leave( KErrBadHandle );

   202     }

   203 

   204 /**

   205 * Asynchronous

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

   207 * Otherwise is identical to PlaySpokenTextL

   208 * @see PlaySpokenTextL

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

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

   211 */     

   212 EXPORT_C void CVCommand::PlayAlternativeSpokenTextL( const CVCommandHandler& /*aHandler*/, 

   213                           MNssPlayEventHandler& /*aPlayEventHandler*/ ) const

   214     {

   215     RUBY_DEBUG_BLOCK( "CVCommand::PlaySpokenTextL" );

   216     RUBY_ERROR0( "Attempt to play never added command" );

   217     User::Leave( KErrBadHandle );

   218     }

   219     

   220 /**

   221 * Cancels playback of a spoken or alternative spoken text

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

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

   224 * nor HandlePlayComplete will be called

   225 *

   226 * @param aHandler CVCommandHandler where the command is stored

   227 *

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

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

   230 * @leave KErrNotReady if playback has never been started

   231 *

   232 */

   233 EXPORT_C void CVCommand::CancelPlaybackL( const CVCommandHandler& /*aHandler*/ ) const

   234     {

   235     RUBY_DEBUG_BLOCK( "CVCommand::CancelPlaybackL" );

   236     RUBY_ERROR0( "CVCommand::CancelPlaybackL Attempt to cancel playback of the command\

   237                   never added to the VCommandHandler" );

   238     User::Leave( KErrBadHandle );

   239     }

   240 

   241 /**

   242  * Tells if all non user-changeable parts of aCommand are equal to this command

   243  * @return ETrue if equal, EFalse otherwise

   244  */

   245 EXPORT_C TBool CVCommand::EqualNonUserChangeableData( const CVCommand& aCommand ) const

   246     {

   247     if( SpokenText() != aCommand.SpokenText() ) return EFalse;

   248     if( !(Runnable() == aCommand.Runnable() ) ) return EFalse;

   249     

   250     return CommandUi().EqualNonUserChangeableData( aCommand.CommandUi() );

   251     }

   252     

   253 //End of file