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

//

#ifndef EMANAGED_H

#define EMANAGED_H

#include <e32base.h>

#include <typerel.h>

#include <swap.h>

/**

   @file

   @brief Utility class templates that provide RAII-based automatic

   resource management.

	 @publishedAll

	 @released

*/

  /**

     Implementation function.In order to override the default cleanup

     strategy for a particular type, use the provided

     DEFINE_CLEANUP_FUNCTION utility macro

     @internalComponent

  */

// Not for Client Use , Only to be used Internally.

template<class T>

inline void CallCleanupFunction(T* aObjPtr)

	{

	aObjPtr->Close();

	}

/**

Utility macro that can be used for defining the cleanup member

function for a class (typically a R-class).

This macro can be used in the same namespace in which the R-class is

defined or in a namespace in which the R-class is used.

Example:

class RDestroyableClass

	{

  public:

	// ...

	void Destroy(); // member function used for cleanup and releasing the resources owned by a RDestroyableClass object

	// ...

	};

DEFINE_CLEANUP_FUNCTION(RDestroyableClass, Destroy)

@param AClass the name of the class

@param CleanupMemFun the name of the cleanup member function of the class

 */

#define DEFINE_CLEANUP_FUNCTION(AClass, CleanupMemFun)	\

	inline void CallCleanupFunction(AClass* aObjPtr)	\

		{												\

		aObjPtr->CleanupMemFun();						\

		}

/**

Utility macro that can be used for specializing the default cleanup

strategy class template TResourceCleanupStrategy for a particular

class (typically a R-class).  The default cleanup strategy for a class

specified using DEFINE_CLEANUP_STRATEGY overrides any other cleanup

strategy specified using DEFINE_CLEANUP_FUNCTION for that class.

This macro must be used in the same namespace in which the R-class is

defined.

   Utility macro that can be used for enabling single phase

   construction for CBase-derived classes. This is necessary because

   Symbian OS currently lacks the placement delete operator

   counterparts corresponding to the placement new operators that take

   a TLeave parameter (new(ELeave)), which will result in memory leaks

   if a class constructor leaves.

   This macro must be used within a public section of a class

   definition, if the single phase construction is part of the public

   interface of the class.

   Current Limitation CONSTRUCTORS_MAY_LEAVE is an unfortunate blight on the

   usability of single-phase construction, but we have yet to come up

   with a better alternative in the face of the legacy handling of

   ELeave.

*/

#define CONSTRUCTORS_MAY_LEAVE											\

	static void operator delete(TAny* aPtr) __NO_THROW					\

		{																\

		::operator delete(aPtr);										\

		}																\

																		\

	static void operator delete(TAny*, TAny*) __NO_THROW				\

		{																\

		}																\

																		\

	static void operator delete(TAny* aPtr, TLeave) __NO_THROW			\

		{																\

		::operator delete(aPtr);										\

		}																\

																		\

	static void operator delete(TAny* aPtr, TUint) __NO_THROW			\

		{																\

		::operator delete(aPtr);										\

		}																\

																		\

	static void operator delete(TAny* aPtr, TLeave, TUint) __NO_THROW	\

		{																\

		::operator delete(aPtr);										\

		}																\

																		\

	static void operator delete[](TAny* aPtr) __NO_THROW				\

		{																\

		::operator delete[](aPtr);										\

		}																\

																		\

	static void operator delete[](TAny* aPtr, TLeave) __NO_THROW		\

		{																\

		::operator delete[](aPtr);										\

		}

// Implementation function.

template<typename T>

void ManagedPopCleanupStackItem(T aIsManaged)

	{

// CleanupStack-based cleanup is automatically triggered by a Leave,

// so, in the case when __LEAVE_EQUALS_THROW__,

// CleanupStack::PopAndDestroy must not be called again here

#ifndef __GCCXML__

// for gccxml builds the std::uncaught_exception function is not listed in std name space

// to supress GCCXML error

	if (!std::uncaught_exception())

		{

		if (aIsManaged)

			{

			CleanupStack::PopAndDestroy();

			}

		else

			{

			CleanupStack::Pop();

			}

		}

#endif		

	}

/**

   Strategy (policy) class that defines the default cleanup strategy

   for managed resource class objects.

   The default cleanup strategy is to call the cleanup member function

   of the managed class, which is the Close() member function of the

   managed class, unless explicitly defined otherwise, for example by

   using the provided DEFINE_CLEANUP_FUNCTION macro.

   @internalComponent

*/

