/*
* 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