// Copyright (c) 2004-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:

// timeout.h - timer manager

// Timer Manager.

//

/**

 @file timeout.h

 @publishedPartner

 @released

*/

#ifndef	__TIMEOUT_H__

#define	__TIMEOUT_H__

#include <e32base.h>

#include "apibase.h"

class RTimeout;

class MTimeoutManager;

//	TimeoutFactory

//	**************

class TimeoutFactory

	/**

	* Factory for creating MTimeoutManager instance(s).

	*

	* TimeoutFactory is not a class that can be instantiated! It only declares

	* static methods, and only publicly available method (NewL) is the one that

	* creates an instance of a timeout manager and returns a reference to the

	* interface class (MTimeoutManager).

	*

	* @publishedPartner

	* @released

	*/

	{

	friend class RTimeout;

public:

	IMPORT_C static MTimeoutManager *NewL(TUint aUnit = 1, TAny *aPtr = 0, TInt aPriority = 0);

private:

	IMPORT_C static void Cancel(RTimeout &aLink);

	IMPORT_C static TBool IsActive(const RTimeout &aLink);

	};

//	MTimeoutManager

//	***************

class MTimeoutManager : public MInetBase

	/**

	* Implementation of "delta queue" timeout manager.

	*

	* The timeout manager provides a timeout callback service

	* for any object. An object using the timeout service only

	* needs to have member variable of RTimeout and define the

	* timeout linkage (TimeoutLinkage) for redirecting the

	* timeout callback to a real function of some object.

	*

	* The same time manager can be used for different object

	* classes. A component can use single timeout manager

	* instance for all of its objects:

	*

	* -# Create timeout manager using TimeoutFactory::NewL

	* -# Objects, which need the timeout callback, declare

	*    the RTimeout member variable and the appropriate

	*    linkage (TimeoutLinkage).

	* -# The timeout callback for a object is requested either

	*	 by RTimeout::Set or MTimeoutManager::Set. The set

	*	 implicitly cancels previous timeout, if active.

	* -# RTimeout::Cancel cancels pending timeout, if any

	*	 is active.

	*

	* Destructions:

	* -# When an object with RTimeout member(s) is destroyed,

	*	 the destructor of this object should include a

	*	 RTimeout::Cancel() for the member variable(s).

	* -# The timeout manager must be deleted, as any normal

	*	 allocated object. All pending timeouts are silently

	*	 cancelled (no expire call will happen for them).

	*

	* The timeout manager maintains an ordered queue of pending timeouts.

	* The next object to expire is always the first in the list, and

	* the timeout manager sets up an internal timer event (RTimer::After)

	* to happen based on the first object.

	*

	* To create an instance of a timeout manager, use TimeoutFactory::NewL.

	*

	* @publishedPartner

	* @released

	*/

	{

public:

	/**

	* Destructor.

	*

	* Even though this is a "mixin" class, the entity that creates

	* it through the TimeoutFactory::NewL() is expected to delete

	* this manager using the returned pointer.

	*/

	virtual ~MTimeoutManager() {};

	/**

	* Activate timeout callback after the specified time.

	*

	* Set a timeout for an object (any previous timeout setting for

	* this object is silently removed, no Expired callback will

	* occur for that). The timeout (aTime) value interpretation is

	* dependent on the aUnit parameter specified for the manager,

	* when it was created (see TimeoutFactory::NewL).

	*

	* @param	aLink	the timeout handle within the object

	* @param	aTime	the time (in fraction of second units).

	*/

	virtual void Set(RTimeout &aLink, TUint aTime) = 0;

	};

//	TimeoutCallback

//	***************

/**

* The callback template.

*

* If the timer expires, the timeout callback is called.

*

* @param	aLink

*		The timeout handle that expired,

* @param	aNow

*		The current time (to which the expiry is based on.

* @param	aPtr

*		The aPtr paramater given in timeout manager instantiation.

*

* @publishedPartner

* @released

*/

typedef void (*TimeoutCallback)(RTimeout &aLink, const TTime &aNow, TAny *aPtr);

//	RTimeout

//	********

