/*
* 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 CMccTimerManager instance.
*
*/



#ifndef MCCEXPIRATIONHANDLER_H
#define MCCEXPIRATIONHANDLER_H

// INCLUDES
#include <e32def.h>

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

// CLASS DEFINITION
/**
 * When a timer expires, this interface is called by MMccTimerManager
 */
class MMccExpirationHandler
	{
	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( TMccTimerId aTimerId, TAny* aTimerParam ) = 0;
	};


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

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

	public: // Constructors and destructor

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

	public:	// Abstract methods

		/**
		 * Creates a new timer and starts it.
		 *
		 * @pre aObserver != NULL
		 * @see See also this method 'MMccExpirationHandler::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 TMccTimerId StartL( MMccExpirationHandler* aObserver,
							     TUint aMilliseconds ) = 0;
							     
		/**
		 * Creates a new timer and starts it.
		 *
		 * @pre aObserver != NULL
		 * @see See also this method 'MMccExpirationHandler::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 MMccExpirationHandler::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 TMccTimerId StartL( MMccExpirationHandler* 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( TMccTimerId 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( TMccTimerId aTimerId ) const = 0;

	};

#endif // MCCEXPIRATIONHANDLER_H