/*
* Copyright (c) 2002 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:  Manager to recover important operations.
*
*/


#ifndef CPHONERECOVERYSYSTEM_H
#define CPHONERECOVERYSYSTEM_H

// INCLUDES
#include    <coemain.h>
#include    <e32base.h>
#include    "ctelerecoverysystem.h"

// CONSTANTS
const TInt KNullId = -1;
const TInt KIdContainerSize = 10;

// MACROS     


// DATA TYPES
typedef TInt TPhoneRecoveryId;
typedef TInt8 TPhoneRecoveryPriority;

typedef TPhoneRecoveryId TRecoveryId;
typedef TPhoneRecoveryPriority TRecoveryPriority;



// FORWARD DECLARATIONS
class CPhoneTimer;
//class CTeleRecoverySystem;

// CLASS DECLARATION

/**
*  If an operation fails, phone application may be leaved to incorrect states. 
*  By using recovery system, failed operation will be tried again some time 
*  later. This may enhance the robustness of phone application.
* 
*  Return value from callback function
*  KErrNone: EStateIdle
*  KErrNoMemory, KErrInUse, KErrServerTerminated, KErrServerBusy, KErrNotRead,
*  KErrAccessDenied, KErrLocked, KErrDiskFull, KErrTimedOut: EStateWaiting
*  Otherwise: EStatePending
*  If call back function leaves, then the error of leave is used as return 
*  value.
*  Note: In the recovery callback function, CPhoneRecoverySystem::AddL(...) or
*  CPhoneRecoverySystem::Add(...) should never be called. 
*  
*  @since 1.0
*/
class CPhoneRecoverySystem 
    : public CCoeStatic
    {
    public:  // Constructors and destructor

        /**
        * First call initializes the singleton object. Subsequent calls return
        * instance.
        * @return the created instance.
        */
        IMPORT_C static CPhoneRecoverySystem* Instance();

        /**
        * Destructor.
        */
        ~CPhoneRecoverySystem();
       
    public: // new function

        /**
        * Adds a new item with given priority & state. Returns Null id if it
        * failed. Same item must not be added twice. Callback's return value
        * indicates how many steps there are to be done, 0 - no more steps. 
        * Error code or leave - failure.
        * Priority indicates importantance of the action.
        *
        * @param aCallBack callback.
        * @param aPriority priority.
        * @param aState start state.
        * @return identifier.
        */
        TRecoveryId Add( TCallBack aCallBack, 
            TRecoveryPriority aPriority, 
            CTeleRecoverySystem::TRecoveryState aState );

        /**
        * Add a new item to the recovery system. The function may leave if
        * OOM. 
        *
        * @param aCallBack callback.
        * @param aPriority priority.
        * @param aState start state.
        * @return identifier.
        */
        IMPORT_C TRecoveryId AddL( TCallBack aCallBack,
            TRecoveryPriority aPriority,
            CTeleRecoverySystem::TRecoveryState aState );
    
        /**
        * Removes item.
        *
        * @param aId identifier of the item to be removed.
        */
        IMPORT_C static void Remove( TRecoveryId aId );
    
        /**
        * Sets state. Note: The timer will not be started if the state is
        * set to be waiting.
        *
        * @param aId identifier.
        * @param aState new state.
        */
        void SetState( TRecoveryId aId, 
            CTeleRecoverySystem::TRecoveryState aState );
    
        /**
        * Resets pending recovery actions back to waiting.
        */
        void ResetPending();
    
        /**
        * Recovers one step or all steps synchronously. Even if it's solved
        * it should call the method.
        *
        * @param aId identifier.
        * @param aPriority priority.
        * @param aAllSteps ETrue if all steps need to be run.
        * @return error code.
        */
        IMPORT_C TInt RecoverNow( TRecoveryId aId, 
            TRecoveryPriority aPriority, 
            TBool aAllSteps = EFalse );

        /**
        * Informs that precondition has been satisfied.
        */
        IMPORT_C void EnablePreconditionL();

                        
       /**
        * Create tele recovery system
        */    
        CTeleRecoverySystem* CreateRecoverySystemL();

    private: // New functions

        /**
        * Removes recovery id item.
        *
        * @param aId identifier of the item to be removed.
        */
        void RemoveId( TRecoveryId aId );
    
    private: // private structures
        
        // Defines structure containing information
        // of a recovery item.
        class TRecoveryItem
            {
            public:
                // Identifier
                TRecoveryId iId;
                // Callback
                TCallBack iCallBack;
                // Priority
                TRecoveryPriority iPriority;
                // State
                CTeleRecoverySystem::TRecoveryState iState;
            };

    private: //private function

        /**
        * Two-phased constructor.
        * @return new instance.
        */
        static CPhoneRecoverySystem* NewL();

        /**
        * C++ constructor.
        */
        CPhoneRecoverySystem();
         
        /**
        * Adds id to container which holds all the ids this singleton
        * has given out via AddL method.
        * @param aId - Id to be added in container
        * @exception -1 (KErrNoSpace) is thrown if there isn't room in the container
        */
        void AddIdToContainer( TRecoveryId aId );
        
        /**
        * Removes given id from the container which holds all the ids this singleton
        * has given out via AddL method.
        * @param aId - Id to be removed from container
        */
        void RemoveFromContainer( TRecoveryId aId );
        
        /**
        * This is called from destructor. Method removes all the ids from recovery
        * system that are hold within container. This is done this way because
        * this singleton object is actually destructed by coeenv before some of
        * object's clients' destructor is called where it would try to remove
        * id from the recovery system. Now this way we do not leak any resources.
        */
        void RemoveAllIdsFromContainer();


    private:    // Data  
           
        // Timer for recovery
        CPhoneTimer* iTimer;

        // Timer for recovery all steps
        CPhoneTimer* iAllStepsTimer;

        // Id counter for TRecoveryId
        TInt iIdCounter;

        // Count the ticks
        TInt iTickCounter;

#ifdef _DEBUG
        // Debug: to prevent modification of recovery system in 
        // recovery callback.
        TBool iIsCallBack;
#endif // _DEBUG

        // ETrue if precondition ok
        TBool iPrecondOk;

        // ETrue if precondition SIM ok
        TBool iPrecondSimOk;

        // Keycount - recovery counter is checked only after some keypresses
        TInt iKeyCount;
        
        // Reference to Tele recovery system.
        CTeleRecoverySystem* iRecoverySystem;
        
        // Container for allocated recovery ids
        TFixedArray< TInt, KIdContainerSize > iIdContainer;

    };

#endif      // CPHONERECOVERYSYSTEM_H   
            
// End of File