/*

* Copyright (c) 2009 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: This file defines email sound state classes.

*

*/

#ifndef FSMAILSOUNDSTATES_H

#define FSMAILSOUNDSTATES_H

#include <e32std.h>

#include <mdaaudiosampleplayer.h>

#include <MProfileEngine.h>

#include <MProfileChangeObserver.h>

#include "fsnotificationhandlertimerobserver.h"

class MEmailSoundStateContext;

class CMdaAudioPlayerUtility;

class MEmailSoundStateContext;

class CFSNotificationHandlerTimer; 

/**

 *  Base class to handle email tone playing logic.

 *

 * Generic behavior of state machine:

 *

 * -- event --> handle event --> state transition -- NO--> do nothing

 *                                  needed?

 *                                     |

 *                                     | YES

 *  -----------------------------------

 *  |

 *  --> new state entry action -> store state to context -> delete old

 *                                                           state(*

 *

 *   (* 'failed state' is never deleted to guarantee entry to it. If

 *   any entry action or some other crusial actioin fails, FSM goes to

 *   'failed state' and any ubsequent event activates 'init' state.

 *

 *  @since S60 v5.2

 */

NONSHARABLE_CLASS( CEmailSoundState ) : public CBase

{

public:

    /* Event handlers called by context (owner of state machine).

     * Not all event handler methodss are applicable in each concrete

     * state class, e.g. AudioInitFailed() is reasonable only for EInit state.

     */

    /**

    * Profile changed event.

    */

    virtual void ProfileChanged();

    /**

    * Initializing tone failed. This always causes transition to EFailed state.

    */

    virtual void AudioInitFailed();

    /**

    * Audio tone initialization completed succesfully.

    */

    virtual void AudioInitCompleted();

    /**

    * Audio tone play completed (success or failure, doesn't matter)

    */

    virtual void AudioPlayCompleted();

    /**

    * Request to play tone that matches with currently active profile.

    */

    virtual void PlayTone();

    /**

    * Request to stop playback. Default implementation is empty

    */

    virtual void StopTone();

public: // state machine startup and stopping.

    /** Initializes state machine. Initial state is EInit

     *  (class CEmailInitilisingTone).

     */

    static void InitializeL( MEmailSoundStateContext* aContext );

    /** uninitializes state machine also deleting current state */

    static void Uninitialize( CEmailSoundState* aState );

    /** Returns state machine context providing services to states

     * @return context interface

     */

    MEmailSoundStateContext& Context() const;

protected:

    /** sound states */

    enum TSoundState {

        /** Tone is being initialized */

        EInit,

        /** Ready to play tone, tone initialization is complete

         */

        EReady,

        /** Playing tone

         */

        EPlaying,

        /** Waiting for initialization to complete after which tone

         * is immediately played. Note: this state can be entered also

         * from EFailed state (not just EInit state) meaning that tone

         *  playback starts after initialization.

         */

        EPendingPlay,

        /** Waiting for playback to complete in order to recreate audio

         * tone (e.g. after active profile changed).

         */

        EPendingInit,

        /** Waiting for delay timer expiration   

         */

        EDelay,

        /** Initialization has been failed, tone cannot be played.

         * In this state ProfileChanged causes EInit and PlayTone

         * EPendingPlay to become active state.

         */

        EFailed

        };

    /** Destructor */

    ~CEmailSoundState();

    /** Sets current state to context (owner of state machine) */

    void BaseEnter();

    /* Deletes current state. Derived class may implement additional

     * behavior and call base class Exit() as __last__ statement.

     */

    virtual void Exit();

    /**

     * Tries to initialize audio tone (async operation).

     * @return ETrue if initialization starts. When it finished,

     *         AudioInitCompleted() or AudioInitFailed() is called.

     *

     *         or EFalse if creation fails. In this case EFailed state

     *         is entered.

     */

    TBool TryStartToneInitialization();

    /**

    * Changes to new state and performs exit action for old state including

    * destruction. If any failure in state transition happens, EFailed

    * state becomes current state - it cannot fail.

    * @param aState requested new state

    */

    void StateTransition( const TSoundState aState );

    /** c++ constructor that must be called by derived class */

    CEmailSoundState( MEmailSoundStateContext& aContext );

protected: // data

    /** state machine owner */

    MEmailSoundStateContext& iContext;

};

/**

* In this state tone initialization is ongoing. Next state will be

* EReady (AudioInitCompleted called),

* EPendingPlay (PlayTone called), or

* EFailed (base class AudioInitFailed called)

*/

NONSHARABLE_CLASS( CEmailInitilisingTone ) : public CEmailSoundState

