/*
* Copyright (c) 2005-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:
* Name          : Lwtimer.h
* Part of       : LightWeightTimer
* This header file is included by the subsystems needing timer
* services, but are not responsible for creating the
* CTimerManager instance.
* Version       : SIP/4.0
*
*/




/**
 @internalComponent
*/


#ifndef LWTIMER_H
#define LWTIMER_H

// INCLUDES
#include <e32def.h>

// TYPEDEFS

//Each timer is associated with an identifier of this type. When a timer is
//startedt, TTimerId is returned to the user.
//When a timer expires, its TTimerId is passed in the callback.
//If the user wishes to stop a certain timer, it must pass the TTimerId of the
// timer in question to the Lightweight timer subsystem.
typedef TUint32 TTimerId;


// CLASS DECLARATION

/**
 * When a timer expires, this interface is called by the Lightweight timer
 * subsystem.
 */
class MExpirationHandler
	{
public: // Virtual destructor

	virtual ~MExpirationHandler() {}

public: // New pure virtual functions

	/**
	 * Indicates that a timer has expired.
	 *
	 * @param aTimerId Identifies the expired timer
	 * @param aTimerParam User specified value which was given when the timer
	 *	was set. It can be used to identify the timer in case multiple timers
	 *  are running simultaneously. Value is NULL if the timer was set using
	 *  CTimerManager::StartL without parameter aTimerParam. Ownership isn't
     *  transferred.
	 */
	virtual void TimerExpiredL(TTimerId aTimerId, TAny* aTimerParam) = 0;
	};


/**
 * MTimerManager provides methods for starting and stopping timers.
 */
class MTimerManager
	{
public: // Enumerations
	enum TTimerIdValues
        {
		//TimerId value for a non-existent timer. This value is never returned
        //to the user of the Lightweight timer subsystem.
		KNoSuchTimer = 0,

		//TimerId for an internal dummy timer, which is used simulate a longer
        //timer without having to use RTimer::At(). This value is never
        //returned to the user of the Lightweight timer subsystem.
		KReservedTimer = 1
	    };

public: // New pure virtual functions

	/**
	 * Creates a new timer and starts it.
	 *
	 * @pre aObserver != NULL	 
	 *
	 * @see See also this method 'MExpirationHandler::TimerExpiredL'
	 *
	 * @param aObserver	IN: Callback to use when timer expires. Ownership is
	 *	not transferred.
	 * @param aMilliseconds	Timer duration in milliseconds (with 32 bits, the
	 *	max value is ~50 days)
	 * @return value TimerId value identifying the new timer	 
	 */
	virtual TTimerId StartL(MExpirationHandler* aObserver,
							TUint aMilliseconds) = 0;
	
	/**
	 * Creates a new timer and starts it.
	 *
	 * @pre aObserver != NULL	 
	 *
	 * @see See also this method 'MExpirationHandler::TimerExpiredL'
	 *
	 * @param aObserver	IN: Callback to use when timer expires. Ownership is
	 *	not transferred.
	 * @param aMilliseconds	Timer duration in milliseconds (with 32 bits, the
	 *	max value is ~50 days)
	 * @param aTimerParam User specified value which will be passed to the
	 *	aObserver function MExpirationHandler::TimerExpiredL when the timer
	 *	expires. Ownership isn't transferred.
	 * @return value TimerId value identifying the new timer
	 */
	virtual TTimerId StartL(MExpirationHandler* aObserver,
						    TUint aMilliseconds,
						    TAny* aTimerParam) = 0;

	/**
	 * Stops the specified timer.
	 *
	 * This function doesn't leave in case of error, as it is thought that this
	 * function is usually also called from destructors.
	 *
	 * @param aTimerId Identifies the timer to be stopped	 
	 * @return value KErrNone: successful
     *               KErrNotFound : no such timer exists
	 */	
	virtual TInt Stop(TTimerId aTimerId) = 0;

	/**
	 * Checks if there exists a timer which hasn't expired yet, with the
	 * specified TimerId.
	 *
	 * @param aTimerId Identifies the timer	 
	 * @return value ETrue: timer exists, KFalse: no such timer
	 */	
	virtual TBool IsRunning(TTimerId aTimerId) const = 0;
	
	/**
	 * Checks how long it will take until the timer expires, with the
	 * specified TimerId.
	 *
	 * @param aTimerId Identifies the timer	 
	 * @param aExpiresAfterInMillisecs on return contains expires after
	 *  value as milliseconds
	 * @return value KErrNone: successful
     *               KErrNotFound : no such timer exists
	 */	
	virtual TInt ExpiresAfter(TTimerId aTimerId, 
	                          TUint& aExpiresAfterInMillisecs) const = 0;
	};

#endif // end of LWTIMER_H

// End of File