class RTimeout

	/**

	* The timeout handle.

	*

	* This can be a member of any object that needs timeout events.

	*

	* The RTimeout can be used as a base for derived classes.

	* 

	* @publishedPartner

	* @released

	*/

	{

	friend class CTimeoutManager;

	friend class TimeoutFactory;

public:

	RTimeout(TimeoutCallback aCallback) : iDelta(0), iExpired(aCallback)

		/**

		* Contructor.

		*

		* @param	aCallback	the expire callback function

		*/

		{

		// Can't use 'this' as initializer, so following is required.

		iNext = this;

		iPrev = this;

		}

	inline void Set(MTimeoutManager *aMgr, TUint aTime)

		/**

		* Activate timeout callback after the specified time.

		*

		* Just an alternate way of calling MTimeoutManager::Set.

		*

		* @param	aMgr	The timeout manager.

		* @param	aTime	The time (in fraction of second units).

		*/

		{

		aMgr->Set(*this, aTime);

		}

	inline TBool IsActive() const

		/**

		* Tests if the timeout is active.

		* @return

		* @li	ETrue, if timeout is active

		* @li	EFalse, if timeout is not active

		*

		* @note

		*	It is always safe to just add the link to a new time manager.

		*	Add will implicitly cancel any previous setting, if such exists.

		*/

		{

		return TimeoutFactory::IsActive(*this);

		}

	inline void Cancel()

		/**

		* Cancel timeout.

		*

		* Cancel removes the timeout (if any) from this link.

		* No Expired() call will happen as a result of this.

		*/

		{

		TimeoutFactory::Cancel(*this);

		}

private:

	RTimeout *iPrev;

	RTimeout *iNext;

	TUint iDelta;

	const TimeoutCallback iExpired;

	};

//	**************

//	TimeoutLinkage

//	**************

template <class T, int Offset>

class TimeoutLinkage

	/**

	* Access "parent" class based on the RTimeout member offset.

	*

	* This is a base template class to convert the link reference into

	* "parent" class refeference. This is just a convenience

	* template and other solutions for defining the the

	* "expired" callback for RTimeout can also be used.

	*

	* A simple use example:

@code

	class CSome

		{

		CSome(aCallback) : iTimeout(aCallback) {};

		~CSome() { iTimeout.Cancel(); }

		Timeout();			// A method to handle the timeout of CSome

	public:

		RTimeout iTimeout;

		};

	class SomeLinkage : public TimeoutLinkage<CSome, _FOFF(CSome, iTimeout)>

		{

	public:

		static void Expired(RTimeout &aLink, const TTime & aNow, TAny *aPtr)

			{

			Object(aLink)->Timeout();

			}

		};

@endcode

	* All of the above can be in the CSome header file, and instances of CSome can now just

	* be created as

@code

	MTimeoutManager *tMgr = TimeoutFactory::NewL(1); // unit = 1s

	...

	CSome x = new CSome(SomeLinkage:Expired);

	...

	x->iTimeout.Set(tMgr, 10); // request timeout after 10s.

	...

	// when not needed, just delete

	delete x;

	delete tMgr;

@endcode

	* and the CSome Timeout() method will be called after 10s, unless

	* cancelled.

	*

	* Instead of using the Timeout in the objects directly, the aPtr parameter

	* of Expired could be an address of a manager type instance,

	* which handles objects of this type. The object itself might not have

	* any use of the Expired call and it should be passed to the manager. This can

	* be realised by defining the linkage Expired as follows (for example)

@code

	static void Expired(RTimeoutLink &aLink, const TTime &aNow, TAny *aPtr)

		{

		((CSomeManager *)aPtr)->Timeout(Object(aLink), aNow);

		}

@endcode

	* @publishedPartner

	* @released

	*/

	{

protected:

	static inline T *Object(RTimeout &aLink)

		/**

		* Gets the "parent object" of RTimeout member.

		*

		* Based on the offset of the RTimeout member, typecast the

		* adjusted pointer to the "parent type", and return the

		* pointer.

		*

		* @param aLink The timeout handle.

		* @return The object.

		*/

		{

		return ((T *)((char *)(&aLink) - Offset));

		}

	};

#endif