/*
* Copyright (c) 2007-2008 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:  FreestyleEmailUi exit guardian.
*
*/

#ifndef C_EUIEXITGUARDIAN_H
#define C_EUIEXITGUARDIAN_H

#include <e32base.h>

// FORWARD DECLARATIONS
class CFreestyleEmailUiAppUi;
class CIdle;

/**
 * Application exit guardian for email UI. This is needed because some routines
 * in email framework create nested scheduler loops to hide asynchronity in
 * them. When application is shutdown these nested levels may cause crashes
 * as resources are freed while they are still being used on other recursion
 * levels.
 *
 * Usage:
 *
 * void CClass::RoutineThatMayCreatedNestedLevelL()
 *    {
 *    iExitGuardian->EnterLC();
 *    // call or execute code that may create nested sceduler loop
 *    ...
 *    // and finally popup and destroy cleanup item
 *    CleanupStack::PopAndDestroy(); // iExitGuardian->EnterLC()
 *    }
 *
 * @since S60 5.1
 */
class CEUiExitGuardian : public CBase
  	{

public:

    /**
     * Leave safe construction for CEuiExitGuardian.
     * @return Newly created instance of CEuiExitGuardian
     */
    static CEUiExitGuardian* NewL(CFreestyleEmailUiAppUi& aAppUi);

    /**
     * Destructor.
     */
    ~CEUiExitGuardian();

    /**
     * Called before executing code that may cause new nested level in
     * active scheduler. Leaves cleanup item in cleanup stack and this item
     * must be purged by the caller after code execution. Cleanup item is used
     * to make level counter leavesafe.
     */
    void EnterLC();

    /**
     * Called by the application to inform that application is ready to
     * exit. If there is any nested active scheduler levels (i.e. recursion),
     * exit execution will be delayed until every nested level has returned.
     *
     * @return KRequestPending if the exit execution is delayed because of
     * nesting, KErrNone otherwise.
     */
    TInt ExitApplication();

private:

    /**
     * Constructor.
     */
    CEUiExitGuardian(CFreestyleEmailUiAppUi& aAppUi);

    /**
     * Pass 2 constructor, may leave.
     */
	void ConstructL();

    /**
     * Static exit method that is given to cleanup item.
     */
    static void Exit(TAny* aPtr);

    /**
     * Non static exit method that is called from static Exit.
     */
    void DoExit();

    /**
     * Static callback method for CIdle. This is run when recursion is rewinded
     * and appication can be closed.
     */
    static TInt IdleCallBack(TAny* aPtr);

private:

    // Reference to application UI
    CFreestyleEmailUiAppUi& iAppUi;

    // Recursion depth (nested level count)
    TInt iEnterCount;

    // ETrue if the application is ready to exit.
    TBool iExitPending;

    // Idle class instance to rewind final level of recursion before calling the
    // exit
    CIdle* iIdle;

    };

#endif // C_EUIEXITGUARDIAN_H