/*
* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: Voice command service interfaces, that are private for the
* : vcommand API implementation
*
*/
#ifndef VCOMMANDINTERNALAPI_H
#define VCOMMANDINTERNALAPI_H
#include <e32def.h>
#include <e32cmn.h>
#include <s32strm.h>
#include <vcommandapi.h>
// context for voice commands tags
_LIT( KVoiceCommandContext, "COMMAND" );
/**
* VCommand with a link to the VAS. This link is a command id
* Stored VCommand can be played back
*/
class CStoredVCommand : public CVCommand
{
private:
// suppress inherited constructors by making them private
/**
* Factory function. Create a const snapshop of exe-ui-vastext collection
* @param aText Text to be trained by VAS. Can be of any length, however
* only first KNssVasDbTagName characters will be trained by VAS
* @see KNssVasDbTagName in nssvasdbkonsts.h
* @param aRunnable Executable to be fired when the command is recognized.
* VCommand takes the ownership on the aRunnable
* @param aUi visible strings to be displayed in VC App. VCommand takes
* the ownership on the aUi
*/
static CVCommand* NewL( const TDesC& aText, const CVCRunnable& aRunnable,
const CVCCommandUi& aUi );
/**
* Internalizes the command from stream
* @leave KErrNotSupported if the stream data format is unsupported
* e.g. if it has been written by newer implementation
*/
static CVCommand* NewL( RReadStream &aStream );
public:
// constructors with the commandId
/**
* Factory function. Create a const snapshop of exe-ui-vastext collection
* @param aText Text to be trained by VAS. Can be of any length, however
* only first KNssVasDbTagName characters will be trained by VAS
* @see KNssVasDbTagName in nssvasdbkonsts.h
* @param aRunnable Executable to be fired when the command is recognized.
* VCommand takes the ownership on the aRunnable
* @param aUi visible strings to be displayed in VC App. VCommand takes
* the ownership on the aUi
*/
static CStoredVCommand* NewL( const TDesC& aText, const CVCRunnable& aRunnable,
const CVCCommandUi& aUi, TInt aCommandId );
/**
* Internalizes the command from stream
* @leave KErrNotSupported if the stream data format is unsupported
* e.g. if it has been written by newer implementation
*/
static CStoredVCommand* NewL( RReadStream &aStream, TInt aCommandId );
/**
* @return CommandId
*/
TInt CommandId() const;
/**
* Attempts to play back the text expected to be recognized.
* To be playable command has to be added to CVCommandHandler AND
* then retrieved back
*
* @param aHandler CVCommandHandler where the command is stored
* @todo Consider storing link to CVCommandHandler within the CStoredVCommand
* Pros: No clumsy aHandler argument for the playback
* Pros: No need to remember in which handler the command is stored
* and why specifying storage is needed during the playback
* Cons: In case of internal link the linked handler should still
* exist. It cannot be e.g. destroyed and recreated later even
* if the latter one is using the same VAS
*
* @param aPlayEventHandler Entity that handles the playback callbacks
* @see NssVasMPlayEventHandler.h
*
* @leave KErrBadHandle if the current command has not been retrieved
* from CVCommandHandler (i.e. was not trained for recognition)
* @leave KErrNotFound if this command cannot be found in aHandler
* @leave KErrNotReady @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult
* EVasUnexpectedRequest
* @leave KErrInUse @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult
* EVasInUse
* @leave KErrArgument @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult
* EVasInvalidParameter
* @leave KErrGeneral @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult
* EVasPlayFailed
*/
void PlaySpokenTextL( const CVCommandHandler& aHandler,
MNssPlayEventHandler& aPlayEventHandler ) const;
/**
* Plays back the user-specified alternative spoken text.
* Otherwise is identical to PlaySpokenTextL
* @see PlaySpokenTextL
* @leave KErrNotFound if this command cannot be found in aHandler of if
* it doesn't have a user-specified text
*/
void PlayAlternativeSpokenTextL( const CVCommandHandler& aHandler,
MNssPlayEventHandler& aPlayEventHandler ) const;
/**
* Cancels playback of a spoken or alternative spoken text
* To be playable command has to be added to CVCommandHandler AND
* then retrieved back. After this function neither HandlePlayStarted,
* nor HandlePlayComplete will be called
*
* @param aHandler CVCommandHandler where the command is stored
*
* @leave KErrBadHandle if the current command has not been retrieved
* from CVCommandHandler (i.e. was not trained for recognition)
* @leave KErrNotReady if playback has never been started
*
*/
void CancelPlaybackL( const CVCommandHandler& aHandler ) const;
protected:
/**
* @see CVCommand::ConstructL
*/
void ConstructL( const TDesC& aText, const CVCRunnable& aRunnable,
const CVCCommandUi& aUi, TInt aCommandId );
/**
* @see CVCommand::ConstructL
*/
void ConstructL( RReadStream& aStream, TInt aCommandId );
/**
* Clone itself
* Is used for copying via NewL( CVCommand& aOriginal )
*/
CVCommand* CloneL() const;
private:
TInt iCommandId;
};
/**
* Interface for storing, listing and removing voice commands to/from VAS
*/
class MVCService
{
public:
/**
* Synchronous. Service doesn't take the ownership, but makes an own copy
* Duplicates can be added
* @todo should we check for duplicates and leave with KErrAlreadyExists?
*/
virtual void AddCommandL( const CVCommand& aCommand ) = 0;
/**
* Synchronous. Service doesn't take the ownership, but makes an own copy
* Duplicates can be added
* @todo Should we check for duplicates and leave with KErrAlreadyExists?
* @param aIgnoreErrors If ETrue, even if some commands fail to be trained,
* handler adds all that are trainable
*/
virtual void AddCommandsL( const RVCommandArray& aCommands,
TBool aIgnoreErrors = EFalse ) = 0;
/**
* Synchronous. Removes the command from the system
* @param aCommand Reference to the command to be removed. Existing commands are
* compared against aCommand. All the matches are removed from VAS
* @leave KErrNotFound No such command
*/
virtual void RemoveCommandL( const CVCommand& aCommand ) = 0;
/**
* Synchronous.
* @param aCommands Reference to the list of commands to be removed. Existing commands are
* compared against aCommands items. All the matches are removed from VAS
* @param aIgnoreErrors If ETrue, even if some commands fail to be removed,
* handler will remove as many as possible
*/
virtual void RemoveCommandsL( const RVCommandArray& aCommands,
TBool aIgnoreErrors = EFalse ) = 0;
/**
* Synchronous
* @return an array of the commands in the system
* Ownership of the array is transfered to the client
* The returned CVCommandArray contains copies of all the
* commands currently stored in this handler
*/
virtual CVCommandArray* ListCommandsL() = 0;
/**
* This method is not intended to be called directly.
* Use CVCommand::PlaySpokenTextL instead
* @see CVCommand::PlaySpokenTextL
* @see CStoredVCommand::PlaySpokenTextL
*/
virtual void PlaySpokenTextL( const CStoredVCommand& aCommand,
MNssPlayEventHandler& aPlayEventHandler ) = 0;
/**
* This method is not intended to be called directly.
* Use CVCommand::PlayAlternativeSpokenTextL instead
* @see CVCommand::PlayAlternativeSpokenTextL
* @see CStoredVCommand::PlayAlternativeSpokenTextL
*/
virtual void PlayAlternativeSpokenTextL( const CStoredVCommand& aCommand,
MNssPlayEventHandler& aPlayEventHandler ) = 0;
/**
* This method is not intended to be called directly.
* Use CVCommand::CancelPlaybackL instead
* @see CVCommand::CancelPlaybackL
* @see CStoredVCommand::CancelPlaybackL
*/
virtual void CancelPlaybackL( const CStoredVCommand& aCommand ) = 0;
virtual ~MVCService() {};
};
#endif // VCOMMANDINTERNALAPI_H