/*
 * Copyright (c) 2010 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
 *
 * Description:
 * This class contains definition of CFlexTimerContainer.
 *
 */

// Protection against nested includes
#ifndef FLEXTIMERCONTAINER_H
#define FLEXTIMERCONTAINER_H

// System includes
#include <e32base.h>

// Forward declarations
class MFlexTimerServiceCB;
class CFlexTimerItem;

// Class declaration
/**
 *  Timer container that contains list of CFlexTimerItems, means to add and
 *  delete them and implementation of algorithms that select which timers
 *   should be expired.
 */
class CFlexTimerContainer : public CBase
    {
public:
    /** Supported timer algorithms.*/
    enum TFlexTimerAlgorithm
        {
        /** Simple algorithm timeouts all timers that have open timeout
         * window when one timer expires.
         */
        EFlexTimerAlgorithmSimple = 1,
        /** Latest possible algorithm tries to delay expiration of timer
         * as long as possible.
         */
        EFlexTimerAlgorithmLatestPossible
        };

    /**
     * Constructs new CFlexTimerContainer.
     */
    static CFlexTimerContainer* NewL();

    /**
     * Destructs timercontainer and all timers in the internal lists.
     */
    virtual ~CFlexTimerContainer();

public:
    /**
     * Makes new timer item and adds it to timerlist.
     *
     * @param aWinStartInterval Time interval from present to left side of the
     *  timer launch window
     * @param aWinEndInterval Time interval from present to right side of the
     *  timer launch window
     * @param aCancelAtSystemTimeChange Whether system time change should
     *  trigger abort
     * @param aFlexTimerServiceCB Call back interface. Used to inform about
     *  timeout, abort etc.
     */
    void AddTimerL(
        const TTimeIntervalMicroSeconds& aWinStartInterval,
        const TTimeIntervalMicroSeconds& aWinEndInterval,
        TBool aCancelAtSystemTimeChange,
        const MFlexTimerServiceCB* aFlexTimerServiceCB );

    /**
     * Finds correct timer according to aFlexTimerServiceCB and removes it
     * from list and finally 
     * deletes the corresponding CFlexTimerItem.
     * @param aFlexTimerServiceCB Call back interface aka. session that
     * handles timer.
     * @return KErrNone or some system wide error code.
     */
    TInt RemoveTimer( const MFlexTimerServiceCB* aFlexTimerServiceCB );

    /**
     * Finds earliest moment that at least one timer must expire and after
     * this function returns aNextTimeoutDelay contains number of microseconds
     * from now to that moment.
     *
     * @param after return aNextTimeoutDelay contains time in microseconds
     * from now till next timer expiry. If aNextTimeoutDelay is zero, it means
     * that expiry time has already passed or is due right now
     * @return Active timers indication
     * - ETrue if there is at least one timer in queue
     * - EFalse if there are no timers
     */
    TBool GetNextTimeout( TTimeIntervalMicroSeconds& aNextTimeoutDelay );

    /**
     * Fires all timers that can be fired according to algorithm that is
     * supplied as parameter.
     *
     * @param aAlgorithmToBeUsed Algorithm that is used to fire timers.
     * - EFlexTimerAlgorithmSimple
     * - EFlexTimerAlgorithmLatestPossible
     */
    void FireTimers( TFlexTimerAlgorithm aAlgorithmToBeUsed );

    /**
     * Aborts and removes all timers that are marked with
     * aCancelAtSystemTimeChange = ETrue during adding timer.
     *
     * @param aReason Timers will be aborted with this reason code. Can be
     * e.g. KErrAbort
     */
    void AbortTimersDueToTimeChange( TInt aReason );

private:
    /**
     * Private constructor.
     */
    CFlexTimerContainer();

    /**
     * Excecutes simple algorithm.
     * 
     * Moves timers (that can be fired right now) from iTimerList to
     * candidateList.
     * 
     * @param aCandidateList After this function returns, this list contains
     * all timers that can be fire right now.
     * @param aCurrentTime Current safe UTC time.
     */
    void SimpleAlgorithm( TSglQue<CFlexTimerItem>& aCandidateList,
        TTime& aCurrentTime );

    /**
     * Excecutes latest possible algorithm.
     * 
     * Moves timers (that don't necessarily be fired right now) from
     * candidateList to iTimerList.
     * 
     * @param aCandidateList After this function returns, this list contains
     * all timers that can be fire right now.
     */
    void LatestPossibleAlgorithm( TSglQue<CFlexTimerItem>& aCandidateList );

    /**
     * Fires all timers in aCandidateList. Calls Timeout() to all timers and
     * deletes timer items.
     * 
     * @param aCandidateList Timers that are fired.
     */
    void ExpireTimers( TSglQue<CFlexTimerItem>& aCandidateList );

    /**
     * Gets current absolute time. The time in FlexTimer engine time base, not
     * system time base. This time base is begins from the first call to
     *  GetCurrentTime and it is base on system ticks.
     * 
     * @param aCurrentAbsoluteTime After this function returns this contains
     * current flextimer timebase time.
     */
    void GetCurrentTime( TTime& aCurrentAbsoluteTime );

    /**
     * Converts microseconds interval to tick based reference time used by
     * FlexTimer engine (also in microseconds). All FlexTimer timeout element
     * time handling is based on this tick based absolute time.
     *
     * @param aInterval Interval to be converted.
     */
    inline TInt64 IntervalToAbsoluteTime(
        const TTimeIntervalMicroSeconds& aInterval );

    /**
     * Converts ticks to microseconds.
     *
     * @param aTicks. Ticks to be converted to microseconds
     */
    inline TInt64 TicksToAbsoluteTime( TUint32 aTicks );

private:
    // Data
    /**
     * Linked list and iterator for all timer objects.
     */
    TSglQue<CFlexTimerItem> iTimerList;
    
    /**
     * Length of system tick in milliseconds. The value is read once
     * to member variable during construction of FlexTimerContainer so that
     * it does not need be read every time the absolute time is calculated.
     */
    TInt iTickPeriod;
     
    /**
     * Number of tics during the last time they were read. This is used to
     * detect possible tick counter overflow and to calculate time passed
     * since the last read.
     */
    TUint32 iLastTicks;
    
    /**
     * Current FlexTimer engine time. This is system tick based time and
     * it is updated every time someone request for it.
     */
    TInt64 iCurrentAbsoluteTime;
    };

#include "flextimercontainer.inl"

#endif  //FLEXTIMERCONTAINER_H