/*

  idletimer.h

  Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). 

  All rights reserved.

  This program and the accompanying materials are made available 

  under the terms of the Eclipse Public License v1.0 which accompanies 

  this distribution, and is available at 

  http://www.eclipse.org/legal/epl-v10.html

  Initial Contributors:

  Nokia Corporation - initial contribution.

  Contributors:

*/

// Description

// 

#ifndef IDLETIMER_H

#define IDLETIMER_H

#include <nkern.h>

/**

@file API for Idle Timers

@publishedPartner

@prototype

*/

/**

@publishedPartner

@prototype

Idle Timer class. These are a timers which allow the client to specify a window in which

the timer should queue a Dfc. The implementation aligns multiple timers to allow the device

to spend longer periods in low power modes, thus saving power.

 */	

NONSHARABLE_CLASS(TIdleTimer)

    {

public:

	static const TInt KNoTimeout = -1;

	enum TFault

		{

		/**

		This fault is raised from TIdleTimer::SetDfcQ if an attempt is made to set the Dfc

		queue for an Idle Timer where one has already been set.

		*/

		EDfcQueAlreadySet = 0,

		/**

		This fault is raised from TIdleTimer::SetFunciton if an attempt is made to change

		the function the Dfc callback should call whilst either a OneShot or Periodic

		request is outstanding on the Idle Timer.

		*/		

		ESetFunctionCalledOnPendingTimer = 1,

		/**

		This fault is raised if either TIdleTimer::OneShot or TIdleTimer::Periodic is

		called but no Dfc queue has been set for the Idle Timer.

		*/

		ENoDfcQSet = 2

		};

public:

	/** Idle Timer constructor

	@param	aFunction, function to call on completion of the timer

	@param	aPtr, parameter to be passed to function callback

	@param	aPriority, priority of DFC within the queue (0 to 7, where 7 is highest)

	*/

	IMPORT_C TIdleTimer(TDfcFn aFunction, TAny* aPtr, TInt aPriority);

	/** Idle Timer constructor

	@param	aFunction, function to call on completion of the timer

	@param	aPtr, parameter to be passed to function callback

	@param	aDfcQ, pointer to a DFC queue on which this Idle Timer should queue 

			the DFC callback on timer completion.

	@param	aPriority, priority of DFC within the queue (0 to 7, where 7 is highest)

	*/

	IMPORT_C TIdleTimer(TDfcFn aFunction, TAny* aPtr, TDfcQue* aDfcQ, TInt aPriority);

	/** Set the Dfc queue on which this Idle Timer should make its Dfc callback on

		completion of the timer.

	A Dfc queue must be set either with this function or from the TIdleTimer

	constructor before the Idle Timer can be used – not doing so will fault the

	kernel when the Idle Timer is scheduled.

	This function should only be used in the initialization of the Idle Timer,

	when it has not previously had a Dfc queue set. This function does not move

	the Idle Timer from one queue to another –attempting to do so will fault the kernel.

	@param	aDfcQ, pointer to a DFC queue on which this Idle Timer should queue 

			the DFC callback on timer completion.

	*/

	IMPORT_C void SetDfcQ(TDfcQue* aDfcQ);

	/** Sets the function to be run when the Idle Timer is completed. This function

	may only be called when the Idle Timer is not queued - attempting otherwise will

	fault the kernel.

	@param	aDfcFn, The function called when the TIdleTimer expires

	*/

	IMPORT_C void SetFunction(TDfcFn aDfcFn);

	/** Starts a one-shot Idle Timer

	The timer will queue a Dfc callback at a time (in nanokernel ticks) between aTime

	and aMaxTime after this function is called. The callback will be made to the previously

	set DfcFn on the requested DfcQue.

	If the default value of KNoTimeout is specified for aMaxTime the Idle Timer will

	have no upper bound on when to schedule the DFC callback. As such, if the device was

	idle at the time aTime number of ticks after the OneShot request was made, the

	Idle Timer will not be completed (i.e. the Dfc callback will not be queued) until the next

	occasion the device comes out of idle.

	@param	aTime the minimum number of nanokernel ticks after which the Dfc callback

			is to be be queued.

	@param	aMaxTime the maximum number of nanokernel ticks before which the Dfc

			callback must be queued.

	@return	KErrNone if no error, KErrInUse if timer is already active, KErrArgument if

			aMaxTime is neither greater than aMinTime nor equal to TIdleTimer::KNoTimeout

	@pre    No fast mutex can be held.

	@pre    Kernel must be unlocked.

	@pre    Call in a thread context.

	@pre    Interrupts must be enabled.

	@see	NKern::TimerTicks()

	*/

    IMPORT_C TInt OneShot(TInt aTime, TInt aMaxTime = KNoTimeout);

	/** Starts a periodic Idle Timer

	The timer will queue a DFC callback at a time (in nanokernel ticks) between aTime and aMaxTime

	after this function is called, and then at successive intervals somewhere between aTime

	and aMaxTime after the previous queuing. The callback will be made to the previously set

	DfcFn on the requested DfcQue. Since the callback is queued automatically, the Idle Timer

	must be explicitly cancelled after Periodic is called on it before it can safely go out of scope.

	If the default value of KNoTimeout is specified for aMaxTime, the Idle Timer will have no

	maximum timeout each cycle. In this case, if the device was idle at the minimum expiry time

	(aTime + time of previous expiry) queuing of the Dfc will not occur until the next time the

	device comes out of idle.

	@param	aTime – the minimum number of nanokernel ticks from the previous completion

			after which the Dfc callback is to be queued.

	@param 	aMaxTime – the maximum number of nanokernel ticks after the previous

			completion before which the Dfc callback must be queued.

	@return	KErrNone if no error, KErrInUse if timer is already active, KErrArgument if 

			aMaxTime is neither greater than aMinTime nor equal to TIdleTimer::KNoTimeout

	@pre    No fast mutex can be held.

	@pre    Kernel must be unlocked.

	@pre    Call in a thread context.

	@pre    Interrupts must be enabled.

	@see    NKern::TimerTicks()

	*/

    IMPORT_C TInt Periodic(TInt aTime, TInt aMaxTime = KNoTimeout);

	/** Cancels an Idle Timer

	This function does nothing if the Idle Timer is not scheduled.

	Note that the implementation of this function is such that, if Cancel is called from a

	thread (i.e. DFC queue) other than the one that the callback is to be made on…

		•	if the callback has started, Cancel will block until the callback has finished

		•	if the callback hasn’t started, Cancel will ensure that it won’t run after Cancel

			has returned

	In order to do this, if called from a different thread, the Cancel function blocks the calling

	thread on a semaphore until the DFC queue thread used for the callback eventually signals it.

	Given this, if the callback function somehow reciprocally blocks on the thread that is calling

	Cancel, a deadlock could occur. It is up to the client to ensure this doesn’t happen.

	To re-iterate - the deadlock scenario described above is only a possibility if Cancel is called

	from a different thread (i.e. DFC queue) than that in which the callback is made. If Cancel

	is called from the same thread then there’s nothing to worry about in this respect.

	@pre    No fast mutex can be held.

	@pre    Kernel must be unlocked.

	@pre    Call in a thread context.

	@pre    Interrupts must be enabled.

	*/

    IMPORT_C void Cancel();

private:

	TInt iData[20];	//Reserved space for implementation

    };

#endif //IDLETIMER_H