--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/srsf/vcommandhandler/inc/vcommandinternalapi.h Wed Sep 01 12:29:17 2010 +0100
@@ -0,0 +1,246 @@
+/*
+* 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
\ No newline at end of file