/*

* Copyright (c) 2004-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:  The MSeechItem provides speech methods to the client.

*               The methods are used by the client to request speech services from SRS. 

*

*/

#ifndef NSSVASMSPEECHITEM_H

#define NSSVASMSPEECHITEM_H

// INCLUDE FILES

#include <nssvascoreconstant.h>

// FORWARD DECLARATIONS

class MNssPlayEventHandler;

class MNssTrainVoiceEventHandler;

class MNssTrainTextEventHandler;

class CNssTrainingParameters;

/**

* The MSpeechItem class represents the speech part of a voice tag. The

* MSeechItem provides speech methods to  the client. The methods are used by

* the client  to request speech services from SRS

*

*  @lib NssVASApi.lib

*  @since 2.0

*/

class MNssSpeechItem

{

  public:  //enum

    /**

    * TNssSpeechItemResult will have all the enums to represent the return values from

    * MSpeechItem's methods.

    * 

    * NOTE:

    * The caller functions should be able to handle the unknown TNssSpeechItemResult enum values.

    */         

    enum TNssSpeechItemResult

     {

        EVasErrorNone,

        EVasUnexpectedRequest,  // Unexpected request from client, when the state is not Idle

        EVasInUse,              // VAS resource is currently in use.

        EVasInvalidParameter,

        EVasPlayFailed,

        EVasTrainFailed

     };

  public:

    /**

    * The Record method is used by the client to record input speech.

    *

    * @since 2.0

    * @param aTrainVoiceEventHandler A call back object to handle the record events

    * @return TNssSpeechItemResult, synchronous return value to identify whether the

    *         synchronous process is success or fail

    */    

    virtual TNssSpeechItemResult RecordL( 

                MNssTrainVoiceEventHandler* aTrainVoiceEventHandler ) = 0;

    /**

    * Method called by the client to indicate to SRS that a playback is

    * needed.

    *

    * @since 2.0

    * @param aPlayEventHandler A call back object to handle the play events

    * @return TNssSpeechItemResult, synchronous return value to identify whether the

    *         synchronous process is success or fail

    */    

    virtual TNssSpeechItemResult PlayL( MNssPlayEventHandler* aPlayEventHandler ) = 0;

    /**

    * Method called by the client to indicate to SRS that a playback is

    * needed with a certain language.

    *

    * @since 2.8

    * @param aPlayEventHandler A call back object to handle the play events

    * @param aLanguage Language which will be used in playback

    * @return TNssSpeechItemResult, synchronous return value to identify whether the

    *         synchronous process is success or fail

    */    

    virtual TNssSpeechItemResult PlayL( MNssPlayEventHandler* aPlayEventHandler,

                                        TLanguage aLanguage ) = 0;

   /**

    * Method called by the client to indicate to SRS that training is

    * needed.

    *

    * @since 2.0

    * @param aTrainVoiceEventHandler A call back object to handle the train events

    * @return TNssSpeechItemResult, synchronous return value to identify whether the

    *         synchronous process is success or fail

    */    

    virtual TNssSpeechItemResult TrainVoiceL( 

                MNssTrainVoiceEventHandler* aTrainVoiceEventHandler ) = 0;

    /**

    * Method called by the client to  cancel the previous operation.

    *

    * @since 2.0

    * @return TNssSpeechItemResult, synchronous return value to identify whether the

    *         synchronous process is success or fail

    */    

    virtual TNssSpeechItemResult CancelL() = 0;

    /**

    * The GetTrainingCapabilities member fucntion is used by the client 

    * to get training capabilities to beused in Speaker Independent voice 

    * recognition.

    *

    * @since 2.0

    * @return the pointer to the array of Training capabilities data

    */    

    virtual CArrayFixFlat<TNssVasCoreConstant::TNssTrainingCapability>* TrainingCapabilities() = 0;

    /**

    * The GetTrainedType member function is used by the client to get 

    * train type  to be used in Speaker Independent voice recognition. 

    * 

    * @since 2.0

    * @return the enum for the trained type

    */    

    virtual TNssVasCoreConstant::TNssTrainedType TrainedType() = 0;

    /**

    * The Text member fucntion is used by the client to get text to be

    * used in Speaker Independent voice recognition. The text can also be

    * used to identify the voice tag, and can be used for user display by

    * the client.

    *

    * @since 2.0

    * @return A text buffer

    */    

    virtual TDesC& Text() = 0;

    /**

    * The SetTextL method is used by the client to initialize the Text

    * data member

    *

    * @since 2.0

    * @param aText the reference of a text buffer

    */    

    virtual void SetTextL( const TDesC& aText ) = 0;

    /**

    * Playing a tag is not supported, if the recognition technology is speaker

    * independent and speech synthesis is not present.

    *

    * @since 2.0

    * @return ETrue Playing is supported.

    *         EFalse PlayL() will leave with KErrNotSupported.

    */

    virtual TBool IsPlayingSupported() = 0;

    /**

    * Trains the speech model. The model is based on the text

    * which was given earlier at SetTextL.

    *

    * @since 2.0

    * @param aEventHandler To inform the client when the training has finished.

    * @param aTrainingParams Training parameters 

    * @return TNssSpeechItemResult Success status

    */

    virtual TNssSpeechItemResult TrainTextL( MNssTrainTextEventHandler* aEventHandler,

                                             CNssTrainingParameters* aTrainingParams ) = 0;

    /**

    * Returns the raw training text from where escape characters are not removed.

    * Should not be used by clients who want to display the string.

    *

    * @since 3.2

    * @return Reference to the text buffer

    */    

    virtual TDesC& RawText() = 0;

    /**

    * Returns the part of text which identified with the given id.

    * If RawText() is for example "_1Amy_1Harris_2mobile" then 

    * PartialText( _L( "1" ) ) call will return "Amy Harris".

    *

    * @since 3.2

    * @param aIdentifier ID of the text part to return

    * @return Text, ownership is transferred to client

    */

    virtual HBufC* PartialTextL( const TDesC& aIdentifier ) = 0;

};

#endif // NSSVASMSPEECHITEM_H