{

public:    // event handlers from CEmailSoundState

    virtual void ProfileChanged();

    virtual void AudioInitCompleted();

    virtual void PlayTone();

private:

    /** c++ constructor */

    CEmailInitilisingTone( MEmailSoundStateContext& aContext );

    /** state entry point */

    static void EnterL( CEmailSoundState* aPreviousState );

    /** state entry actions */

    void DoEnterL();

    // allows base class to do state transition

    friend class CEmailSoundState;

};

/**

* In this state tone initialization has been completed and tone

* can be played. Next state will be

* EInit (ProfileCanged called), or

* EPlaying (PlayTone called)

*/

NONSHARABLE_CLASS( CEmailReadyToPlay ) : public CEmailSoundState

{

public:    // event handlers from CEmailSoundState

    virtual void ProfileChanged();

    virtual void PlayTone();

private:

    /** c++ constructor */

    CEmailReadyToPlay( MEmailSoundStateContext& aContext );

    /** state entry point */

    static void EnterL( CEmailSoundState* aPreviousState );

    /** state entry actions */

    void DoEnterL();

    // allows base class to do state transition

    friend class CEmailSoundState;

};

/**

* In this state tone initialization has been failed.  Next state will be

* EInit (ProfileChanged called), or

* EPendingPlay (PlayTone called)

*/

NONSHARABLE_CLASS( CEmailSoundFailed ) : public CEmailSoundState

{

public:    // event handlers from CEmailSoundState

    virtual void ProfileChanged();

    virtual void PlayTone();

private:      // state entry and exit functions

    /** overrides base class */

    virtual void Exit();

    /** c++ constructor */

    CEmailSoundFailed( MEmailSoundStateContext& aContext );

    /** Enter cannot fail because object is pre-allocated */

    static void Enter( CEmailSoundState* aPreviousState );

    /** state entry actions */

    void DoEnter();

    // allows base class to do state transition

    friend class CEmailSoundState;

};

/**

* In this state tone is being played. Next state will be:

* EReady (StopTone or AudioPlayCompleted called), or

* EPendingInit (ProfileChanged called)

*/

NONSHARABLE_CLASS( CEmailPlayingTone ) : public CEmailSoundState

{

public:    // event handlers from CEmailSoundState

    virtual void ProfileChanged();

    virtual void AudioPlayCompleted();

    virtual void StopTone();

private:      // state entry and exit functions

    /** c++ constructor */

    CEmailPlayingTone( MEmailSoundStateContext& aContext );

    /** state entry point */

    static void EnterL( CEmailSoundState* aPreviousState );

    /** state entry actions */

    void DoEnterL();

    // allows base class to do state transition

    friend class CEmailSoundState;

};

/**

* In this tone initialization is ongoing. Next state will be:

* EPlaying (AudioInitCompleted called),

* EFailed (base class AudioInitFailed called)

*/

NONSHARABLE_CLASS( CEmailPendingPlay ) : public CEmailSoundState

{

public:    // event handlers from CEmailSoundState

    virtual void ProfileChanged();

    virtual void AudioInitCompleted();

private:

    /** state entry actions */

    void DoEnterL();

    /** c++ constructor */

    CEmailPendingPlay( MEmailSoundStateContext& aContext );

    /** state entry point */

    static void EnterL( CEmailSoundState* aPreviousState );

    // allows base class to do state transition

    friend class CEmailSoundState;

};

/**

* In this state profile has changed while tone is being played. Next state

* will be:

* EInit (AudioPlayCompleted called)

*/

NONSHARABLE_CLASS( CEmailPendingInit ) : public CEmailSoundState

{

public:    // event handlers from CEmailSoundState

    virtual void AudioPlayCompleted();

private:

    /** state entry actions */

   void DoEnterL();

    /** c++ constructor */

    CEmailPendingInit( MEmailSoundStateContext& aContext );

    /** state entry point */

    static void EnterL( CEmailSoundState* aPreviousState );

    // allows base class to do state transition

    friend class CEmailSoundState;

};

/**

 * In this state delay timer is started. Next state will be:

 * EReady (when inner timer expires),

 * EFailed (base class AudioInitFailed called)

 */   

NONSHARABLE_CLASS( CEmailTimerDelay ) : public CEmailSoundState,

                                        public MFSNotificationHandlerTimerObserver 

{

public: // event handlers from CEmailSoundState

    virtual void ProfileChanged();

public: // timer callback from base class MFSNotificationHandlerTimerObserver

    virtual void TimerCallBackL( TInt aError );

protected:

    /** Destructor */

    ~CEmailTimerDelay();

private:

    /** state entry actions */

    void DoEnterL();

    /** c++ constructor */

    CEmailTimerDelay( MEmailSoundStateContext& aContext );

    /** state entry point */

    static void EnterL( CEmailSoundState* aPreviousState );

    // allows base class to do state transition

    friend class CEmailSoundState;

private:

    /** timer service, owned */    

    CFSNotificationHandlerTimer* iTimer;

};

#endif // FSMAILSOUNDSTATES_H