/*

* 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

*

*/

#ifndef VCOMMANDAPI_H

#define VCOMMANDAPI_H

#include <e32def.h>

#include <e32cmn.h>

#include <s32strm.h>

#include <nssvasmrrd.h>  // For KNssVASMAXRRDTextLength only

/** 

* Maximal length of the exe arguments string

* @todo If longer arguments needed, reengineer the storage scheme. 

*       Currently argument string has to fit into the VAS DB rrdtext column

*       @see CTagCommandConverter

*/

const TInt KMaxVCArgumentLength = KNssVASMAXRRDTextLength;

class MNssPlayEventHandler;

class CStoredVCommand;

class MVCService;

class CVCommandHandler;

class CGulIcon;

/**

 * Container for the voice command folder information. Note that every command can

 * have its own folder information

 */

class CVCFolderInfo : public CBase

    {

    public:

        /**

         * This object does not take an ownership of the passed descriptors, 

         * but makes own copies. 

         * 

         * @param aTitle Folder title. It is shown at the top of the screen,

         *        when the folder is opened in the VCommand application

         * @param aListedName Version of a title shown when the folder is

         *        is displayed in the list of VCommands in the VCommand app

         * @param aHelpTopicId Topic to open when help is requested for the 

         *        given folder

         * @param aIconIndex Zero based index of the folder icon in the folder icons mbm file

         *        each index correspods to two images - the actual icon and its mask

         * @param aIconFile Mbm file where the icons are obtained from. If KNullDesC, 

         * 		  the default icon file is used

         * 

         */

        IMPORT_C static CVCFolderInfo* NewL( const TDesC& aTitle,

                const TDesC& aListedName, TUint32 aHelpTopicId, TUint aIconIndex,

                const TDesC& aIconFile = KNullDesC );

        /**

         * Constructs the folder information from stream

         * @leave KErrNotSupported if the stream data format is unsupported

         */

        IMPORT_C static CVCFolderInfo* NewL( RReadStream& aStream );

        /**

         * Cloning constructor

         */

        IMPORT_C static CVCFolderInfo* NewL( const CVCFolderInfo& aOriginal );

        IMPORT_C ~CVCFolderInfo();

        /** 

        * Saves the folder information to stream.

        * Descriptor components are saved as <length><descriptor> pairs, where 

        * <length> is TInt32 and <descriptor> is the default descriptor represetation

        */

        IMPORT_C void ExternalizeL( RWriteStream &aStream ) const;

        /**

         * Returns folder title. It is shown at the top of the screen,

         *        when the folder is opened in the VCommand application

         */

        IMPORT_C const TDesC& Title() const;

        /**

         * Version of a title shown when the folder is

         * is displayed in the list of VCommands in the VCommand app

         */

        IMPORT_C const TDesC& ListedName() const;

        IMPORT_C TUint32 HelpTopicId() const;

	/**

        * Creates an icon to represent this folder. Works only if CEikonEnv is available

	* @return Icon for the folder

	*/

	IMPORT_C CGulIcon* IconLC() const;

        IMPORT_C TBool operator==( const CVCFolderInfo& aFolderInfo ) const;

    protected:

        CVCFolderInfo( TUint32 aHelpTopicId, TUint aIconIndex );

        // unhiding inherited parameterless constructor

        CVCFolderInfo() {}

        /**

         * Zero based index of the folder icon in the icon file

         * @see IconFile

         */

        TUint IconIndex() const;

        /**

         * Full file name of the file name, where the folder icon is obtained from

         * Is always no longer, than KMaxFileName

         * If KNullDesC is returned, the default icon file is used

         */

        TDesC& IconFile() const;

    private:

        /** @see NewL */

        void ConstructL( const TDesC& aTitle, 

                         const TDesC& aListedName,

                         const TDesC& aIconFile );

        void ConstructL( RReadStream& aStream );

    private:

        HBufC* iTitle;

        HBufC* iListedName;

        HBufC* iIconFile;

        TUint32 iHelpTopicId;

        TUint iIconIndex;

    };

/** 

* Container for VC app specific "human-visible" parts of the voice command:

* tooltip, displayable text, folder, icon, etc

*/ 

