// 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;

		}

	T Unmanage()

		{

		iEnabled = EFalse;

		return iHandle;

		}

	TBool IsEnabled() const

		{

		return iEnabled;

		}

	void Disable()

		{

		iEnabled = EFalse;

		}

	void Swap(LAutoHandleBase& aAutoHandle)

		{

		::Swap(iHandle, aAutoHandle.iHandle);

		::Swap(iEnabled, aAutoHandle.iEnabled);

		}

  protected:

	T iHandle;

	TBool iEnabled;

  private:

	LAutoHandleBase(const LAutoHandleBase&);

	LAutoHandleBase& operator=(const LAutoHandleBase&);

	};

/**

   Implementation base class - not designed for public inheritance or

   direct use.  Specialization for types derived from RHandleBase.

*/

template<typename T>

class LAutoHandleBase<T, EAutoRHandleBaseDerived>

	{

  protected:

	LAutoHandleBase()

		{

		}

	template<typename Param1>

	explicit LAutoHandleBase(const Param1& aParam1)

		: iHandle(aParam1)

		{

		}

	template<typename Param1>

	explicit LAutoHandleBase(Param1& aParam1)

		: iHandle(aParam1)

		{

		}

	template<typename Param1,

			 typename Param2>

	LAutoHandleBase(const Param1& aParam1,

					const Param2& aParam2)

		: iHandle(aParam1,

				  aParam2)

		{

		}

	template<typename Param1,

			 typename Param2>

	LAutoHandleBase(Param1& aParam1,

					const Param2& aParam2)

		: iHandle(aParam1,

				  aParam2)

		{

		}

	template<typename Param1,

			 typename Param2>

	LAutoHandleBase(const Param1& aParam1,

					Param2& aParam2)

		: iHandle(aParam1,

				  aParam2)

		{

		}

	template<typename Param1,

			 typename Param2>

	LAutoHandleBase(Param1& aParam1,

					Param2& aParam2)

		: iHandle(aParam1,

				  aParam2)

		{

		}

	template<typename U>

	LAutoHandleBase& operator=(const U& aHandle)

		{

		iHandle = aHandle;

		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;

		}

	T Unmanage()

		{

		T handle = iHandle;

		iHandle.SetHandle(KNullHandle);

		return handle;

		}

	TBool IsEnabled() const

		{

		return iHandle.Handle() != KNullHandle;

		}

	void Disable()

		{

		iHandle.SetHandle(KNullHandle);

		}

	void Swap(LAutoHandleBase& aAutoHandle)

		{

		::Swap(iHandle, aAutoHandle.iHandle);

		}

  protected:

	T iHandle;

  private:

	LAutoHandleBase(const LAutoHandleBase&);

	LAutoHandleBase& operator=(const LAutoHandleBase&);

	};

// N.B. RBuf8, RBuf16 and RBuf cannot be used with LManagedHandle and

// LCleanedupHandle.  Use LString or managed references instead.

// The following specialization must not be used.

template<typename T>

class LAutoHandleBase<T, EAutoHandleRBuf>: protected T

	{

  private:

	LAutoHandleBase()

		{

		}

	~LAutoHandleBase()

		{

		}

	};

/**

   A class template for the creation and automatic management of

   resource handles (typically R-class instances) held in the data

   members of objects.

   @note This class should not used to define locals. See below for

   an explanation and links to management classes suitable for use in

   that context.

   This class template can be used to protect a resource handle of

   type T (typically an R-class instance) such that the instance of T

   protected is automatically cleaned up when the management object is

   destroyed; typically when the object containing it is deleted.

   By default, the cleanup action is to call the Close() member

   function of the managed handle. An alternative cleanup strategy may

   be selected by specifying a cleanup strategy template class in the

   optional second template parameter position. The most common

   alternative cleanup strategies are predefined. It is also possible

   to specialize the default cleanup action for a given class using

   the DEFINE_CLEANUP_FUNCTION macro.

   The constructors of this class never leave (unless construction of

   the underlying T instance can leave, which is rare), so data

   members defined with this type may be initialized safely during any

   phase of construction of the owning class.

   Any arguments supplied when initializing an instance of this class

   are automatically passed through to T's constructors.

   As a convenience, the methods of the managed pointer may be

   accessed via "->" notation directly on the management object, while

   "." notation is used to access the interface of the management

   object itself. Using "*" to dereference the management object

   yields a T&, and is often useful when passing the managed object as

   an argument.

   Automatic cleanup may be disabled at any time by calling

   Unmanage(), while cleanup may be forced at any time by calling

   ReleaseResource().

   Example:

   @code

   class CComposite : public CBase

	   {

	 public:

	   CONSTRUCTORS_MAY_LEAVE

	   CComposite()

		   {

		   iFileServ->Connect() OR_LEAVE;

		   iFile->Open(*iFileServ, ...);

		   }

	   ~CComposite()

		   {

		   // the handles are automatically closed

		   }

	 private:

	   LManagedHandle<RFs> iFileServ;

	   LManagedHandle<RFile> iFile;

	   };

   @endcode

   Behind the scenes, this class template simply relies on reliable

   execution of its destructor. If used for a local variable rather

   than a data member, cleanup will occur but out-of-order compared to

   objects protected using the LCleanupXxx variants or the

   CleanupStack directly. Therefore it is not recommended for use in

   that context.

   These management classes may be used as the basis for implementing

   leave-safe single-phase construction, since fully initialized

   data members protected in this way will get destroyed (so reliably

   triggering cleanup) if their containing classes leave during

   execution of their constructors. Note, however, that single-phase

   construction must be explicitly enabled in the containing class

   using the CONSTRUCTORS_MAY_LEAVE macro.

   This class template together with the cleanup strategy class

   templates provide a template-based implementation of the Strategy

   design pattern (See also: Policy-based design).

   @see TClose which implements the default Close() calling cleanup strategy

   @see TResetAndDestroy which implements an alternative

   ResetAndDestroy() calling cleanup strategy

   @see TFree which implements an alternative Free() calling cleanup

   strategy

   @see TDestroy which implements an alternative Destroy() calling

   cleanup strategy

   @see TRelease which implements an alternative Release() calling cleanup strategy

   @see LCleanedupHandle which has the same interface, but uses the cleanup

   stack and is suitable for protecting locals

   @see CONSTRUCTORS_MAY_LEAVE

*/