// Not for Client Use , Only to be used Internally.

class TResourceCleanupStrategy

	{

  public:

	template<typename T>

	static void Cleanup(T* aObjPtr)

		{

		CallCleanupFunction(aObjPtr);

		}

	};

/**

   Strategy (policy) class that defines a cleanup strategy for managed

   resource class objects.  This cleanup strategy calls the Close()

   member function of the managed class.

   @see LCleanedupHandle to which this strategy type may be supplied as

   an (optional) second tamplate parameter

   @see LManagedHandle to which this strategy type may be supplied as

   an (optional) second tamplate parameter

*/

class TClose

	{

  public:

	template<class T>

	static void Cleanup(T* aObjPtr)

		{

		aObjPtr->Close();

		}

	};

/**

   Strategy (policy) class that defines a cleanup strategy for managed

   resource class objects.  This cleanup strategy calls the Release()

   member function of the managed class.

   @see LCleanedupHandle to which this strategy type may be supplied as

   an (optional) second tamplate parameter

   @see LManagedHandle to which this strategy type may be supplied as

   an (optional) second tamplate parameter

*/

class TRelease

	{

  public:

	template<class T>

	static void Cleanup(T* aObjPtr)

		{

		aObjPtr->Release();

		}

	};

/**

   Strategy (policy) class that defines a cleanup strategy for managed

   resource class objects.  This cleanup strategy calls the Destroy()

   member function of the managed class.

   @see LCleanedupHandle to which this strategy type may be supplied as

   an (optional) second tamplate parameter

   @see LManagedHandle to which this strategy type may be supplied as

   an (optional) second tamplate parameter

*/

class TDestroy

	{

  public:

	template<class T>

	static void Cleanup(T* aObjPtr)

		{

		aObjPtr->Destroy();

		}

	};

/**

   Strategy (policy) class that defines a cleanup strategy for managed

   resource class objects.  This cleanup strategy calls the Free()

   member function of the managed class.

   @see LCleanedupHandle to which this strategy type may be supplied as

   an (optional) second tamplate parameter

   @see LManagedHandle to which this strategy type may be supplied as

   an (optional) second tamplate parameter

*/

class TFree

	{

  public:

	template<class T>

	static void Cleanup(T* aObjPtr)

		{

		aObjPtr->Free();

		}

	};

/**

   Strategy (policy) class that defines a cleanup strategy for managed

   resource class objects.  This cleanup strategy calls the

   ResetAndDestroy() member function of the managed class.

   @see LCleanedupHandle to which this strategy type may be supplied as

   an (optional) second tamplate parameter

   @see LManagedHandle to which this strategy type may be supplied as

   an (optional) second tamplate parameter

*/

class TResetAndDestroy

	{

  public:

	template<class T>

	static void Cleanup(T* aObjPtr)

		{

		aObjPtr->ResetAndDestroy();

		}

	};

/**

   Strategy (policy) class that defines the default cleanup strategy

   for pointer types.  For pointers to CBase-derived types, the

   default cleanup strategy is to call CBase::Delete with the managed

   pointer.  For pointers to types that are not derived from CBase,

   the default cleanup strategy is to delete the managed pointer using

   non-array delete.

   @see LCleanedupPtr to which this strategy type may be supplied as

   an (optional) second tamplate parameter

   @see LManagedPtr to which this strategy type may be supplied as

   an (optional) second tamplate parameter

*/

class TPtrCleanupStrategy

	{

  public:

	template<typename T>

	static void Cleanup(T* aPtr)

		{

		delete aPtr;

		}

	static void Cleanup(CBase* aPtr)

		{

		CBase::Delete(aPtr);

		}

	};

/**

   Strategy (policy) class that defines a cleanup strategy for pointer

   types.  This cleanup strategy deletes the managed pointer by using

   non-array delete.

   @see LCleanedupPtr to which this strategy type may be supplied as

   an (optional) second tamplate parameter

   @see LManagedPtr to which this strategy type may be supplied as

   an (optional) second tamplate parameter

*/

class TPointerDeleteStrategy

	{

  public:

	template<typename T>

	static void Cleanup(T* aPtr)

		{

		delete aPtr;

		}

	};

