/*
* Copyright (c) 2006 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 header file is included by the subsystems which are
*                  using timer services, but are not responsible for creating
*                  the CTimerManager instance.
*
*/



#ifndef __MCETIMER_H__
#define __MCETIMER_H__

// INCLUDES
#include <e32def.h>

/// Every timer is associated with an identifier of this type.
/// When a timer is set, TMceTimerId is returned to the user of the Lightweight
/// timer subsystem.
/// When a timer expires, its TMceTimerId is passed in the callback.
/// If the user wishes to stop or adjust a certain timer, it has to pass the
/// TMceTimerId of the timer in question to the Lightweight timer subsystem.
typedef TUint32 TMceTimerId;

// CLASS DEFINITION
/**
 * When a timer expires, this interface is called by the Ligthweight timer
 * subsystem.
 */
class MMCEExpirationHandler
	{
	public: // Constructors and destructor

		/// Virtual destructor
		virtual ~MMCEExpirationHandler() {}

	public: // Abstract methods

		/**
		 * 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( TMceTimerId aTimerId, TAny* aTimerParam ) = 0;
	};


// CLASS DEFINITION
/**
 * MMceTimerManager provides methods for starting, stopping and adjusting timers.
 */
class MMceTimerManager
	{
	public: // Enumerations

		/// This exists for backward compatibility
		enum TMceTimerIdValues
			{
			/// TimerId that is never used with a valid timer
			KNoSuchTimer = 0
			};

	public: // Constructors and destructor

		/// Virtual destructor
		virtual ~MMceTimerManager() {}

	public:	// Abstract methods

		/**
		 * Creates a new timer and starts it.
		 *
		 * @pre aObserver != NULL
		 * @see See also this method 'MMCEExpirationHandler::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
		 *
		 * In case of an error, this function leaves.
		 */
		virtual TMceTimerId StartL( MMCEExpirationHandler* aObserver,
							     TUint aMilliseconds ) = 0;
							     
		/**
		 * Creates a new timer and starts it.
		 *
		 * @pre aObserver != NULL
		 * @see See also this method 'MMCEExpirationHandler::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 MMCEExpirationHandler::TimerExpiredL() when the timer
		 *	expires. Ownership isn't transferred.
		 * @return value TimerId value identifying the new timer
		 *
		 * In case of an error, this function leaves.
		 */
		virtual TMceTimerId StartL( MMCEExpirationHandler* 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( TMceTimerId 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( TMceTimerId aTimerId ) const = 0;

	};

#endif // __MCETIMER_H__