class CVCCommandUi : public CBase

    {

    public:

        /**

        * This object does not take an ownership of the passed descriptors, 

        * but makes own copies. 

        * 

        * @param aWrittenText Text to display

        * @param aTooltip Second line of the text if ant

        * @param aFolderInfo Folder-related details

        * @param aModifiable If user can modify the command

        * @param aConfirmationNeeded If EFalse, when the command is recognized,

        *        it is immediately executed

        *        If ETrue, when the command is recognized, it is played back and

        *        user is asked to confirm the recognition results

        * @see

        * @todo Add "see" reference to the recognition-side function that uses the

        *       "confirmation needed information"

        * @todo aModifiable param is "hanging in the air" and never actually used

        *       Clarify its existence and responsibilities

        * @param aUserText Optional user-specified shortcut for the command

        */

        IMPORT_C static CVCCommandUi* NewL( const TDesC& aWrittenText, 

                const CVCFolderInfo& aFolderInfo, TBool aModifiable, 

                const TDesC& aTooltip, const TUid& aIconUid, 

                const TDesC& aUserText = KNullDesC,

                TBool aConfirmationNeeded = ETrue );

        /**

        * Factory function that constructs a CVCCommandUi from the stream

        * @leave KErrNotSupported if the stream data format is unsupported

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

        */

        IMPORT_C static CVCCommandUi* NewL( RReadStream& aStream );

        /**

        * Copy the existing CVCCommandUi

        */

        IMPORT_C static CVCCommandUi* NewL( const CVCCommandUi& aOriginal );

        /** Destructor */

        IMPORT_C ~CVCCommandUi();

        /** 

		* Saves the command to stream.

		* Descriptor components are saved as <length><descriptor> pairs, where 

		* <length> is TInt32 and <descriptor> is the default descriptor represetation

		* TBools are saved as TInt32 either

		*/

		IMPORT_C void ExternalizeL( RWriteStream &aStream ) const;

        // Accessor methods

        /**

        * @return Unmodifiable written text

        */

        IMPORT_C const TDesC& WrittenText() const;

        /**

        * @return Unmodifiable user-specified shortcut for the command

        *         KNullDesC if none

        */

        IMPORT_C const TDesC& UserText() const;

        /**

        * @return Unmodifiable folder name

        */

        IMPORT_C const CVCFolderInfo& FolderInfo() const;

        /**

        * @return ETrue if the command is modifiable by user

        *         EFalse otherwise

        */

        IMPORT_C TBool Modifiable() const;

        /**

        * @return EFalse, if when the command is recognized,

        *         it is immediately executed

        *         ETrue, if when the command is recognized, it is played back and

        *         user is asked to confirm the recognition results

        * @see

        * @todo Add "see" reference to the recognition-side function that uses the

        *       "confirmation needed information"

        **/

        IMPORT_C TBool ConfirmationNeeded() const;

        /**

        * @return Unmodifiable extra text

        */

        IMPORT_C const TDesC& Tooltip() const;

        /**

        * @return global icon id

        * @todo AVKON-global? What kind of global?

        */ 

        IMPORT_C const TUid& IconUid() const;

	    /**

        * Creates the command icon. Takes into account the skin-specifics

	    * Works only if CEikonEnv is available

        * @return The command icon pushed to the cleanup stack

        */

	    IMPORT_C CGulIcon* IconLC() const;

        IMPORT_C TBool operator==( const CVCCommandUi& aCommandUi ) const;

        /**

         * Tells if all non user-changeable parts of aCommandUi are equal to this object's

         * @return ETrue if equal, EFalse otherwise

         */

        IMPORT_C TBool EqualNonUserChangeableData( const CVCCommandUi& aCommandUi ) const;

    private:

        /** 

        * Second-phase constructor 

        * @see NewL for guard conditions

        */

        void ConstructL( const TDesC& aWrittenText, 

                const CVCFolderInfo& aFolderInfo, TBool aModifiable, 

                const TDesC& aTooltip, const TUid& aIconUid, 

                const TDesC& aUserText, TBool aConfirmationNeeded );

        void ConstructL( RReadStream& aStream );

    private: // Data

        // Text shown on screen

        HBufC* iWrittenText;

        // User-specified alternative command text

        HBufC* iUserText;

        // Text shown on screen

        HBufC* iTooltip;

        // Folder-related details

        CVCFolderInfo* iFolderInfo;

        // Tells if this command is user modifiable

        TBool iUserCanModify;

        // Ask user to confirm the recognition result

        TBool iConfirmationNeeded;

        // global icon id

        /** @todo AVKON-global? What kind of global? */

        TUid iIconUid;

    };

/**

* Container for the information on how the command should be executed:

* 1) app uid OR exe filename; 2) optional command line arguments

*/    