/**

   Strategy (policy) class that defines a cleanup strategy for

   pointers to CBase-derived types.  This cleanup strategy calls

   CBase::Delete with the managed pointer.

   @see LCleanedupPtr to which this strategy type may be supplied as

   an (optional) second tamplate parameter

   @see LManagedPtr to which this strategy type may be supplied as

   an (optional) second tamplate parameter

*/

class TCBaseDeleteStrategy

	{

  public:

	static void Cleanup(CBase* aPtr)

		{

		CBase::Delete(aPtr);

		}

	};

/**

   Strategy (policy) class that defines a cleanup strategy for pointer

   types.  This cleanup strategy calls User::Free with the managed

   pointer.

   @see LCleanedupPtr to which this strategy type may be supplied as

   an (optional) second tamplate parameter

   @see LManagedPtr to which this strategy type may be supplied as

   an (optional) second tamplate parameter

*/

class TPointerFree

	{

  public:

	static void Cleanup(TAny* aPtr)

		{

		User::Free(aPtr);

		}

	};

/**

   Strategy (policy) class that defines the default cleanup strategy

   for heap-allocated arrays.  This cleanup strategy deallocates the

   managed array by using array delete.

*/

class TArrayDelete

	{

  public:

	template<typename T>

	static void Cleanup(T* aPtr)

		{

		delete[] aPtr;

		}

	};

// enum type used for identifying the categories of managed pointer types

enum TManagedPtrType

{

	EPtrNonSpecial,

	EPtrCBaseDerived

};

// macro used for determining whether a pointer is special

#define IS_PTR_SPECIAL(T) IS_BASE_OF(CBase, T)

// enum type used for identifying the categories of resource handle types

enum TAutoHandleType

{

	EAutoHandleNonSpecial,

	EAutoRHandleBaseDerived,

	EAutoHandleRBuf

};

// macro used for determining whether a resource handle type is special

#define IS_HANDLE_SPECIAL(T) IS_BASE_OF(RHandleBase, T) ? EAutoRHandleBaseDerived : ( (IS_SAME(RBuf8, T) || IS_SAME(RBuf16, T)) ? EAutoHandleRBuf : EAutoHandleNonSpecial )

/**

   Implementation base class - not designed for public inheritance or

   direct use.

   @internalComponent

*/

// Not for Client Use , Only to be used Internally.

template<typename T,

		 TInt isHandleSpecial = IS_HANDLE_SPECIAL(T)>

class LAutoHandleBase

	{

  protected:

	LAutoHandleBase()

		: iEnabled(ETrue)

		{

		}

	template<typename Param1>

	explicit LAutoHandleBase(const Param1& aParam1)

		: iHandle(aParam1),

		  iEnabled(ETrue)

		{

		}

	template<typename Param1>

	explicit LAutoHandleBase(Param1& aParam1)

		: iHandle(aParam1),

		  iEnabled(ETrue)

		{

		}

	template<typename Param1,

			 typename Param2>

	LAutoHandleBase(const Param1& aParam1,

					const Param2& aParam2)

		: iHandle(aParam1,

				  aParam2),

		  iEnabled(ETrue)

		{

		}

	template<typename Param1,

			 typename Param2>

	LAutoHandleBase(Param1& aParam1,

					const Param2& aParam2)

		: iHandle(aParam1,

				  aParam2),

		  iEnabled(ETrue)

		{

		}

	template<typename Param1,

			 typename Param2>

	LAutoHandleBase(const Param1& aParam1,

					Param2& aParam2)

		: iHandle(aParam1,

				  aParam2),

		  iEnabled(ETrue)

		{

		}

	template<typename Param1,

			 typename Param2>

	LAutoHandleBase(Param1& aParam1,

					Param2& aParam2)

		: iHandle(aParam1,

				  aParam2),

		  iEnabled(ETrue)

		{

		}

	template<typename U>

	LAutoHandleBase& operator=(const U& aHandle)

		{

		iHandle = aHandle;

		iEnabled = ETrue;

		return *this;

		}

	T& Get()

		{

		return iHandle;

		}

	const T& Get() const

		{

		return iHandle;

		}

	T& operator*()

		{

		return iHandle;

		}

	const T& operator*() const

		{

		return iHandle;

		}

	T* operator->()

		{

		return &iHandle;

		}

	const T* operator->() const

		{

		return &iHandle;

		}