template<typename T,

		 class CleanupStrategyType = TResourceCleanupStrategy>

class LManagedHandle: protected LAutoHandleBase<T, IS_HANDLE_SPECIAL(T)>

	{

	typedef LAutoHandleBase<T, IS_HANDLE_SPECIAL(T)> LAutoHandleBase;

  public:

	typedef T ManagedType;

	typedef CleanupStrategyType CleanupStrategy;

/**

   Default constructor.

*/

	LManagedHandle()

		{

		}

	template<typename Param1>

	explicit LManagedHandle(const Param1& aParam1)

		: LAutoHandleBase(aParam1)

		{

		}

	template<typename Param1>

	explicit LManagedHandle(Param1& aParam1)

		: LAutoHandleBase(aParam1)

		{

		}

	template<typename Param1,

			 typename Param2>

	LManagedHandle(const Param1& aParam1,

				   const Param2& aParam2)

		: LAutoHandleBase(aParam1,

					   aParam2)

		{

		}

	template<typename Param1,

			 typename Param2>

	LManagedHandle(const Param1& aParam1,

				   Param2& aParam2)

		: LAutoHandleBase(aParam1,

					   aParam2)

		{

		}

	template<typename Param1,

			 typename Param2>

	LManagedHandle(Param1& aParam1,

				   const Param2& aParam2)

		: LAutoHandleBase(aParam1,

					   aParam2)

		{

		}

	template<typename Param1,

			 typename Param2>

	LManagedHandle(Param1& aParam1,

				   Param2& aParam2)

		: LAutoHandleBase(aParam1,

					   aParam2)

		{

		}

/**

   Assigns a new resource to be managed.  If the LManagedHandle object

   already contains a managed resource handle, then the managed

   resource is released using the specified cleanup strategy before

   assigning the new managed resource.

   @param aHandle a reference to a handle object of a type that can be assigned to a handle object of type T

 */

	template<typename U>

	LManagedHandle& operator=(const U& aHandle)

		{

		ReleaseResource();

		LAutoHandleBase::operator=(aHandle);

		return *this;

		}

/**

   Destructor.	When automatic resource management is enabled, the

   destructor calls the cleanup function defined by the cleanup

   strategy with the contained resource handle object.

 */

	~LManagedHandle()

		{

		if (IsEnabled())

			{

			CleanupStrategy::Cleanup(&Get());

			}

		}

/**

   If automatic resource management is enabled, calls the cleanup

   function defined by the cleanup strategy with the managed resource

   handle object and then disables the automatic resource management

   for this object.	 The cleanup strategy is specified by the

   CleanupStrategy template template parameter.	 The default cleanup

   strategy is to call the cleanup member function on the contained

   resource handle object. which is a member function named Close(),

   unless explicitly defined otherwise for the class of the object,

   for example by using the provided DEFINE_CLEANUP_FUNCTION macro.

*/

	void ReleaseResource()

		{

		if (!IsEnabled())

			return;

		CleanupStrategy::Cleanup(&Get());

		LAutoHandleBase::Disable();

		}

/**

   Disables the automatic resource management for this object and

   returns a copy of the resource handle.

   @return A copy of the resource handle.

*/

	using LAutoHandleBase::Unmanage;

/**

   Returns ETrue if automatic resource management is enabled; EFalse

   otherwise.

   @return ETrue if automatic resource management is enabled; EFalse

   otherwise.

*/

	using LAutoHandleBase::IsEnabled;

/**

   Returns a reference to the resource handle.

   @return A reference to the resource handle.

*/

	using LAutoHandleBase::Get;

/**

   Overloaded indirection operator function.

   @return A reference to the resource handle.

*/

	using LAutoHandleBase::operator*;

/**

   Overloaded class member access operator function.

   @return A pointer to the resource handle.

*/

	using LAutoHandleBase::operator->;

	using LAutoHandleBase::Disable;

	void Swap(LManagedHandle& aManagedHandle)

		{

		LAutoHandleBase::Swap(aManagedHandle);

		}

	};

/**

   Implementation base class - not designed for public inheritance or

   direct use.

   @internalComponent

*/

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

template<typename T>

class LAutoPtrBase

	{

  protected:

	LAutoPtrBase()

		: iPtr(NULL)

		{

		}

	explicit LAutoPtrBase(T* aPtr)

		: iPtr(aPtr)

		{

		}

	LAutoPtrBase& operator=(T* aPtr)

		{

		iPtr = aPtr;

		return *this;

		}

	T* Unmanage()

		{

		T* ptr = iPtr;

		iPtr = NULL;