class CVCRunnable : public CBase

    {

    public:

        /**

        * Factory function

        * @param aAppUid UID of the application to start. Cannot be KNullUidValue

        * @param aArguments Command line to pass to the application. This object makes

        *        a copy of the passed string

        * @leave KErrOverflow if aArguments is longer, than KMaxVCArgumentLength

        * @leave KErrArgument if aAppUid is KNullUidValue

        */

        IMPORT_C static CVCRunnable* NewL( TUid aAppUid, const TDesC8& aArguments = KNullDesC8 );

        /**

        * Factory function

        * @param aExeName Exe-file to start. Can be full or partical name according to 

        *        the RProcess::Create rules. Cannot be KNullDesC

        * @param aArguments Command line to pass to the application. This object makes

        *        a copy of the passed string

        * @leave KErrOverflow if aArguments is longer, than KMaxVCArgumentLength or 

        *		 aExeName is longer, than KMaxFileName

        * @leave KErrUndeflow if aExeName is empty

        */

        IMPORT_C static CVCRunnable* NewL( const TDesC& aExeName, 

        								   const TDesC8& aArguments = KNullDesC8 );

        /** 

        * Internalizes the object from stream 

        * @leave KErrNotSupported if the stream data format is unsupported

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

        */

        IMPORT_C static CVCRunnable* NewL( RReadStream &aStream );

        /**

        * Copy the existing CVRunnable

        */

        IMPORT_C static CVCRunnable* NewL( const CVCRunnable& aOriginal );

        /** Destructor */

        IMPORT_C ~CVCRunnable();

        /** 

        * Run the command. In case of aAppUid specified during the construction

        * application is started via the RApaLsSession::StartApp, otherwise

        * via the RProcess::Create

        * @leave System-wide error code. In particular KErrNotFound if there is

        *        no such app in the system

        */

        IMPORT_C void ExecuteL() const;

        /** Saves the object to stream */

        IMPORT_C void ExternalizeL( RWriteStream &aStream ) const;

        /**

        * @return The uid of the application to be started. KNullUid if there is none

        */

        IMPORT_C const TUid Uid() const;

        /**

        * @return The filename of the application to be started. KNullDesC if there is none

        */

        IMPORT_C const TDesC& ExeName() const;

        /**

        * The arguments to be passed to the application. This object keeps

        * the ownership of the returned value

        */

        IMPORT_C const TDesC8& Arguments() const;

        IMPORT_C TBool operator==( const CVCRunnable& aRunnable ) const;

    private:

        void ConstructL( TUid aAppUid, const TDesC8& aArguments );

        void ConstructL( const TDesC& aExeName, const TDesC8& aArguments );

        void ConstructL( RReadStream& aStream );

    private:

        // UID of the application to be run, when the vcommand is recognized

        // KNullUidValue if none specified

        TUid iExeUid;

        // Filename to pass to RProcess::Create or NULL

        HBufC* iExeName;

        // Arguments string

        HBufC8* iArguments;

    };

/**

* The packaged VCommand storable/retriavable to/from VAS

*/

class CVCommand : public CBase

    {

    public:

        /**

        * 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

        */

        IMPORT_C 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

        */

        IMPORT_C static CVCommand* NewL( RReadStream &aStream );

        /**

        * Copy the existing CVCommand

        */

        IMPORT_C static CVCommand* NewL( const CVCommand& aOriginal );

        /** Destructor */

        IMPORT_C ~CVCommand();

        /**

		* Saves the command to stream 

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

		*         <runnable><commandui>

		*/

        IMPORT_C void ExternalizeL( RWriteStream &aStream ) const;

        /**

        * @return the Runnable component of the command

        */

        IMPORT_C const CVCRunnable& Runnable() const;

        /**

        * @return the UI-related component of the command

        */

        IMPORT_C const CVCCommandUi& CommandUi() const;

        /**

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

        *         It is different from the CVCommandUi::WrittenText

        */

        IMPORT_C const TDesC& SpokenText() const;

        /**

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

        *         recognize the command. Is always identical to the 

        *         CVCommandUi::UserText()

        *         Can be KNullDesC

        *

        * @todo Responsibilities of SpokenText, AlternativeSpokenText,

        *       WrittenText and UserText are mixed. The source of problems

        *       is the fact that WrittenText can really be different from the

        *       default spoken text while User supplied text is always what's

        *       expected to be [alternatively] recognized

        *       A better structuring would be very welcome

        */

        IMPORT_C const TDesC& AlternativeSpokenText() const;

        /**

        * Asynchronous

        * 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 CVCommand (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

        */

        IMPORT_C virtual void PlaySpokenTextL( const CVCommandHandler& aHandler, 

                                   MNssPlayEventHandler& aPlayEventHandler ) const;

        /**

        * Asynchronous

        * 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

        */ 

        IMPORT_C virtual 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

        *

        */                                   

        IMPORT_C virtual void CancelPlaybackL( const CVCommandHandler& aHandler ) const;