Symaptic: os/ossrv/lowlevellibsandfws/genericusabilitylib/inc/emanaged.h@260cb5ec6c19 (annotated)

sl@0	1	// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0	2	// All rights reserved.
sl@0	3	// This component and the accompanying materials are made available
sl@0	4	// under the terms of "Eclipse Public License v1.0"
sl@0	5	// which accompanies this distribution, and is available
sl@0	6	// at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0	7	//
sl@0	8	// Initial Contributors:
sl@0	9	// Nokia Corporation - initial contribution.
sl@0	10	//
sl@0	11	// Contributors:
sl@0	12	//
sl@0	13	// Description:
sl@0	14	//
sl@0	15
sl@0	16	#ifndef EMANAGED_H
sl@0	17	#define EMANAGED_H
sl@0	18
sl@0	19	#include <e32base.h>
sl@0	20
sl@0	21	#include <typerel.h>
sl@0	22	#include <swap.h>
sl@0	23
sl@0	24
sl@0	25
sl@0	26
sl@0	27	/**
sl@0	28	@file
sl@0	29	@brief Utility class templates that provide RAII-based automatic
sl@0	30	resource management.
sl@0	31
sl@0	32	@publishedAll
sl@0	33	@released
sl@0	34	*/
sl@0	35
sl@0	36
sl@0	37	/**
sl@0	38	Implementation function.In order to override the default cleanup
sl@0	39	strategy for a particular type, use the provided
sl@0	40	DEFINE_CLEANUP_FUNCTION utility macro
sl@0	41	@internalComponent
sl@0	42	*/
sl@0	43	// Not for Client Use , Only to be used Internally.
sl@0	44	template<class T>
sl@0	45	inline void CallCleanupFunction(T* aObjPtr)
sl@0	46	{
sl@0	47	aObjPtr->Close();
sl@0	48	}
sl@0	49
sl@0	50
sl@0	51	/**
sl@0	52	Utility macro that can be used for defining the cleanup member
sl@0	53	function for a class (typically a R-class).
sl@0	54
sl@0	55	This macro can be used in the same namespace in which the R-class is
sl@0	56	defined or in a namespace in which the R-class is used.
sl@0	57
sl@0	58	Example:
sl@0	59
sl@0	60	class RDestroyableClass
sl@0	61	{
sl@0	62	public:
sl@0	63	// ...
sl@0	64	void Destroy(); // member function used for cleanup and releasing the resources owned by a RDestroyableClass object
sl@0	65	// ...
sl@0	66	};
sl@0	67
sl@0	68	DEFINE_CLEANUP_FUNCTION(RDestroyableClass, Destroy)
sl@0	69
sl@0	70	@param AClass the name of the class
sl@0	71	@param CleanupMemFun the name of the cleanup member function of the class
sl@0	72	*/
sl@0	73	#define DEFINE_CLEANUP_FUNCTION(AClass, CleanupMemFun) \
sl@0	74	inline void CallCleanupFunction(AClass* aObjPtr) \
sl@0	75	{ \
sl@0	76	aObjPtr->CleanupMemFun(); \
sl@0	77	}
sl@0	78
sl@0	79	/**
sl@0	80	Utility macro that can be used for specializing the default cleanup
sl@0	81	strategy class template TResourceCleanupStrategy for a particular
sl@0	82	class (typically a R-class). The default cleanup strategy for a class
sl@0	83	specified using DEFINE_CLEANUP_STRATEGY overrides any other cleanup
sl@0	84	strategy specified using DEFINE_CLEANUP_FUNCTION for that class.
sl@0	85
sl@0	86	This macro must be used in the same namespace in which the R-class is
sl@0	87	defined.
sl@0	88
sl@0	89
sl@0	90	Utility macro that can be used for enabling single phase
sl@0	91	construction for CBase-derived classes. This is necessary because
sl@0	92	Symbian OS currently lacks the placement delete operator
sl@0	93	counterparts corresponding to the placement new operators that take
sl@0	94	a TLeave parameter (new(ELeave)), which will result in memory leaks
sl@0	95	if a class constructor leaves.
sl@0	96
sl@0	97	This macro must be used within a public section of a class
sl@0	98	definition, if the single phase construction is part of the public
sl@0	99	interface of the class.
sl@0	100
sl@0	101	Current Limitation CONSTRUCTORS_MAY_LEAVE is an unfortunate blight on the
sl@0	102	usability of single-phase construction, but we have yet to come up
sl@0	103	with a better alternative in the face of the legacy handling of
sl@0	104	ELeave.
sl@0	105	*/
sl@0	106	#define CONSTRUCTORS_MAY_LEAVE \
sl@0	107	static void operator delete(TAny* aPtr) __NO_THROW \
sl@0	108	{ \
sl@0	109	::operator delete(aPtr); \
sl@0	110	} \
sl@0	111	\
sl@0	112	static void operator delete(TAny, TAny) __NO_THROW \
sl@0	113	{ \
sl@0	114	} \
sl@0	115	\
sl@0	116	static void operator delete(TAny* aPtr, TLeave) __NO_THROW \
sl@0	117	{ \
sl@0	118	::operator delete(aPtr); \
sl@0	119	} \
sl@0	120	\
sl@0	121	static void operator delete(TAny* aPtr, TUint) __NO_THROW \
sl@0	122	{ \
sl@0	123	::operator delete(aPtr); \
sl@0	124	} \
sl@0	125	\
sl@0	126	static void operator delete(TAny* aPtr, TLeave, TUint) __NO_THROW \
sl@0	127	{ \
sl@0	128	::operator delete(aPtr); \
sl@0	129	} \
sl@0	130	\
sl@0	131	static void operator delete[](TAny* aPtr) __NO_THROW \
sl@0	132	{ \
sl@0	133	::operator delete[](aPtr); \
sl@0	134	} \
sl@0	135	\
sl@0	136	static void operator delete[](TAny* aPtr, TLeave) __NO_THROW \
sl@0	137	{ \
sl@0	138	::operator delete[](aPtr); \
sl@0	139	}
sl@0	140
sl@0	141
sl@0	142	// Implementation function.
sl@0	143	template<typename T>
sl@0	144	void ManagedPopCleanupStackItem(T aIsManaged)
sl@0	145	{
sl@0	146	// CleanupStack-based cleanup is automatically triggered by a Leave,
sl@0	147	// so, in the case when __LEAVE_EQUALS_THROW__,
sl@0	148	// CleanupStack::PopAndDestroy must not be called again here
sl@0	149	#ifndef __GCCXML__
sl@0	150	// for gccxml builds the std::uncaught_exception function is not listed in std name space
sl@0	151	// to supress GCCXML error
sl@0	152	if (!std::uncaught_exception())
sl@0	153	{
sl@0	154	if (aIsManaged)
sl@0	155	{
sl@0	156	CleanupStack::PopAndDestroy();
sl@0	157	}
sl@0	158	else
sl@0	159	{
sl@0	160	CleanupStack::Pop();
sl@0	161	}
sl@0	162	}
sl@0	163	#endif
sl@0	164	}
sl@0	165
sl@0	166	/**
sl@0	167	Strategy (policy) class that defines the default cleanup strategy
sl@0	168	for managed resource class objects.
sl@0	169
sl@0	170	The default cleanup strategy is to call the cleanup member function
sl@0	171	of the managed class, which is the Close() member function of the
sl@0	172	managed class, unless explicitly defined otherwise, for example by
sl@0	173	using the provided DEFINE_CLEANUP_FUNCTION macro.
sl@0	174
sl@0	175	@internalComponent
sl@0	176	*/
sl@0	177	// Not for Client Use , Only to be used Internally.
sl@0	178	class TResourceCleanupStrategy
sl@0	179	{
sl@0	180	public:
sl@0	181	template<typename T>
sl@0	182	static void Cleanup(T* aObjPtr)
sl@0	183	{
sl@0	184	CallCleanupFunction(aObjPtr);
sl@0	185	}
sl@0	186	};
sl@0	187
sl@0	188	/**
sl@0	189	Strategy (policy) class that defines a cleanup strategy for managed
sl@0	190	resource class objects. This cleanup strategy calls the Close()
sl@0	191	member function of the managed class.
sl@0	192
sl@0	193	@see LCleanedupHandle to which this strategy type may be supplied as
sl@0	194	an (optional) second tamplate parameter
sl@0	195	@see LManagedHandle to which this strategy type may be supplied as
sl@0	196	an (optional) second tamplate parameter
sl@0	197	*/
sl@0	198	class TClose
sl@0	199	{
sl@0	200	public:
sl@0	201	template<class T>
sl@0	202	static void Cleanup(T* aObjPtr)
sl@0	203	{
sl@0	204	aObjPtr->Close();
sl@0	205	}
sl@0	206	};
sl@0	207
sl@0	208	/**
sl@0	209	Strategy (policy) class that defines a cleanup strategy for managed
sl@0	210	resource class objects. This cleanup strategy calls the Release()
sl@0	211	member function of the managed class.
sl@0	212
sl@0	213	@see LCleanedupHandle to which this strategy type may be supplied as
sl@0	214	an (optional) second tamplate parameter
sl@0	215	@see LManagedHandle to which this strategy type may be supplied as
sl@0	216	an (optional) second tamplate parameter
sl@0	217	*/
sl@0	218	class TRelease
sl@0	219	{
sl@0	220	public:
sl@0	221	template<class T>
sl@0	222	static void Cleanup(T* aObjPtr)
sl@0	223	{
sl@0	224	aObjPtr->Release();
sl@0	225	}
sl@0	226	};
sl@0	227
sl@0	228	/**
sl@0	229	Strategy (policy) class that defines a cleanup strategy for managed
sl@0	230	resource class objects. This cleanup strategy calls the Destroy()
sl@0	231	member function of the managed class.
sl@0	232
sl@0	233	@see LCleanedupHandle to which this strategy type may be supplied as
sl@0	234	an (optional) second tamplate parameter
sl@0	235	@see LManagedHandle to which this strategy type may be supplied as
sl@0	236	an (optional) second tamplate parameter
sl@0	237	*/
sl@0	238	class TDestroy
sl@0	239	{
sl@0	240	public:
sl@0	241	template<class T>
sl@0	242	static void Cleanup(T* aObjPtr)
sl@0	243	{
sl@0	244	aObjPtr->Destroy();
sl@0	245	}
sl@0	246	};
sl@0	247
sl@0	248	/**
sl@0	249	Strategy (policy) class that defines a cleanup strategy for managed
sl@0	250	resource class objects. This cleanup strategy calls the Free()
sl@0	251	member function of the managed class.
sl@0	252
sl@0	253	@see LCleanedupHandle to which this strategy type may be supplied as
sl@0	254	an (optional) second tamplate parameter
sl@0	255	@see LManagedHandle to which this strategy type may be supplied as
sl@0	256	an (optional) second tamplate parameter
sl@0	257	*/
sl@0	258	class TFree
sl@0	259	{
sl@0	260	public:
sl@0	261	template<class T>
sl@0	262	static void Cleanup(T* aObjPtr)
sl@0	263	{
sl@0	264	aObjPtr->Free();
sl@0	265	}
sl@0	266	};
sl@0	267
sl@0	268	/**
sl@0	269	Strategy (policy) class that defines a cleanup strategy for managed
sl@0	270	resource class objects. This cleanup strategy calls the
sl@0	271	ResetAndDestroy() member function of the managed class.
sl@0	272
sl@0	273	@see LCleanedupHandle to which this strategy type may be supplied as
sl@0	274	an (optional) second tamplate parameter
sl@0	275	@see LManagedHandle to which this strategy type may be supplied as
sl@0	276	an (optional) second tamplate parameter
sl@0	277	*/
sl@0	278	class TResetAndDestroy
sl@0	279	{
sl@0	280	public:
sl@0	281	template<class T>
sl@0	282	static void Cleanup(T* aObjPtr)
sl@0	283	{
sl@0	284	aObjPtr->ResetAndDestroy();
sl@0	285	}
sl@0	286	};
sl@0	287
sl@0	288
sl@0	289	/**
sl@0	290	Strategy (policy) class that defines the default cleanup strategy
sl@0	291	for pointer types. For pointers to CBase-derived types, the
sl@0	292	default cleanup strategy is to call CBase::Delete with the managed
sl@0	293	pointer. For pointers to types that are not derived from CBase,
sl@0	294	the default cleanup strategy is to delete the managed pointer using
sl@0	295	non-array delete.
sl@0	296
sl@0	297	@see LCleanedupPtr to which this strategy type may be supplied as
sl@0	298	an (optional) second tamplate parameter
sl@0	299	@see LManagedPtr to which this strategy type may be supplied as
sl@0	300	an (optional) second tamplate parameter
sl@0	301	*/
sl@0	302	class TPtrCleanupStrategy
sl@0	303	{
sl@0	304	public:
sl@0	305	template<typename T>
sl@0	306	static void Cleanup(T* aPtr)
sl@0	307	{
sl@0	308	delete aPtr;
sl@0	309	}
sl@0	310
sl@0	311	static void Cleanup(CBase* aPtr)
sl@0	312	{
sl@0	313	CBase::Delete(aPtr);
sl@0	314	}
sl@0	315	};
sl@0	316
sl@0	317
sl@0	318	/**
sl@0	319	Strategy (policy) class that defines a cleanup strategy for pointer
sl@0	320	types. This cleanup strategy deletes the managed pointer by using
sl@0	321	non-array delete.
sl@0	322
sl@0	323	@see LCleanedupPtr to which this strategy type may be supplied as
sl@0	324	an (optional) second tamplate parameter
sl@0	325	@see LManagedPtr to which this strategy type may be supplied as
sl@0	326	an (optional) second tamplate parameter
sl@0	327	*/
sl@0	328	class TPointerDeleteStrategy
sl@0	329	{
sl@0	330	public:
sl@0	331	template<typename T>
sl@0	332	static void Cleanup(T* aPtr)
sl@0	333	{
sl@0	334	delete aPtr;
sl@0	335	}
sl@0	336	};
sl@0	337
sl@0	338
sl@0	339	/**
sl@0	340	Strategy (policy) class that defines a cleanup strategy for
sl@0	341	pointers to CBase-derived types. This cleanup strategy calls
sl@0	342	CBase::Delete with the managed pointer.
sl@0	343
sl@0	344	@see LCleanedupPtr to which this strategy type may be supplied as
sl@0	345	an (optional) second tamplate parameter
sl@0	346	@see LManagedPtr to which this strategy type may be supplied as
sl@0	347	an (optional) second tamplate parameter
sl@0	348	*/
sl@0	349	class TCBaseDeleteStrategy
sl@0	350	{
sl@0	351	public:
sl@0	352	static void Cleanup(CBase* aPtr)
sl@0	353	{
sl@0	354	CBase::Delete(aPtr);
sl@0	355	}
sl@0	356	};
sl@0	357
sl@0	358
sl@0	359	/**
sl@0	360	Strategy (policy) class that defines a cleanup strategy for pointer
sl@0	361	types. This cleanup strategy calls User::Free with the managed
sl@0	362	pointer.
sl@0	363
sl@0	364	@see LCleanedupPtr to which this strategy type may be supplied as
sl@0	365	an (optional) second tamplate parameter
sl@0	366	@see LManagedPtr to which this strategy type may be supplied as
sl@0	367	an (optional) second tamplate parameter
sl@0	368	*/
sl@0	369	class TPointerFree
sl@0	370	{
sl@0	371	public:
sl@0	372	static void Cleanup(TAny* aPtr)
sl@0	373	{
sl@0	374	User::Free(aPtr);
sl@0	375	}
sl@0	376	};
sl@0	377
sl@0	378
sl@0	379	/**
sl@0	380	Strategy (policy) class that defines the default cleanup strategy
sl@0	381	for heap-allocated arrays. This cleanup strategy deallocates the
sl@0	382	managed array by using array delete.
sl@0	383	*/
sl@0	384	class TArrayDelete
sl@0	385	{
sl@0	386	public:
sl@0	387	template<typename T>
sl@0	388	static void Cleanup(T* aPtr)
sl@0	389	{
sl@0	390	delete[] aPtr;
sl@0	391	}
sl@0	392	};
sl@0	393
sl@0	394
sl@0	395	// enum type used for identifying the categories of managed pointer types
sl@0	396	enum TManagedPtrType
sl@0	397	{
sl@0	398	EPtrNonSpecial,
sl@0	399	EPtrCBaseDerived
sl@0	400	};
sl@0	401
sl@0	402
sl@0	403	// macro used for determining whether a pointer is special
sl@0	404	#define IS_PTR_SPECIAL(T) IS_BASE_OF(CBase, T)
sl@0	405
sl@0	406
sl@0	407	// enum type used for identifying the categories of resource handle types
sl@0	408	enum TAutoHandleType
sl@0	409	{
sl@0	410	EAutoHandleNonSpecial,
sl@0	411	EAutoRHandleBaseDerived,
sl@0	412	EAutoHandleRBuf
sl@0	413	};
sl@0	414
sl@0	415
sl@0	416	// macro used for determining whether a resource handle type is special
sl@0	417	#define IS_HANDLE_SPECIAL(T) IS_BASE_OF(RHandleBase, T) ? EAutoRHandleBaseDerived : ( (IS_SAME(RBuf8, T) \|\| IS_SAME(RBuf16, T)) ? EAutoHandleRBuf : EAutoHandleNonSpecial )
sl@0	418
sl@0	419
sl@0	420	/**
sl@0	421	Implementation base class - not designed for public inheritance or
sl@0	422	direct use.
sl@0	423
sl@0	424	@internalComponent
sl@0	425	*/
sl@0	426	// Not for Client Use , Only to be used Internally.
sl@0	427	template<typename T,
sl@0	428	TInt isHandleSpecial = IS_HANDLE_SPECIAL(T)>
sl@0	429	class LAutoHandleBase
sl@0	430	{
sl@0	431	protected:
sl@0	432	LAutoHandleBase()
sl@0	433	: iEnabled(ETrue)
sl@0	434	{
sl@0	435	}
sl@0	436
sl@0	437	template<typename Param1>
sl@0	438	explicit LAutoHandleBase(const Param1& aParam1)
sl@0	439	: iHandle(aParam1),
sl@0	440	iEnabled(ETrue)
sl@0	441	{
sl@0	442	}
sl@0	443
sl@0	444	template<typename Param1>
sl@0	445	explicit LAutoHandleBase(Param1& aParam1)
sl@0	446	: iHandle(aParam1),
sl@0	447	iEnabled(ETrue)
sl@0	448	{
sl@0	449	}
sl@0	450
sl@0	451	template<typename Param1,
sl@0	452	typename Param2>
sl@0	453	LAutoHandleBase(const Param1& aParam1,
sl@0	454	const Param2& aParam2)
sl@0	455	: iHandle(aParam1,
sl@0	456	aParam2),
sl@0	457	iEnabled(ETrue)
sl@0	458	{
sl@0	459	}
sl@0	460
sl@0	461	template<typename Param1,
sl@0	462	typename Param2>
sl@0	463	LAutoHandleBase(Param1& aParam1,
sl@0	464	const Param2& aParam2)
sl@0	465	: iHandle(aParam1,
sl@0	466	aParam2),
sl@0	467	iEnabled(ETrue)
sl@0	468	{
sl@0	469	}
sl@0	470
sl@0	471	template<typename Param1,
sl@0	472	typename Param2>
sl@0	473	LAutoHandleBase(const Param1& aParam1,
sl@0	474	Param2& aParam2)
sl@0	475	: iHandle(aParam1,
sl@0	476	aParam2),
sl@0	477	iEnabled(ETrue)
sl@0	478	{
sl@0	479	}
sl@0	480
sl@0	481	template<typename Param1,
sl@0	482	typename Param2>
sl@0	483	LAutoHandleBase(Param1& aParam1,
sl@0	484	Param2& aParam2)
sl@0	485	: iHandle(aParam1,
sl@0	486	aParam2),
sl@0	487	iEnabled(ETrue)
sl@0	488	{
sl@0	489	}
sl@0	490
sl@0	491	template<typename U>
sl@0	492	LAutoHandleBase& operator=(const U& aHandle)
sl@0	493	{
sl@0	494	iHandle = aHandle;
sl@0	495	iEnabled = ETrue;
sl@0	496	return *this;
sl@0	497	}
sl@0	498
sl@0	499	T& Get()
sl@0	500	{
sl@0	501	return iHandle;
sl@0	502	}
sl@0	503
sl@0	504	const T& Get() const
sl@0	505	{
sl@0	506	return iHandle;
sl@0	507	}
sl@0	508
sl@0	509	T& operator*()
sl@0	510	{
sl@0	511	return iHandle;
sl@0	512	}
sl@0	513
sl@0	514	const T& operator*() const
sl@0	515	{
sl@0	516	return iHandle;
sl@0	517	}
sl@0	518
sl@0	519	T* operator->()
sl@0	520	{
sl@0	521	return &iHandle;
sl@0	522	}
sl@0	523
sl@0	524	const T* operator->() const
sl@0	525	{
sl@0	526	return &iHandle;
sl@0	527	}
sl@0	528
sl@0	529	T Unmanage()
sl@0	530	{
sl@0	531	iEnabled = EFalse;
sl@0	532	return iHandle;
sl@0	533	}
sl@0	534
sl@0	535	TBool IsEnabled() const
sl@0	536	{
sl@0	537	return iEnabled;
sl@0	538	}
sl@0	539
sl@0	540	void Disable()
sl@0	541	{
sl@0	542	iEnabled = EFalse;
sl@0	543	}
sl@0	544
sl@0	545	void Swap(LAutoHandleBase& aAutoHandle)
sl@0	546	{
sl@0	547	::Swap(iHandle, aAutoHandle.iHandle);
sl@0	548	::Swap(iEnabled, aAutoHandle.iEnabled);
sl@0	549	}
sl@0	550
sl@0	551	protected:
sl@0	552	T iHandle;
sl@0	553	TBool iEnabled;
sl@0	554
sl@0	555	private:
sl@0	556	LAutoHandleBase(const LAutoHandleBase&);
sl@0	557	LAutoHandleBase& operator=(const LAutoHandleBase&);
sl@0	558	};
sl@0	559
sl@0	560
sl@0	561	/**
sl@0	562	Implementation base class - not designed for public inheritance or
sl@0	563	direct use. Specialization for types derived from RHandleBase.
sl@0	564	*/
sl@0	565	template<typename T>
sl@0	566	class LAutoHandleBase<T, EAutoRHandleBaseDerived>
sl@0	567	{
sl@0	568	protected:
sl@0	569	LAutoHandleBase()
sl@0	570	{
sl@0	571	}
sl@0	572
sl@0	573	template<typename Param1>
sl@0	574	explicit LAutoHandleBase(const Param1& aParam1)
sl@0	575	: iHandle(aParam1)
sl@0	576	{
sl@0	577	}
sl@0	578
sl@0	579	template<typename Param1>
sl@0	580	explicit LAutoHandleBase(Param1& aParam1)
sl@0	581	: iHandle(aParam1)
sl@0	582	{
sl@0	583	}
sl@0	584
sl@0	585	template<typename Param1,
sl@0	586	typename Param2>
sl@0	587	LAutoHandleBase(const Param1& aParam1,
sl@0	588	const Param2& aParam2)
sl@0	589	: iHandle(aParam1,
sl@0	590	aParam2)
sl@0	591	{
sl@0	592	}
sl@0	593
sl@0	594	template<typename Param1,
sl@0	595	typename Param2>
sl@0	596	LAutoHandleBase(Param1& aParam1,
sl@0	597	const Param2& aParam2)
sl@0	598	: iHandle(aParam1,
sl@0	599	aParam2)
sl@0	600	{
sl@0	601	}
sl@0	602
sl@0	603	template<typename Param1,
sl@0	604	typename Param2>
sl@0	605	LAutoHandleBase(const Param1& aParam1,
sl@0	606	Param2& aParam2)
sl@0	607	: iHandle(aParam1,
sl@0	608	aParam2)
sl@0	609	{
sl@0	610	}
sl@0	611
sl@0	612	template<typename Param1,
sl@0	613	typename Param2>
sl@0	614	LAutoHandleBase(Param1& aParam1,
sl@0	615	Param2& aParam2)
sl@0	616	: iHandle(aParam1,
sl@0	617	aParam2)
sl@0	618	{
sl@0	619	}
sl@0	620
sl@0	621	template<typename U>
sl@0	622	LAutoHandleBase& operator=(const U& aHandle)
sl@0	623	{
sl@0	624	iHandle = aHandle;
sl@0	625	return *this;
sl@0	626	}
sl@0	627
sl@0	628	T& Get()
sl@0	629	{
sl@0	630	return iHandle;
sl@0	631	}
sl@0	632
sl@0	633	const T& Get() const
sl@0	634	{
sl@0	635	return iHandle;
sl@0	636	}
sl@0	637
sl@0	638	T& operator*()
sl@0	639	{
sl@0	640	return iHandle;
sl@0	641	}
sl@0	642
sl@0	643	const T& operator*() const
sl@0	644	{
sl@0	645	return iHandle;
sl@0	646	}
sl@0	647
sl@0	648	T* operator->()
sl@0	649	{
sl@0	650	return &iHandle;
sl@0	651	}
sl@0	652
sl@0	653	const T* operator->() const
sl@0	654	{
sl@0	655	return &iHandle;
sl@0	656	}
sl@0	657
sl@0	658	T Unmanage()
sl@0	659	{
sl@0	660	T handle = iHandle;
sl@0	661	iHandle.SetHandle(KNullHandle);
sl@0	662	return handle;
sl@0	663	}
sl@0	664
sl@0	665	TBool IsEnabled() const
sl@0	666	{
sl@0	667	return iHandle.Handle() != KNullHandle;
sl@0	668	}
sl@0	669
sl@0	670	void Disable()
sl@0	671	{
sl@0	672	iHandle.SetHandle(KNullHandle);
sl@0	673	}
sl@0	674
sl@0	675	void Swap(LAutoHandleBase& aAutoHandle)
sl@0	676	{
sl@0	677	::Swap(iHandle, aAutoHandle.iHandle);
sl@0	678	}
sl@0	679
sl@0	680	protected:
sl@0	681	T iHandle;
sl@0	682
sl@0	683	private:
sl@0	684	LAutoHandleBase(const LAutoHandleBase&);
sl@0	685	LAutoHandleBase& operator=(const LAutoHandleBase&);
sl@0	686	};
sl@0	687
sl@0	688
sl@0	689	// N.B. RBuf8, RBuf16 and RBuf cannot be used with LManagedHandle and
sl@0	690	// LCleanedupHandle. Use LString or managed references instead.
sl@0	691	// The following specialization must not be used.
sl@0	692	template<typename T>
sl@0	693	class LAutoHandleBase<T, EAutoHandleRBuf>: protected T
sl@0	694	{
sl@0	695	private:
sl@0	696	LAutoHandleBase()
sl@0	697	{
sl@0	698	}
sl@0	699
sl@0	700	~LAutoHandleBase()
sl@0	701	{
sl@0	702	}
sl@0	703	};
sl@0	704
sl@0	705
sl@0	706	/**
sl@0	707	A class template for the creation and automatic management of
sl@0	708	resource handles (typically R-class instances) held in the data
sl@0	709	members of objects.
sl@0	710
sl@0	711	@note This class should not used to define locals. See below for
sl@0	712	an explanation and links to management classes suitable for use in
sl@0	713	that context.
sl@0	714
sl@0	715	This class template can be used to protect a resource handle of
sl@0	716	type T (typically an R-class instance) such that the instance of T
sl@0	717	protected is automatically cleaned up when the management object is
sl@0	718	destroyed; typically when the object containing it is deleted.
sl@0	719
sl@0	720	By default, the cleanup action is to call the Close() member
sl@0	721	function of the managed handle. An alternative cleanup strategy may
sl@0	722	be selected by specifying a cleanup strategy template class in the
sl@0	723	optional second template parameter position. The most common
sl@0	724	alternative cleanup strategies are predefined. It is also possible
sl@0	725	to specialize the default cleanup action for a given class using
sl@0	726	the DEFINE_CLEANUP_FUNCTION macro.
sl@0	727
sl@0	728	The constructors of this class never leave (unless construction of
sl@0	729	the underlying T instance can leave, which is rare), so data
sl@0	730	members defined with this type may be initialized safely during any
sl@0	731	phase of construction of the owning class.
sl@0	732
sl@0	733	Any arguments supplied when initializing an instance of this class
sl@0	734	are automatically passed through to T's constructors.
sl@0	735
sl@0	736	As a convenience, the methods of the managed pointer may be
sl@0	737	accessed via "->" notation directly on the management object, while
sl@0	738	"." notation is used to access the interface of the management
sl@0	739	object itself. Using "*" to dereference the management object
sl@0	740	yields a T&, and is often useful when passing the managed object as
sl@0	741	an argument.
sl@0	742
sl@0	743	Automatic cleanup may be disabled at any time by calling
sl@0	744	Unmanage(), while cleanup may be forced at any time by calling
sl@0	745	ReleaseResource().
sl@0	746
sl@0	747	Example:
sl@0	748	@code
sl@0	749	class CComposite : public CBase
sl@0	750	{
sl@0	751	public:
sl@0	752	CONSTRUCTORS_MAY_LEAVE
sl@0	753
sl@0	754	CComposite()
sl@0	755	{
sl@0	756	iFileServ->Connect() OR_LEAVE;
sl@0	757	iFile->Open(*iFileServ, ...);
sl@0	758	}
sl@0	759
sl@0	760	~CComposite()
sl@0	761	{
sl@0	762	// the handles are automatically closed
sl@0	763	}
sl@0	764
sl@0	765	private:
sl@0	766
sl@0	767	LManagedHandle<RFs> iFileServ;
sl@0	768	LManagedHandle<RFile> iFile;
sl@0	769	};
sl@0	770	@endcode
sl@0	771
sl@0	772	Behind the scenes, this class template simply relies on reliable
sl@0	773	execution of its destructor. If used for a local variable rather
sl@0	774	than a data member, cleanup will occur but out-of-order compared to
sl@0	775	objects protected using the LCleanupXxx variants or the
sl@0	776	CleanupStack directly. Therefore it is not recommended for use in
sl@0	777	that context.
sl@0	778
sl@0	779	These management classes may be used as the basis for implementing
sl@0	780	leave-safe single-phase construction, since fully initialized
sl@0	781	data members protected in this way will get destroyed (so reliably
sl@0	782	triggering cleanup) if their containing classes leave during
sl@0	783	execution of their constructors. Note, however, that single-phase
sl@0	784	construction must be explicitly enabled in the containing class
sl@0	785	using the CONSTRUCTORS_MAY_LEAVE macro.
sl@0	786
sl@0	787	This class template together with the cleanup strategy class
sl@0	788	templates provide a template-based implementation of the Strategy
sl@0	789	design pattern (See also: Policy-based design).
sl@0	790
sl@0	791	@see TClose which implements the default Close() calling cleanup strategy
sl@0	792	@see TResetAndDestroy which implements an alternative
sl@0	793	ResetAndDestroy() calling cleanup strategy
sl@0	794	@see TFree which implements an alternative Free() calling cleanup
sl@0	795	strategy
sl@0	796	@see TDestroy which implements an alternative Destroy() calling
sl@0	797	cleanup strategy
sl@0	798	@see TRelease which implements an alternative Release() calling cleanup strategy
sl@0	799	@see LCleanedupHandle which has the same interface, but uses the cleanup
sl@0	800	stack and is suitable for protecting locals
sl@0	801	@see CONSTRUCTORS_MAY_LEAVE
sl@0	802	*/
sl@0	803	template<typename T,
sl@0	804	class CleanupStrategyType = TResourceCleanupStrategy>
sl@0	805	class LManagedHandle: protected LAutoHandleBase<T, IS_HANDLE_SPECIAL(T)>
sl@0	806	{
sl@0	807	typedef LAutoHandleBase<T, IS_HANDLE_SPECIAL(T)> LAutoHandleBase;
sl@0	808
sl@0	809	public:
sl@0	810	typedef T ManagedType;
sl@0	811	typedef CleanupStrategyType CleanupStrategy;
sl@0	812
sl@0	813	/**
sl@0	814	Default constructor.
sl@0	815	*/
sl@0	816	LManagedHandle()
sl@0	817	{
sl@0	818	}
sl@0	819
sl@0	820	template<typename Param1>
sl@0	821	explicit LManagedHandle(const Param1& aParam1)
sl@0	822	: LAutoHandleBase(aParam1)
sl@0	823	{
sl@0	824	}
sl@0	825
sl@0	826	template<typename Param1>
sl@0	827	explicit LManagedHandle(Param1& aParam1)
sl@0	828	: LAutoHandleBase(aParam1)
sl@0	829	{
sl@0	830	}
sl@0	831
sl@0	832	template<typename Param1,
sl@0	833	typename Param2>
sl@0	834	LManagedHandle(const Param1& aParam1,
sl@0	835	const Param2& aParam2)
sl@0	836	: LAutoHandleBase(aParam1,
sl@0	837	aParam2)
sl@0	838	{
sl@0	839	}
sl@0	840
sl@0	841	template<typename Param1,
sl@0	842	typename Param2>
sl@0	843	LManagedHandle(const Param1& aParam1,
sl@0	844	Param2& aParam2)
sl@0	845	: LAutoHandleBase(aParam1,
sl@0	846	aParam2)
sl@0	847	{
sl@0	848	}
sl@0	849
sl@0	850	template<typename Param1,
sl@0	851	typename Param2>
sl@0	852	LManagedHandle(Param1& aParam1,
sl@0	853	const Param2& aParam2)
sl@0	854	: LAutoHandleBase(aParam1,
sl@0	855	aParam2)
sl@0	856	{
sl@0	857	}
sl@0	858
sl@0	859	template<typename Param1,
sl@0	860	typename Param2>
sl@0	861	LManagedHandle(Param1& aParam1,
sl@0	862	Param2& aParam2)
sl@0	863	: LAutoHandleBase(aParam1,
sl@0	864	aParam2)
sl@0	865	{
sl@0	866	}
sl@0	867
sl@0	868	/**
sl@0	869	Assigns a new resource to be managed. If the LManagedHandle object
sl@0	870	already contains a managed resource handle, then the managed
sl@0	871	resource is released using the specified cleanup strategy before
sl@0	872	assigning the new managed resource.
sl@0	873
sl@0	874	@param aHandle a reference to a handle object of a type that can be assigned to a handle object of type T
sl@0	875	*/
sl@0	876	template<typename U>
sl@0	877	LManagedHandle& operator=(const U& aHandle)
sl@0	878	{
sl@0	879	ReleaseResource();
sl@0	880	LAutoHandleBase::operator=(aHandle);
sl@0	881	return *this;
sl@0	882	}
sl@0	883
sl@0	884	/**
sl@0	885	Destructor. When automatic resource management is enabled, the
sl@0	886	destructor calls the cleanup function defined by the cleanup
sl@0	887	strategy with the contained resource handle object.
sl@0	888	*/
sl@0	889	~LManagedHandle()
sl@0	890	{
sl@0	891	if (IsEnabled())
sl@0	892	{
sl@0	893	CleanupStrategy::Cleanup(&Get());
sl@0	894	}
sl@0	895	}
sl@0	896
sl@0	897	/**
sl@0	898	If automatic resource management is enabled, calls the cleanup
sl@0	899	function defined by the cleanup strategy with the managed resource
sl@0	900	handle object and then disables the automatic resource management
sl@0	901	for this object. The cleanup strategy is specified by the
sl@0	902	CleanupStrategy template template parameter. The default cleanup
sl@0	903	strategy is to call the cleanup member function on the contained
sl@0	904	resource handle object. which is a member function named Close(),
sl@0	905	unless explicitly defined otherwise for the class of the object,
sl@0	906	for example by using the provided DEFINE_CLEANUP_FUNCTION macro.
sl@0	907	*/
sl@0	908	void ReleaseResource()
sl@0	909	{
sl@0	910	if (!IsEnabled())
sl@0	911	return;
sl@0	912
sl@0	913	CleanupStrategy::Cleanup(&Get());
sl@0	914	LAutoHandleBase::Disable();
sl@0	915	}
sl@0	916
sl@0	917	/**
sl@0	918	Disables the automatic resource management for this object and
sl@0	919	returns a copy of the resource handle.
sl@0	920
sl@0	921	@return A copy of the resource handle.
sl@0	922	*/
sl@0	923	using LAutoHandleBase::Unmanage;
sl@0	924
sl@0	925	/**
sl@0	926	Returns ETrue if automatic resource management is enabled; EFalse
sl@0	927	otherwise.
sl@0	928
sl@0	929	@return ETrue if automatic resource management is enabled; EFalse
sl@0	930	otherwise.
sl@0	931	*/
sl@0	932	using LAutoHandleBase::IsEnabled;
sl@0	933
sl@0	934	/**
sl@0	935	Returns a reference to the resource handle.
sl@0	936
sl@0	937	@return A reference to the resource handle.
sl@0	938	*/
sl@0	939	using LAutoHandleBase::Get;
sl@0	940
sl@0	941	/**
sl@0	942	Overloaded indirection operator function.
sl@0	943
sl@0	944	@return A reference to the resource handle.
sl@0	945	*/
sl@0	946	using LAutoHandleBase::operator*;
sl@0	947
sl@0	948	/**
sl@0	949	Overloaded class member access operator function.
sl@0	950
sl@0	951	@return A pointer to the resource handle.
sl@0	952	*/
sl@0	953	using LAutoHandleBase::operator->;
sl@0	954
sl@0	955	using LAutoHandleBase::Disable;
sl@0	956
sl@0	957	void Swap(LManagedHandle& aManagedHandle)
sl@0	958	{
sl@0	959	LAutoHandleBase::Swap(aManagedHandle);
sl@0	960	}
sl@0	961	};
sl@0	962
sl@0	963
sl@0	964	/**
sl@0	965	Implementation base class - not designed for public inheritance or
sl@0	966	direct use.
sl@0	967
sl@0	968	@internalComponent
sl@0	969	*/
sl@0	970	// Not for Client Use , Only to be used Internally.
sl@0	971	template<typename T>
sl@0	972	class LAutoPtrBase
sl@0	973	{
sl@0	974	protected:
sl@0	975	LAutoPtrBase()
sl@0	976	: iPtr(NULL)
sl@0	977	{
sl@0	978	}
sl@0	979
sl@0	980	explicit LAutoPtrBase(T* aPtr)
sl@0	981	: iPtr(aPtr)
sl@0	982	{
sl@0	983	}
sl@0	984
sl@0	985	LAutoPtrBase& operator=(T* aPtr)
sl@0	986	{
sl@0	987	iPtr = aPtr;
sl@0	988	return *this;
sl@0	989	}
sl@0	990
sl@0	991	T* Unmanage()
sl@0	992	{
sl@0	993	T* ptr = iPtr;
sl@0	994	iPtr = NULL;
sl@0	995	return ptr;
sl@0	996	}
sl@0	997
sl@0	998	TBool IsEnabled() const
sl@0	999	{
sl@0	1000	return iPtr != NULL;
sl@0	1001	}
sl@0	1002
sl@0	1003	T* Get() const
sl@0	1004	{
sl@0	1005	return iPtr;
sl@0	1006	}
sl@0	1007
sl@0	1008	T* operator->() const
sl@0	1009	{
sl@0	1010	return iPtr;
sl@0	1011	}
sl@0	1012
sl@0	1013	void Disable()
sl@0	1014	{
sl@0	1015	iPtr = NULL;
sl@0	1016	}
sl@0	1017
sl@0	1018	void Swap(LAutoPtrBase& aAutoPtr)
sl@0	1019	{
sl@0	1020	::Swap(iPtr, aAutoPtr.iPtr);
sl@0	1021	}
sl@0	1022
sl@0	1023	protected:
sl@0	1024	T* iPtr;
sl@0	1025
sl@0	1026	private:
sl@0	1027	LAutoPtrBase(const LAutoPtrBase&);
sl@0	1028	LAutoPtrBase& operator=(const LAutoPtrBase&);
sl@0	1029	};
sl@0	1030
sl@0	1031
sl@0	1032	// Cleanup traits class template
sl@0	1033	template<typename T,
sl@0	1034	class CleanupStrategyType,
sl@0	1035	TInt isPtrSpecial = IS_PTR_SPECIAL(T)>
sl@0	1036	struct TPtrCleanupTraits
sl@0	1037	{
sl@0	1038	};
sl@0	1039
sl@0	1040
sl@0	1041	// Cleanup traits class template specialization for pointers to types
sl@0	1042	// that are not derived from CBase
sl@0	1043	template<typename T,
sl@0	1044	class CleanupStrategyType>
sl@0	1045	struct TPtrCleanupTraits<T, CleanupStrategyType, EPtrNonSpecial>
sl@0	1046	{
sl@0	1047	typedef T ManagedType;
sl@0	1048	typedef T BaseManagedType;
sl@0	1049	typedef CleanupStrategyType CleanupStrategy;
sl@0	1050	};
sl@0	1051
sl@0	1052	// Cleanup traits class template specialization for pointers to types
sl@0	1053	// that are derived from CBase
sl@0	1054	template<typename T,
sl@0	1055	class CleanupStrategyType>
sl@0	1056	struct TPtrCleanupTraits<T, CleanupStrategyType, EPtrCBaseDerived>
sl@0	1057	{
sl@0	1058	typedef T ManagedType;
sl@0	1059	typedef CBase BaseManagedType;
sl@0	1060	typedef CleanupStrategyType CleanupStrategy;
sl@0	1061	};
sl@0	1062
sl@0	1063	// Cleanup traits class template specialization for pointers to types
sl@0	1064	// that are derived from CBase and the default pointer cleanup
sl@0	1065	// strategy (TPtrCleanupStrategy)
sl@0	1066	template<typename T>
sl@0	1067	struct TPtrCleanupTraits<T, TPtrCleanupStrategy, EPtrCBaseDerived>
sl@0	1068	{
sl@0	1069	typedef CBase ManagedType;
sl@0	1070	typedef CBase BaseManagedType;
sl@0	1071	typedef TPtrCleanupStrategy CleanupStrategy;
sl@0	1072	};
sl@0	1073
sl@0	1074
sl@0	1075	/**
sl@0	1076	Implementation base class - not designed for public inheritance or
sl@0	1077	direct use.
sl@0	1078	*/
sl@0	1079	template<typename T,
sl@0	1080	class CleanupStrategyType>
sl@0	1081	class LManagedPtrBase: protected LAutoPtrBase<typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType>
sl@0	1082	{
sl@0	1083	typedef LAutoPtrBase<typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType> LAutoPtrBase;
sl@0	1084
sl@0	1085	protected:
sl@0	1086	typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::ManagedType ManagedType;
sl@0	1087	typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType BaseManagedType;
sl@0	1088	typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::CleanupStrategy CleanupStrategy;
sl@0	1089
sl@0	1090	LManagedPtrBase()
sl@0	1091	{
sl@0	1092	}
sl@0	1093
sl@0	1094	template<typename U>
sl@0	1095	explicit LManagedPtrBase(U* aPtr)
sl@0	1096	: LAutoPtrBase(aPtr)
sl@0	1097	{
sl@0	1098	}
sl@0	1099
sl@0	1100	/**
sl@0	1101	Destructor. When automatic resource management is enabled, the
sl@0	1102	destructor invokes the specified cleanup strategy for the managed
sl@0	1103	pointer.
sl@0	1104	*/
sl@0	1105	~LManagedPtrBase()
sl@0	1106	{
sl@0	1107	if (IsEnabled())
sl@0	1108	{
sl@0	1109	CleanupStrategy::Cleanup(static_cast<ManagedType*>(iPtr));
sl@0	1110	}
sl@0	1111	}
sl@0	1112
sl@0	1113	template<typename U>
sl@0	1114	LManagedPtrBase& operator=(U* aPtr)
sl@0	1115	{
sl@0	1116	ReleaseResource();
sl@0	1117	LAutoPtrBase::operator=(aPtr);
sl@0	1118	return *this;
sl@0	1119	}
sl@0	1120
sl@0	1121	/**
sl@0	1122	If automatic resource management is enabled, the specified cleanup
sl@0	1123	strategy is invoked for the managed pointer and the automatic
sl@0	1124	resource management is then disabled. The underlying pointer is
sl@0	1125	reset to NULL.
sl@0	1126
sl@0	1127	@post Get() == NULL
sl@0	1128	*/
sl@0	1129	void ReleaseResource()
sl@0	1130	{
sl@0	1131	if (!IsEnabled())
sl@0	1132	return;
sl@0	1133
sl@0	1134	CleanupStrategy::Cleanup(static_cast<ManagedType*>(iPtr));
sl@0	1135	LAutoPtrBase::Disable();
sl@0	1136	}
sl@0	1137
sl@0	1138	using LAutoPtrBase::Unmanage;
sl@0	1139
sl@0	1140	using LAutoPtrBase::IsEnabled;
sl@0	1141
sl@0	1142	using LAutoPtrBase::Get;
sl@0	1143
sl@0	1144	using LAutoPtrBase::operator->;
sl@0	1145
sl@0	1146	using LAutoPtrBase::Disable;
sl@0	1147
sl@0	1148	using LAutoPtrBase::iPtr;
sl@0	1149
sl@0	1150	void Swap(LManagedPtrBase& aManagedPtr)
sl@0	1151	{
sl@0	1152	LAutoPtrBase::Swap(aManagedPtr);
sl@0	1153	}
sl@0	1154	};
sl@0	1155
sl@0	1156
sl@0	1157	/**
sl@0	1158	A class template that provides automatic management of pointers
sl@0	1159	held in the data members of objects.
sl@0	1160
sl@0	1161	@note This class should not used to define locals. See below for
sl@0	1162	an explanation and links to management classes suitable for use in
sl@0	1163	that context.
sl@0	1164
sl@0	1165	This class template can be used to protect a pointer to type T such
sl@0	1166	that the instance of T referred to is automatically cleaned up when
sl@0	1167	the management object is destroyed; typically when the object
sl@0	1168	containing it is deleted.
sl@0	1169
sl@0	1170	By default, the cleanup action is to delete the managed pointer
sl@0	1171	using a (non-array) delete operation. An alternative cleanup
sl@0	1172	strategy can be specified using the optional CleanupStrategy class
sl@0	1173	template parameter of the LManagedPtr class template. The most
sl@0	1174	common alternative cleanup strategies are predefined
sl@0	1175	(e.g. TPointerFree).
sl@0	1176
sl@0	1177	The constructors of this class never leave, so data members defined with
sl@0	1178	this type may be initialized safely during any phase of
sl@0	1179	construction of the owning class.
sl@0	1180
sl@0	1181	As a convenience, the methods of the managed pointer may be
sl@0	1182	accessed via "->" notation directly on the management object, while
sl@0	1183	"." notation is used to access the interface of the management
sl@0	1184	object itself. Using "*" to dereference the management object
sl@0	1185	yields a T&, and is often useful when passing the managed object as
sl@0	1186	an argument.
sl@0	1187
sl@0	1188	Automatic cleanup may be disabled at any time by calling
sl@0	1189	Unmanage(), while cleanup may be forced at any time by calling
sl@0	1190	ReleaseResource().
sl@0	1191
sl@0	1192	Example:
sl@0	1193	@code
sl@0	1194	class CComposite : public CBase
sl@0	1195	{
sl@0	1196	public:
sl@0	1197	CONSTRUCTORS_MAY_LEAVE
sl@0	1198
sl@0	1199	CComposite()
sl@0	1200	: iComponent(CComponent::NewL())
sl@0	1201	{
sl@0	1202	//...
sl@0	1203	}
sl@0	1204
sl@0	1205	~CComposite()
sl@0	1206	{
sl@0	1207	// the pointer to the CComponent object is automatically
sl@0	1208	// deleted
sl@0	1209	}
sl@0	1210
sl@0	1211	private:
sl@0	1212	LManagedPtr<CComponent> iComponent;
sl@0	1213	};
sl@0	1214	@endcode
sl@0	1215
sl@0	1216	Behind the scenes, this class template simply relies on reliable
sl@0	1217	execution of its destructor. If used for a local variable rather
sl@0	1218	than a data member, cleanup will occur but out-of-order compared to
sl@0	1219	objects protected using the LCleanupXxx variants or the
sl@0	1220	CleanupStack directly. Therefore it is not recommended for use in
sl@0	1221	that context.
sl@0	1222
sl@0	1223	These management classes may be used as the basis for implementing
sl@0	1224	leave-safe single-phase construction, since fully initialized
sl@0	1225	data members protected in this way will get destroyed (so reliably
sl@0	1226	triggering cleanup) if their containing classes leave during
sl@0	1227	execution of their constructors. Note, however, that single-phase
sl@0	1228	construction must be explicitly enabled in the containing class
sl@0	1229	using the CONSTRUCTORS_MAY_LEAVE macro.
sl@0	1230
sl@0	1231	This class template together with the cleanup strategy class
sl@0	1232	templates provide a template-based implementation of the Strategy
sl@0	1233	design pattern (See also: Policy-based design).
sl@0	1234
sl@0	1235	@see TPointerDelete which implements the default deleting cleanup strategy
sl@0	1236	@see TPointerFree which implements the alternative User::Free() cleanup strategy
sl@0	1237	@see LCleanedupPtr which has the same interface, but uses the cleanup
sl@0	1238	stack and is suitable for protecting locals
sl@0	1239	@see CONSTRUCTORS_MAY_LEAVE
sl@0	1240	*/
sl@0	1241	template<typename T,
sl@0	1242	class CleanupStrategyType = TPtrCleanupStrategy>
sl@0	1243	class LManagedPtr: protected LManagedPtrBase<T, CleanupStrategyType>
sl@0	1244	{
sl@0	1245	typedef LManagedPtrBase<T, CleanupStrategyType> LManagedPtrBase;
sl@0	1246
sl@0	1247	public:
sl@0	1248	typedef T ManagedType;
sl@0	1249	typedef CleanupStrategyType CleanupStrategy;
sl@0	1250
sl@0	1251
sl@0	1252	/**
sl@0	1253	Default constructor. Constructs an empty LManagedPtr object.
sl@0	1254
sl@0	1255	@post Get() == NULL
sl@0	1256	*/
sl@0	1257	LManagedPtr()
sl@0	1258	{
sl@0	1259	}
sl@0	1260
sl@0	1261	/**
sl@0	1262	Explicit constructor template. Constructs a LManagedPtr object
sl@0	1263	that manages the pointer aPtr of a type convertible to T* that can
sl@0	1264	be cleaned up using the cleanup strategy of the LManagedPtr class.
sl@0	1265	The default cleanup strategy is to delete the pointer to a
sl@0	1266	heap-allocated object by using non-array delete. Alternative
sl@0	1267	cleanup strategies can be specified by using the CleanupStrategy
sl@0	1268	template parameter of the LManagedPtr class template.
sl@0	1269
sl@0	1270	@param aPtr A pointer of a type that is convertible to T* that can
sl@0	1271	be cleaned up using the cleanup strategy.
sl@0	1272
sl@0	1273	@pre aPtr is of a type convertible to T* and can be cleaned up
sl@0	1274	using the cleanup strategy.
sl@0	1275
sl@0	1276	@post Get() == aPtr
sl@0	1277	*/
sl@0	1278	explicit LManagedPtr(T* aPtr)
sl@0	1279	: LManagedPtrBase(aPtr)
sl@0	1280	{
sl@0	1281	}
sl@0	1282
sl@0	1283	/**
sl@0	1284	Destructor. When automatic resource management is enabled, the
sl@0	1285	destructor invokes the specified cleanup strategy for the managed
sl@0	1286	pointer.
sl@0	1287	*/
sl@0	1288
sl@0	1289
sl@0	1290	/**
sl@0	1291	Assigns a new pointer to be managed. The new pointer must be of a
sl@0	1292	type convertible to T* and it must be possible to use the cleanup
sl@0	1293	strategy of the LManagedPtr object for the cleanup of the new
sl@0	1294	managed pointer. If the LManagedPtr object already contains a
sl@0	1295	managed pointer, then the cleanup strategy is invoked with the
sl@0	1296	managed pointer before assigning the new managed pointer.
sl@0	1297
sl@0	1298	@param aPtr A pointer of a type that is convertible to T* that can
sl@0	1299	be cleaned up using the cleanup strategy.
sl@0	1300
sl@0	1301	@pre aPtr is a pointer of a type that is convertible to T* and can
sl@0	1302	be cleaned up using the cleanup strategy.
sl@0	1303
sl@0	1304	@post Get() == aPtr
sl@0	1305	*/
sl@0	1306	LManagedPtr& operator=(T* aPtr)
sl@0	1307	{
sl@0	1308	LManagedPtrBase::operator=(aPtr);
sl@0	1309	return *this;
sl@0	1310	}
sl@0	1311
sl@0	1312	/**
sl@0	1313	Assigns a new pointer to be managed. The new pointer must be of a
sl@0	1314	type convertible to T* and it must be possible to use the cleanup
sl@0	1315	strategy of the LManagedPtr object for the cleanup of the new
sl@0	1316	managed pointer. If the LManagedPtr object already contains a
sl@0	1317	managed pointer, then the cleanup strategy is invoked with the
sl@0	1318	managed pointer before assigning the new managed pointer.
sl@0	1319
sl@0	1320	@param aPtr A pointer of a type that is convertible to T* that can
sl@0	1321	be cleaned up using the cleanup strategy.
sl@0	1322
sl@0	1323	@pre aPtr is a pointer of a type that is convertible to T* and can
sl@0	1324	be cleaned up using the cleanup strategy.
sl@0	1325
sl@0	1326	@post Get() == aPtr
sl@0	1327	*/
sl@0	1328	template<typename U>
sl@0	1329	LManagedPtr& operator=(U* aPtr)
sl@0	1330	{
sl@0	1331	LManagedPtrBase::operator=(aPtr);
sl@0	1332	return *this;
sl@0	1333	}
sl@0	1334
sl@0	1335	using LManagedPtrBase::ReleaseResource;
sl@0	1336
sl@0	1337	/**
sl@0	1338	Disables the automatic resource management for this object and
sl@0	1339	returns a pointer to the object of type T.
sl@0	1340
sl@0	1341	@return A pointer to the object of type T.
sl@0	1342	*/
sl@0	1343	T* Unmanage()
sl@0	1344	{
sl@0	1345	return static_cast<T*>(LManagedPtrBase::Unmanage());
sl@0	1346	}
sl@0	1347
sl@0	1348	/**
sl@0	1349	Returns ETrue if automatic resource management is enabled; EFalse
sl@0	1350	otherwise.
sl@0	1351
sl@0	1352	@return ETrue if automatic resource management is enabled; EFalse
sl@0	1353	otherwise.
sl@0	1354	*/
sl@0	1355	using LManagedPtrBase::IsEnabled;
sl@0	1356
sl@0	1357	/**
sl@0	1358	Returns a pointer to the managed object of type T.
sl@0	1359
sl@0	1360	@return A pointer to the managed object of type T.
sl@0	1361	*/
sl@0	1362	T* Get() const
sl@0	1363	{
sl@0	1364	return static_cast<T*>(iPtr);
sl@0	1365	}
sl@0	1366
sl@0	1367	/**
sl@0	1368	Overloaded indirection operator function.
sl@0	1369
sl@0	1370	@return A reference to the managed object of type T.
sl@0	1371	*/
sl@0	1372	T& operator*() const
sl@0	1373	{
sl@0	1374	return (static_cast<T>(iPtr));
sl@0	1375	}
sl@0	1376
sl@0	1377	/**
sl@0	1378	Overloaded class member access operator function.
sl@0	1379
sl@0	1380	@return A pointer to the managed object of type T.
sl@0	1381	*/
sl@0	1382	T* operator->() const
sl@0	1383	{
sl@0	1384	return static_cast<T*>(iPtr);
sl@0	1385	}
sl@0	1386
sl@0	1387
sl@0	1388	// Implementation type - do not use
sl@0	1389	typedef typename LManagedPtrBase::BaseManagedType* LManagedPtr<T, CleanupStrategy>::*TUnspecifiedBoolType;
sl@0	1390
sl@0	1391	/**
sl@0	1392	Conversion operator that enables LCleanedupPtr objects to be used
sl@0	1393	in boolean contexts.
sl@0	1394
sl@0	1395	@return An unspecified value of an unspecified type convertible to
sl@0	1396	boolean, which has a boolean value equal to Get() != NULL
sl@0	1397	*/
sl@0	1398	operator TUnspecifiedBoolType()
sl@0	1399	{
sl@0	1400	return iPtr ? &LManagedPtr::iPtr : NULL;
sl@0	1401	}
sl@0	1402
sl@0	1403
sl@0	1404	using LManagedPtrBase::Disable;
sl@0	1405
sl@0	1406	void Swap(LManagedPtr& aManagedPtr)
sl@0	1407	{
sl@0	1408	LManagedPtrBase::Swap(aManagedPtr);
sl@0	1409	}
sl@0	1410
sl@0	1411	private:
sl@0	1412	using LManagedPtrBase::iPtr;
sl@0	1413	};
sl@0	1414
sl@0	1415
sl@0	1416	// function template used for comparing two LManagedPtr-managed
sl@0	1417	// pointers for equality
sl@0	1418	template<typename T, typename U>
sl@0	1419	TBool operator==(const LManagedPtr<T>& aPtr1, const LManagedPtr<U>& aPtr2)
sl@0	1420	{
sl@0	1421	return aPtr1.Get() == aPtr2.Get();
sl@0	1422	}
sl@0	1423
sl@0	1424	// function template used for comparing two LManagedPtr-managed
sl@0	1425	// pointers for inequality
sl@0	1426	template<typename T, typename U>
sl@0	1427	TBool operator!=(const LManagedPtr<T>& aPtr1, const LManagedPtr<U>& aPtr2)
sl@0	1428	{
sl@0	1429	return aPtr1.Get() != aPtr2.Get();
sl@0	1430	}
sl@0	1431
sl@0	1432	// function template used for testing the ordering of two
sl@0	1433	// LManagedPtr-managed pointers
sl@0	1434	template<typename T, typename U>
sl@0	1435	TBool operator<(const LManagedPtr<T>& aPtr1, const LManagedPtr<U>& aPtr2)
sl@0	1436	{
sl@0	1437	return aPtr1.Get() < aPtr2.Get();
sl@0	1438	}
sl@0	1439
sl@0	1440
sl@0	1441	/**
sl@0	1442	A class template that provides automatic management of arrays. Such
sl@0	1443	managed arrays can be data members of composite classes.
sl@0	1444
sl@0	1445	@note This class should not used to define locals. See below for
sl@0	1446	an explanation and links to management classes suitable for use in
sl@0	1447	that context.
sl@0	1448
sl@0	1449	@par
sl@0	1450
sl@0	1451	@note This class can only be used with raw arrays, which are used
sl@0	1452	only rarely on Symbian OS. Instances of Symbian array container
sl@0	1453	classes (e.g. RArray, RPointerArray) should be managed using the
sl@0	1454	automatic management template classes appropriate for the array's
sl@0	1455	type (LManagedHandle template classes for Symbian R arrays or
sl@0	1456	LManagedPtr template classes for Symbian C arrays).
sl@0	1457
sl@0	1458	This class template can be used to protect a heap-allocated array
sl@0	1459	of objects of type T such that the managed array is automatically
sl@0	1460	deallocated when the management object is destroyed.
sl@0	1461
sl@0	1462	The default cleanup strategy is to deallocate the managed array
sl@0	1463	using arrray delete (delete[]), assuming that the array is
sl@0	1464	heap-allocated. An alternative cleanup strategy can be selected by
sl@0	1465	specifying a cleanup strategy template class as the optional second
sl@0	1466	template argument (corresponding to the CleanupStrategy template
sl@0	1467	parameter).
sl@0	1468
sl@0	1469	The constructors of this class never leave, so data members defined with
sl@0	1470	this type may be initialized safely during any phase of
sl@0	1471	construction of the owning class.
sl@0	1472
sl@0	1473	As a convenience, the elements of the managed array may be accessed
sl@0	1474	via "[]" notation directly on the management object.
sl@0	1475
sl@0	1476	Automatic cleanup may be disabled at any time by calling
sl@0	1477	Unmanage(), while cleanup may be forced at any time by calling
sl@0	1478	ReleaseResource().
sl@0	1479
sl@0	1480
sl@0	1481	Example:
sl@0	1482	@code
sl@0	1483	class CComposite : public CBase
sl@0	1484	{
sl@0	1485	public:
sl@0	1486	CONSTRUCTORS_MAY_LEAVE
sl@0	1487
sl@0	1488	CComposite()
sl@0	1489	: iComponents(new(ELeave) CComponent[KNumComponents])
sl@0	1490	{
sl@0	1491	//...
sl@0	1492	}
sl@0	1493
sl@0	1494	~CComposite()
sl@0	1495	{
sl@0	1496	// the array is automatically deleted
sl@0	1497	}
sl@0	1498
sl@0	1499	private:
sl@0	1500	LManagedArray<CComponent> iComponents;
sl@0	1501	};
sl@0	1502	@endcode
sl@0	1503
sl@0	1504
sl@0	1505	Behind the scenes, this class template simply relies on reliable
sl@0	1506	execution of its destructor. If used for a local variable rather
sl@0	1507	than a data member, cleanup will occur but out-of-order compared to
sl@0	1508	objects protected using the LCleanupXxx variants or the
sl@0	1509	CleanupStack directly. Therefore it is not recommended for use in
sl@0	1510	that context.
sl@0	1511
sl@0	1512	These management classes may be used as the basis for implementing
sl@0	1513	leave-safe single-phase construction, since fully initialized
sl@0	1514	data members protected in this way will get destroyed (so reliably
sl@0	1515	triggering cleanup) if their containing classes leave during
sl@0	1516	execution of their constructors. Note, however, that single-phase
sl@0	1517	construction must be explicitly enabled in the containing class
sl@0	1518	using the CONSTRUCTORS_MAY_LEAVE macro.
sl@0	1519
sl@0	1520	This class template together with the cleanup strategy class
sl@0	1521	templates provide a template-based implementation of the Strategy
sl@0	1522	design pattern (See also: Policy-based design).
sl@0	1523
sl@0	1524	@see LCleanedupArray which has the same interface, but uses the cleanup
sl@0	1525	stack and is suitable for protecting locals
sl@0	1526	@see CONSTRUCTORS_MAY_LEAVE
sl@0	1527	*/
sl@0	1528	template<typename T,
sl@0	1529	class CleanupStrategyType = TArrayDelete>
sl@0	1530	class LManagedArray: protected LAutoPtrBase<T>
sl@0	1531	{
sl@0	1532	typedef LAutoPtrBase<T> LAutoPtrBase;
sl@0	1533
sl@0	1534	public:
sl@0	1535	typedef T ManagedType;
sl@0	1536	typedef CleanupStrategyType CleanupStrategy;
sl@0	1537
sl@0	1538	/**
sl@0	1539	Default constructor. Constructs an empty LManagedArray object.
sl@0	1540
sl@0	1541	@post Get() == NULL
sl@0	1542	*/
sl@0	1543	LManagedArray()
sl@0	1544	{
sl@0	1545	}
sl@0	1546
sl@0	1547	/**
sl@0	1548	Explicit constructor. Constructs a LManagedArray object that
sl@0	1549	manages an array of objects of type T that can be cleaned up using
sl@0	1550	the cleanup strategy of the LManagedArray class. The default
sl@0	1551	cleanup strategy is to deallocate the managed array by using array
sl@0	1552	delete (delete[]), assuming that the array is heap-allocated.
sl@0	1553	Alternative cleanup strategies can be specified by using the
sl@0	1554	CleanupStrategy template parameter of the LManagedArray class
sl@0	1555	template.
sl@0	1556
sl@0	1557	@param aPtr A pointer to the first element of an array of objects
sl@0	1558	of type T - array that can be cleaned up using the cleanup strategy
sl@0	1559	of the the LManagedArray class.
sl@0	1560
sl@0	1561	@pre The array can be cleaned up using the cleanup strategy.
sl@0	1562
sl@0	1563	@post Get() == aPtr
sl@0	1564	*/
sl@0	1565	explicit LManagedArray(T* aPtr)
sl@0	1566	: LAutoPtrBase(aPtr)
sl@0	1567	{
sl@0	1568	}
sl@0	1569
sl@0	1570	/**
sl@0	1571	Destructor. When automatic resource management is enabled, the
sl@0	1572	destructor invokes the specified cleanup strategy for the managed
sl@0	1573	pointer.
sl@0	1574	*/
sl@0	1575	~LManagedArray()
sl@0	1576	{
sl@0	1577	if (LAutoPtrBase::IsEnabled())
sl@0	1578	{
sl@0	1579	CleanupStrategy::Cleanup(iPtr);
sl@0	1580	}
sl@0	1581	}
sl@0	1582
sl@0	1583	/**
sl@0	1584	Assigns a new array of objects of type T to be managed. It needs
sl@0	1585	to be possible use the cleanup strategy of the LManagedArray object
sl@0	1586	for the cleanup of the new managed array. The default cleanup
sl@0	1587	strategy is to delete the heap-allocated array by using array
sl@0	1588	delete (delete[]). If the LManagedArray object already manages an
sl@0	1589	array, then the cleanup strategy is invoked with the managed array
sl@0	1590	before assigning the new managed array.
sl@0	1591
sl@0	1592	@param aPtr A pointer to the first element of the array of objects
sl@0	1593	of type T - array that can be cleaned up using the cleanup
sl@0	1594	strategy.
sl@0	1595
sl@0	1596	@pre The new array to be managed can be cleaned up using the
sl@0	1597	cleanup strategy.
sl@0	1598
sl@0	1599	@post Get() == aPtr
sl@0	1600	*/
sl@0	1601	LManagedArray& operator=(T* aPtr)
sl@0	1602	{
sl@0	1603	ReleaseResource();
sl@0	1604	LAutoPtrBase::operator=(aPtr);
sl@0	1605	return *this;
sl@0	1606	}
sl@0	1607
sl@0	1608	/**
sl@0	1609	If automatic resource management is enabled, the specified cleanup
sl@0	1610	strategy is invoked for the managed pointer and the automatic
sl@0	1611	resource management is then disabled. The underlying pointer is
sl@0	1612	reset to NULL.
sl@0	1613
sl@0	1614	@post Get() == NULL
sl@0	1615	*/
sl@0	1616	void ReleaseResource()
sl@0	1617	{
sl@0	1618	if (!LAutoPtrBase::IsEnabled())
sl@0	1619	return;
sl@0	1620
sl@0	1621	CleanupStrategy::Cleanup(iPtr);
sl@0	1622	LAutoPtrBase::Disable();
sl@0	1623	}
sl@0	1624
sl@0	1625	/**
sl@0	1626	Disables the automatic resource management for this object and
sl@0	1627	returns a pointer to the first element of the array of objects of
sl@0	1628	type T.
sl@0	1629
sl@0	1630	@return A pointer to the first element of the array of objects of
sl@0	1631	type T.
sl@0	1632	*/
sl@0	1633	T* Unmanage()
sl@0	1634	{
sl@0	1635	return static_cast<T*>(LAutoPtrBase::Unmanage());
sl@0	1636	}
sl@0	1637
sl@0	1638	/**
sl@0	1639	Returns ETrue if automatic resource management is enabled; EFalse
sl@0	1640	otherwise.
sl@0	1641
sl@0	1642	@return ETrue if automatic resource management is enabled; EFalse
sl@0	1643	otherwise.
sl@0	1644	*/
sl@0	1645	using LAutoPtrBase::IsEnabled;
sl@0	1646
sl@0	1647	/**
sl@0	1648	Returns a pointer to the first element of the managed array of
sl@0	1649	objects of type T.
sl@0	1650
sl@0	1651	@return A pointer to the first element of the managed array of
sl@0	1652	objects of type T.
sl@0	1653	*/
sl@0	1654	using LAutoPtrBase::Get;
sl@0	1655
sl@0	1656	/**
sl@0	1657	Overloaded subscript operator.
sl@0	1658
sl@0	1659	@return A reference to the object of type T at the position aIndex.
sl@0	1660	*/
sl@0	1661	T& operator[](TInt aIndex) const
sl@0	1662	{
sl@0	1663	return iPtr[aIndex];
sl@0	1664	}
sl@0	1665
sl@0	1666	using LAutoPtrBase::Disable;
sl@0	1667
sl@0	1668	void Swap(LManagedArray& aArray)
sl@0	1669	{
sl@0	1670	LAutoPtrBase::Swap(aArray);
sl@0	1671	}
sl@0	1672
sl@0	1673	private:
sl@0	1674	using LAutoPtrBase::iPtr;
sl@0	1675	};
sl@0	1676
sl@0	1677
sl@0	1678	/**
sl@0	1679	Implementation base class - not designed for public inheritance or
sl@0	1680	direct use.
sl@0	1681
sl@0	1682	@internalComponent
sl@0	1683	*/
sl@0	1684	// Not for Client Use , Only to be used Internally.
sl@0	1685	template<typename T>
sl@0	1686	class LAutoRefBase
sl@0	1687	{
sl@0	1688	protected:
sl@0	1689	template<typename U>
sl@0	1690	explicit LAutoRefBase(U& aRef)
sl@0	1691	: iPtr(&aRef)
sl@0	1692	{
sl@0	1693	}
sl@0	1694
sl@0	1695	template<typename U>
sl@0	1696	LAutoRefBase& operator=(U& aRef)
sl@0	1697	{
sl@0	1698	iPtr = &aRef;
sl@0	1699	return *this;
sl@0	1700	}
sl@0	1701
sl@0	1702	T& Unmanage()
sl@0	1703	{
sl@0	1704	T* ptr = iPtr;
sl@0	1705	iPtr = NULL;
sl@0	1706	return *ptr;
sl@0	1707	}
sl@0	1708
sl@0	1709	TBool IsEnabled() const
sl@0	1710	{
sl@0	1711	return iPtr != NULL;
sl@0	1712	}
sl@0	1713
sl@0	1714	T& Get() const
sl@0	1715	{
sl@0	1716	return *iPtr;
sl@0	1717	}
sl@0	1718
sl@0	1719	T& operator*() const
sl@0	1720	{
sl@0	1721	return *iPtr;
sl@0	1722	}
sl@0	1723
sl@0	1724	T* operator->() const
sl@0	1725	{
sl@0	1726	return iPtr;
sl@0	1727	}
sl@0	1728
sl@0	1729	void Disable()
sl@0	1730	{
sl@0	1731	iPtr = NULL;
sl@0	1732	}
sl@0	1733
sl@0	1734	void Swap(LAutoRefBase& aAutoRef)
sl@0	1735	{
sl@0	1736	::Swap(iPtr, aAutoRef.iPtr);
sl@0	1737	}
sl@0	1738
sl@0	1739	protected:
sl@0	1740	T* iPtr;
sl@0	1741
sl@0	1742	private:
sl@0	1743	LAutoRefBase(const LAutoRefBase&);
sl@0	1744	LAutoRefBase& operator=(const LAutoRefBase&);
sl@0	1745	};
sl@0	1746
sl@0	1747
sl@0	1748	/**
sl@0	1749	A class template that provides automatic management of references
sl@0	1750	to resource handles (often R-class instances) held in the data
sl@0	1751	members of objects.
sl@0	1752
sl@0	1753	@note This class should not used to define locals. See below for
sl@0	1754	an explanation and links to management classes suitable for use in
sl@0	1755	that context.
sl@0	1756
sl@0	1757	Unlike LManagedHandle which creates a fresh instance of its managed
sl@0	1758	type, this class template can be used to protect an existing
sl@0	1759	resource handle of type T (typically an R-class instance). The
sl@0	1760	instance of T referred to has a cleanup operation run on it
sl@0	1761	automatically when the management object is destroyed; typically
sl@0	1762	when the object containing it is deleted.
sl@0	1763
sl@0	1764	By default, the cleanup action is to call the Close() member
sl@0	1765	function of the referenced handle. An alternative cleanup strategy may
sl@0	1766	be selected by specifying a cleanup strategy template class in the
sl@0	1767	optional second template parameter position. The most common
sl@0	1768	alternative cleanup strategies are predefined. It is also possible
sl@0	1769	to specialize the default cleanup action for a given class using
sl@0	1770	the DEFINE_CLEANUP_FUNCTION macro.
sl@0	1771
sl@0	1772	The constructors of this class never leave, so data members defined with
sl@0	1773	this type may be initialized safely during any phase of
sl@0	1774	construction of the owning class.
sl@0	1775
sl@0	1776	As a convenience, the methods of the managed pointer may be
sl@0	1777	accessed via "->" notation directly on the management object, while
sl@0	1778	"." notation is used to access the interface of the management
sl@0	1779	object itself. Using "*" to dereference the management object
sl@0	1780	yields a T&, and is often useful when passing the managed object as
sl@0	1781	an argument.
sl@0	1782
sl@0	1783	Automatic cleanup may be disabled at any time by calling
sl@0	1784	Unmanage(), while cleanup may be forced at any time by calling
sl@0	1785	ReleaseResource().
sl@0	1786
sl@0	1787	Example:
sl@0	1788	@code
sl@0	1789	class CComposite : public CBase
sl@0	1790	{
sl@0	1791	public:
sl@0	1792	CONSTRUCTORS_MAY_LEAVE
sl@0	1793
sl@0	1794	// An existing RFs instance is given to us to reuse, but
sl@0	1795	// we are responsible for calling Close() when we're done
sl@0	1796	CComposite(RFs& aFs)
sl@0	1797	: iFileServ(aFs)
sl@0	1798	{
sl@0	1799	iFileServ->Connect() OR_LEAVE;
sl@0	1800	iFile->Open(*iFileServ, ...);
sl@0	1801	}
sl@0	1802
sl@0	1803	~CComposite()
sl@0	1804	{
sl@0	1805	// the handles are automatically closed
sl@0	1806	}
sl@0	1807
sl@0	1808	private:
sl@0	1809
sl@0	1810	LManagedRef<RFs> iFileServ;
sl@0	1811	LManagedHandle<RFile> iFile;
sl@0	1812	};
sl@0	1813	@endcode
sl@0	1814
sl@0	1815	Behind the scenes, this class template simply relies on reliable
sl@0	1816	execution of its destructor. If used for a local variable rather
sl@0	1817	than a data member, cleanup will occur but out-of-order compared to
sl@0	1818	objects protected using the LCleanupXxx variants or the
sl@0	1819	CleanupStack directly. Therefore it is not recommended for use in
sl@0	1820	that context.
sl@0	1821
sl@0	1822	These management classes may be used as the basis for implementing
sl@0	1823	leave-safe single-phase construction, since fully initialized
sl@0	1824	data members protected in this way will get destroyed (so reliably
sl@0	1825	triggering cleanup) if their containing classes leave during
sl@0	1826	execution of their constructors. Note, however, that single-phase
sl@0	1827	construction must be explicitly enabled in the containing class
sl@0	1828	using the CONSTRUCTORS_MAY_LEAVE macro.
sl@0	1829
sl@0	1830	This class template together with the cleanup strategy class
sl@0	1831	templates provide a template-based implementation of the Strategy
sl@0	1832	design pattern (See also: Policy-based design).
sl@0	1833
sl@0	1834	@see TClose which implements the default Close() calling cleanup strategy
sl@0	1835	@see TResetAndDestroy which implements an alternative
sl@0	1836	ResetAndDestroy() calling cleanup strategy
sl@0	1837	@see TFree which implements an alternative Free() calling cleanup
sl@0	1838	strategy
sl@0	1839	@see TDestroy which implements an alternative Destroy() calling
sl@0	1840	cleanup strategy
sl@0	1841	@see TRelease which implements an alternative Release() calling
sl@0	1842	cleanup strategy
sl@0	1843	@see LCleanedupRef which has the same interface, but uses the cleanup
sl@0	1844	stack and is suitable for protecting locals
sl@0	1845	@see LManagedHandle which has a similar interface but creates a fresh
sl@0	1846	local instance of T
sl@0	1847	@see CONSTRUCTORS_MAY_LEAVE
sl@0	1848	*/
sl@0	1849	template<typename T,
sl@0	1850	class CleanupStrategyType = TResourceCleanupStrategy>
sl@0	1851	class LManagedRef: protected LAutoRefBase<T>
sl@0	1852	{
sl@0	1853	typedef LAutoRefBase<T> LAutoRefBase;
sl@0	1854
sl@0	1855	public:
sl@0	1856	typedef T ManagedType;
sl@0	1857	typedef CleanupStrategyType CleanupStrategy;
sl@0	1858
sl@0	1859	/**
sl@0	1860	Explicit constructor.
sl@0	1861	*/
sl@0	1862	template<typename U>
sl@0	1863	explicit LManagedRef(U& aRef)
sl@0	1864	: LAutoRefBase(aRef)
sl@0	1865	{
sl@0	1866	}
sl@0	1867
sl@0	1868	/**
sl@0	1869	Destructor. When automatic resource management is enabled, the
sl@0	1870	destructor invokes the specified cleanup strategy for the managed
sl@0	1871	reference.
sl@0	1872	*/
sl@0	1873	~LManagedRef()
sl@0	1874	{
sl@0	1875	if (LAutoRefBase::IsEnabled())
sl@0	1876	{
sl@0	1877	CleanupStrategy::Cleanup(iPtr);
sl@0	1878	}
sl@0	1879	}
sl@0	1880
sl@0	1881	/**
sl@0	1882	Assigns a new reference to be managed. If the LManagedRef
sl@0	1883	object already contains a managed reference, then the specified
sl@0	1884	cleanup strategy is invoked for the managed reference before
sl@0	1885	assigning the new managed reference.
sl@0	1886	*/
sl@0	1887	template<typename U>
sl@0	1888	LManagedRef& operator=(U& aRef)
sl@0	1889	{
sl@0	1890	ReleaseResource();
sl@0	1891	LAutoRefBase::operator=(aRef);
sl@0	1892	return *this;
sl@0	1893	}
sl@0	1894
sl@0	1895	/**
sl@0	1896	If automatic resource management is enabled, the specified cleanup
sl@0	1897	strategy is invoked for the managed reference and the automatic
sl@0	1898	resource management is then disabled for this object.
sl@0	1899	*/
sl@0	1900	void ReleaseResource()
sl@0	1901	{
sl@0	1902	if (!LAutoRefBase::IsEnabled())
sl@0	1903	return;
sl@0	1904
sl@0	1905	CleanupStrategy::Cleanup(iPtr);
sl@0	1906	LAutoRefBase::Disable();
sl@0	1907	}
sl@0	1908
sl@0	1909	/**
sl@0	1910	Disables the automatic resource management for this object and
sl@0	1911	returns a reference to the object of type T.
sl@0	1912
sl@0	1913	@return A reference to the object of type T.
sl@0	1914	*/
sl@0	1915	using LAutoRefBase::Unmanage;
sl@0	1916
sl@0	1917	/**
sl@0	1918	Returns ETrue if automatic resource management is enabled; EFalse
sl@0	1919	otherwise.
sl@0	1920
sl@0	1921	@return ETrue if automatic resource management is enabled; EFalse
sl@0	1922	otherwise.
sl@0	1923	*/
sl@0	1924	using LAutoRefBase::IsEnabled;
sl@0	1925
sl@0	1926	/**
sl@0	1927	Returns a reference to the managed object of type T.
sl@0	1928
sl@0	1929	@return A reference to the managed object of type T.
sl@0	1930	*/
sl@0	1931	using LAutoRefBase::Get;
sl@0	1932
sl@0	1933	/**
sl@0	1934	Overloaded indirection operator function.
sl@0	1935
sl@0	1936	@return A reference to the managed object of type T.
sl@0	1937	*/
sl@0	1938	using LAutoRefBase::operator*;
sl@0	1939
sl@0	1940	/**
sl@0	1941	Overloaded class member access operator function.
sl@0	1942
sl@0	1943	@return A pointer to the managed object of type T.
sl@0	1944	*/
sl@0	1945	using LAutoRefBase::operator->;
sl@0	1946
sl@0	1947	using LAutoRefBase::Disable;
sl@0	1948
sl@0	1949	void Swap(LManagedRef& aRef)
sl@0	1950	{
sl@0	1951	LAutoRefBase::Swap(aRef);
sl@0	1952	}
sl@0	1953
sl@0	1954	private:
sl@0	1955	using LAutoRefBase::iPtr;
sl@0	1956	};
sl@0	1957
sl@0	1958
sl@0	1959	/**
sl@0	1960	A class template for the creation and CleanupStack-based
sl@0	1961	local-scope automatic management of resource handles (typically
sl@0	1962	instances of R-classes).
sl@0	1963
sl@0	1964	@note This class can only be used to define locals, never
sl@0	1965	data members. See below for an explanation and links to management
sl@0	1966	classes suitable for use in different contexts. It should never be
sl@0	1967	used in the same function as code that uses the CleanupStack API
sl@0	1968	directly.
sl@0	1969
sl@0	1970	This class template can be used to create and protect a resource
sl@0	1971	handle of type T (typically a R-class) such that the instance of T
sl@0	1972	referred to is automatically cleaned up when either of the
sl@0	1973	following occur:
sl@0	1974
sl@0	1975	- The referring local variable goes out of scope normally
sl@0	1976	- The referring local variable goes out of scope due to an
sl@0	1977	untrapped leave causing the scope to be exited non-locally
sl@0	1978
sl@0	1979	By default, the cleanup action is to call the Close() member
sl@0	1980	function of the managed handle. An alternative cleanup strategy may
sl@0	1981	be selected by specifying a cleanup strategy template class in the
sl@0	1982	optional second template parameter position. The most common
sl@0	1983	alternative cleanup strategies are predefined. It is also possible
sl@0	1984	to specialize the default cleanup action for a given class using
sl@0	1985	the DEFINE_CLEANUP_FUNCTION macro.
sl@0	1986
sl@0	1987	The constructors of this class may leave.
sl@0	1988
sl@0	1989	Any arguments supplied when initializing an instance of this class
sl@0	1990	are automatically passed through to T's constructors.
sl@0	1991
sl@0	1992	As a convenience, the methods of the managed handle may be
sl@0	1993	accessed via "->" notation directly on the management object, while
sl@0	1994	"." notation is used to access the interface of the management
sl@0	1995	object itself. Using "*" to dereference the management object
sl@0	1996	yields a T&, and is often useful when passing the managed object as
sl@0	1997	an argument.
sl@0	1998
sl@0	1999	Automatic cleanup may be disabled at any time by calling
sl@0	2000	Unmanage(), while cleanup may be forced at any time by calling
sl@0	2001	ReleaseResource().
sl@0	2002
sl@0	2003	Example:
sl@0	2004	@code
sl@0	2005	// block scope example
sl@0	2006	{
sl@0	2007	LCleanedupHandle<RClosable> obj;
sl@0	2008	obj->DoSomethingL(); // leave-safe
sl@0	2009	if (obj->Finished())
sl@0	2010	return; // RClosable::Close is invoked automatically
sl@0	2011	obj->DoSomethingElseL(); // leave-safe
sl@0	2012	// RClosable::Close is invoked automatically
sl@0	2013	}
sl@0	2014	@endcode
sl@0	2015
sl@0	2016	Behind the scenes, this class template is implemented in terms of
sl@0	2017	the thread-local CleanupStack, restricting its use to locals on the
sl@0	2018	stack. This use of the CleanupStack ensures a consistent cleanup
sl@0	2019	order between functions that call one another, even if they use
sl@0	2020	different cleanup idioms.
sl@0	2021
sl@0	2022	This class template together with the cleanup strategy class
sl@0	2023	templates provide a template-based implementation of the Strategy
sl@0	2024	design pattern (See also: Policy-based design).
sl@0	2025
sl@0	2026	@see TClose which implements the default Close() calling cleanup strategy
sl@0	2027	@see TResetAndDestroy which implements an alternative
sl@0	2028	ResetAndDestroy() calling cleanup strategy
sl@0	2029	@see TFree which implements an alternative Free() calling cleanup
sl@0	2030	strategy
sl@0	2031	@see TDestroy which implements an alternative Destroy() calling
sl@0	2032	cleanup strategy
sl@0	2033	@see TRelease which implements an alternative Release() calling cleanup strategy
sl@0	2034	@see LManagedHandle which has the same interface, but does not use the cleanup
sl@0	2035	stack and is suitable for protecting the data members of classes
sl@0	2036	*/
sl@0	2037	template<typename T,
sl@0	2038	class CleanupStrategyType = TResourceCleanupStrategy>
sl@0	2039	class LCleanedupHandle: protected LAutoHandleBase<T, IS_HANDLE_SPECIAL(T)>
sl@0	2040	{
sl@0	2041	typedef LAutoHandleBase<T, IS_HANDLE_SPECIAL(T)> LAutoHandleBase;
sl@0	2042
sl@0	2043	public:
sl@0	2044	typedef T ManagedType;
sl@0	2045	typedef CleanupStrategyType CleanupStrategy;
sl@0	2046
sl@0	2047
sl@0	2048	/**
sl@0	2049	Default constructor.
sl@0	2050	*/
sl@0	2051	LCleanedupHandle()
sl@0	2052	{
sl@0	2053	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2054	}
sl@0	2055
sl@0	2056	template<typename Param1>
sl@0	2057	explicit LCleanedupHandle(const Param1& aParam1)
sl@0	2058	: LAutoHandleBase(aParam1)
sl@0	2059	{
sl@0	2060	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2061	}
sl@0	2062
sl@0	2063	template<typename Param1>
sl@0	2064	explicit LCleanedupHandle(Param1& aParam1)
sl@0	2065	: LAutoHandleBase(aParam1)
sl@0	2066	{
sl@0	2067	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2068	}
sl@0	2069
sl@0	2070	template<typename Param1,
sl@0	2071	typename Param2>
sl@0	2072	LCleanedupHandle(const Param1& aParam1,
sl@0	2073	const Param2& aParam2)
sl@0	2074	: LAutoHandleBase(aParam1,
sl@0	2075	aParam2)
sl@0	2076	{
sl@0	2077	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2078	}
sl@0	2079
sl@0	2080	template<typename Param1,
sl@0	2081	typename Param2>
sl@0	2082	LCleanedupHandle(const Param1& aParam1,
sl@0	2083	Param2& aParam2)
sl@0	2084	: LAutoHandleBase(aParam1,
sl@0	2085	aParam2)
sl@0	2086	{
sl@0	2087	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2088	}
sl@0	2089
sl@0	2090	template<typename Param1,
sl@0	2091	typename Param2>
sl@0	2092	LCleanedupHandle(Param1& aParam1,
sl@0	2093	const Param2& aParam2)
sl@0	2094	: LAutoHandleBase(aParam1,
sl@0	2095	aParam2)
sl@0	2096	{
sl@0	2097	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2098	}
sl@0	2099
sl@0	2100	template<typename Param1,
sl@0	2101	typename Param2>
sl@0	2102	LCleanedupHandle(Param1& aParam1,
sl@0	2103	Param2& aParam2)
sl@0	2104	: LAutoHandleBase(aParam1,
sl@0	2105	aParam2)
sl@0	2106	{
sl@0	2107	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2108	}
sl@0	2109
sl@0	2110
sl@0	2111	~LCleanedupHandle()
sl@0	2112	{
sl@0	2113	ManagedPopCleanupStackItem(IsEnabled());
sl@0	2114	}
sl@0	2115
sl@0	2116	/**
sl@0	2117	Assigns a new resource to be managed. If the LCleanedupHandle
sl@0	2118	object already contains a managed resource handle, then the managed
sl@0	2119	resource is released using the specified cleanup strategy before
sl@0	2120	assigning the new managed resource.
sl@0	2121	*/
sl@0	2122	template<typename U>
sl@0	2123	LCleanedupHandle& operator=(const U& aHandle)
sl@0	2124	{
sl@0	2125	ReleaseResource();
sl@0	2126	LAutoHandleBase::operator=(aHandle);
sl@0	2127	return *this;
sl@0	2128	}
sl@0	2129
sl@0	2130
sl@0	2131	/**
sl@0	2132	If automatic resource management is enabled, calls the cleanup
sl@0	2133	function defined by the cleanup strategy with the managed resource
sl@0	2134	handle object and then disables the automatic resource management
sl@0	2135	for this object. The cleanup strategy is specified by the
sl@0	2136	CleanupStrategy template template parameter. The default cleanup
sl@0	2137	strategy is to call the cleanup member function on the contained
sl@0	2138	resource handle object. which is a member function named Close(),
sl@0	2139	unless explicitly defined otherwise for the class of the object,
sl@0	2140	for example by using the provided DEFINE_CLEANUP_FUNCTION macro.
sl@0	2141	*/
sl@0	2142	void ReleaseResource()
sl@0	2143	{
sl@0	2144	if (!IsEnabled())
sl@0	2145	return;
sl@0	2146
sl@0	2147	CleanupStrategy::Cleanup(&Get());
sl@0	2148	LAutoHandleBase::Disable();
sl@0	2149	}
sl@0	2150
sl@0	2151	/**
sl@0	2152	Disables the automatic resource management for this obkect and
sl@0	2153	returns a copy of the resource handle.
sl@0	2154
sl@0	2155	@return A copy of the resource handle.
sl@0	2156	*/
sl@0	2157	using LAutoHandleBase::Unmanage;
sl@0	2158
sl@0	2159	/**
sl@0	2160	Returns ETrue if automatic resource management is enabled; EFalse
sl@0	2161	otherwise.
sl@0	2162
sl@0	2163	@return ETrue if automatic resource management is enabled; EFalse
sl@0	2164	otherwise.
sl@0	2165	*/
sl@0	2166	using LAutoHandleBase::IsEnabled;
sl@0	2167
sl@0	2168
sl@0	2169	/**
sl@0	2170	Returns a reference to the resource handle.
sl@0	2171
sl@0	2172	@return A reference to the resource handle.
sl@0	2173	*/
sl@0	2174	using LAutoHandleBase::Get;
sl@0	2175
sl@0	2176
sl@0	2177	/**
sl@0	2178	Overloaded indirection operator function.
sl@0	2179
sl@0	2180	@return A reference to the resource handle.
sl@0	2181	*/
sl@0	2182	using LAutoHandleBase::operator*;
sl@0	2183
sl@0	2184	/**
sl@0	2185	Overloaded class member access operator function.
sl@0	2186
sl@0	2187	@return A pointer to the resource handle.
sl@0	2188	*/
sl@0	2189	using LAutoHandleBase::operator->;
sl@0	2190
sl@0	2191	static void Cleanup(TAny* aPtr)
sl@0	2192	{
sl@0	2193	LCleanedupHandle* autoh = static_cast<LCleanedupHandle*>(aPtr);
sl@0	2194
sl@0	2195	if (autoh->IsEnabled())
sl@0	2196	{
sl@0	2197	CleanupStrategy::Cleanup(&autoh->Get());
sl@0	2198	}
sl@0	2199	}
sl@0	2200
sl@0	2201	using LAutoHandleBase::Disable;
sl@0	2202
sl@0	2203	void Swap(LCleanedupHandle& aCleanedupHandle)
sl@0	2204	{
sl@0	2205	LAutoHandleBase::Swap(aCleanedupHandle);
sl@0	2206	}
sl@0	2207	};
sl@0	2208
sl@0	2209
sl@0	2210	/**
sl@0	2211	Implementation base class - not designed for public inheritance or
sl@0	2212	direct use.
sl@0	2213
sl@0	2214	@internalComponent
sl@0	2215	*/
sl@0	2216	// Not for Client Use , Only to be used Internally.
sl@0	2217	template<typename T,
sl@0	2218	class CleanupStrategyType>
sl@0	2219	class LCleanedupPtrBase: protected LAutoPtrBase<typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType>
sl@0	2220	{
sl@0	2221	typedef LAutoPtrBase<typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType> LAutoPtrBase;
sl@0	2222
sl@0	2223	protected:
sl@0	2224	typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::ManagedType ManagedType;
sl@0	2225	typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType BaseManagedType;
sl@0	2226	typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::CleanupStrategy CleanupStrategy;
sl@0	2227
sl@0	2228	LCleanedupPtrBase()
sl@0	2229	{
sl@0	2230	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2231	}
sl@0	2232
sl@0	2233	template<typename U>
sl@0	2234	explicit LCleanedupPtrBase(U* aPtr)
sl@0	2235	: LAutoPtrBase(aPtr)
sl@0	2236	{
sl@0	2237	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2238	}
sl@0	2239
sl@0	2240	~LCleanedupPtrBase()
sl@0	2241	{
sl@0	2242	ManagedPopCleanupStackItem(LAutoPtrBase::IsEnabled());
sl@0	2243	}
sl@0	2244
sl@0	2245	template<typename U>
sl@0	2246	LCleanedupPtrBase& operator=(U* aPtr)
sl@0	2247	{
sl@0	2248	ReleaseResource();
sl@0	2249	LAutoPtrBase::operator=(aPtr);
sl@0	2250	return *this;
sl@0	2251	}
sl@0	2252
sl@0	2253	void ReleaseResource()
sl@0	2254	{
sl@0	2255	if (!LAutoPtrBase::IsEnabled())
sl@0	2256	return;
sl@0	2257
sl@0	2258	CleanupStrategy::Cleanup(static_cast<ManagedType*>(iPtr));
sl@0	2259	LAutoPtrBase::Disable();
sl@0	2260	}
sl@0	2261
sl@0	2262	using LAutoPtrBase::Unmanage;
sl@0	2263
sl@0	2264	using LAutoPtrBase::IsEnabled;
sl@0	2265
sl@0	2266	using LAutoPtrBase::Get;
sl@0	2267
sl@0	2268	using LAutoPtrBase::operator->;
sl@0	2269
sl@0	2270	static void Cleanup(TAny* aPtr)
sl@0	2271	{
sl@0	2272	LCleanedupPtrBase* cleanupPtr = static_cast<LCleanedupPtrBase*>(aPtr);
sl@0	2273
sl@0	2274	if (cleanupPtr->IsEnabled())
sl@0	2275	{
sl@0	2276	CleanupStrategy::Cleanup(static_cast<ManagedType*>(cleanupPtr->iPtr));
sl@0	2277	}
sl@0	2278	}
sl@0	2279
sl@0	2280	using LAutoPtrBase::iPtr;
sl@0	2281
sl@0	2282	void Swap(LCleanedupPtrBase& aCleanedupPtr)
sl@0	2283	{
sl@0	2284	LAutoPtrBase::Swap(aCleanedupPtr);
sl@0	2285	}
sl@0	2286	};
sl@0	2287
sl@0	2288
sl@0	2289	/**
sl@0	2290	A class template that provides CleanupStack-based local-scope
sl@0	2291	automatic management of pointers.
sl@0	2292
sl@0	2293	@note This class can only be used to define locals, never
sl@0	2294	data members. See below for an explanation and links to management
sl@0	2295	classes suitable for use in different contexts. It should never be
sl@0	2296	used in the same function as code that uses the CleanupStack API
sl@0	2297	directly
sl@0	2298
sl@0	2299	This class template can be used to protect a pointer to type T such
sl@0	2300	that the instance of T referred to is automatically cleaned up
sl@0	2301	when either of the following occur:
sl@0	2302
sl@0	2303	- The referring local variable goes out of scope normally
sl@0	2304	- The referring local variable goes out of scope due to an
sl@0	2305	untrapped leave causing the scope to be exited non-locally
sl@0	2306
sl@0	2307	By default, the cleanup action is to delete the managed pointer
sl@0	2308	using non-array delete. An alternative cleanup strategy may be
sl@0	2309	selected by specifying a cleanup strategy template class in the
sl@0	2310	optional second template parameter position. The most common
sl@0	2311	alternative cleanup strategies are predefined.
sl@0	2312
sl@0	2313	The constructors of this class may leave.
sl@0	2314
sl@0	2315	As a convenience, the methods of the managed pointer may be
sl@0	2316	accessed via "->" notation directly on the management object, while
sl@0	2317	"." notation is used to access the interface of the management
sl@0	2318	object itself. Using "*" to dereference the management object
sl@0	2319	yields a T&, and is often useful when passing the managed object as
sl@0	2320	an argument.
sl@0	2321
sl@0	2322	Automatic cleanup may be disabled at any time by calling
sl@0	2323	Unmanage(), while cleanup may be forced at any time by calling
sl@0	2324	ReleaseResource().
sl@0	2325
sl@0	2326	Example:
sl@0	2327	@code
sl@0	2328	// block scope example
sl@0	2329	{
sl@0	2330	LCleanedupPtr<CDynamic> autop(new(ELeave) CDynamic);
sl@0	2331	autop->DoSomethingL(); // leave-safe
sl@0	2332	if (autop->Finished())
sl@0	2333	return; // the pointer is deleted automatically when exiting from scope
sl@0	2334	autop->DoSomethingElseL(); // leave-safe
sl@0	2335	// the pointer is deleted automatically when exiting from scope
sl@0	2336	}
sl@0	2337	@endcode
sl@0	2338
sl@0	2339	Behind the scenes, this class template is implemented in terms of
sl@0	2340	the thread-local CleanupStack, restricting its use to locals on the
sl@0	2341	stack. This use of the CleanupStack ensures a consistent cleanup
sl@0	2342	order between functions that call one another, even if they use
sl@0	2343	different cleanup idioms.
sl@0	2344
sl@0	2345	This class template together with the cleanup strategy class
sl@0	2346	templates provide a template-based implementation of the Strategy
sl@0	2347	design pattern (See also: Policy-based design).
sl@0	2348
sl@0	2349	@see TPointerDelete which implements the default deleting cleanup strategy
sl@0	2350	@see TPointerFree which implements the alternative User::Free() cleanup strategy
sl@0	2351	@see LManagedPtr which has the same interface, but does not use the cleanup
sl@0	2352	stack and is suitable for protecting the data members of classes
sl@0	2353	*/
sl@0	2354	template<typename T,
sl@0	2355	class CleanupStrategyType = TPtrCleanupStrategy>
sl@0	2356	class LCleanedupPtr: protected LCleanedupPtrBase<T, CleanupStrategyType>
sl@0	2357	{
sl@0	2358	typedef LCleanedupPtrBase<T, CleanupStrategyType> LCleanedupPtrBase;
sl@0	2359
sl@0	2360	public:
sl@0	2361	typedef T ManagedType;
sl@0	2362	typedef CleanupStrategyType CleanupStrategy;
sl@0	2363
sl@0	2364
sl@0	2365	/**
sl@0	2366	Default constructor. Constructs an empty LCleanedupPtr object.
sl@0	2367
sl@0	2368	@post Get() == NULL
sl@0	2369	*/
sl@0	2370	LCleanedupPtr()
sl@0	2371	{
sl@0	2372	}
sl@0	2373
sl@0	2374	/**
sl@0	2375	Explicit constructor template. Constructs a LCleanedupPtr object
sl@0	2376	that manages the pointer aPtr of a type convertible to T* that can
sl@0	2377	be cleaned up using the cleanup strategy of the LCleanedupPtr
sl@0	2378	class. The default cleanup strategy is to delete the pointer to a
sl@0	2379	heap-allocated object by using non-array delete. Alternative
sl@0	2380	cleanup strategies can be specified by using the CleanupStrategy
sl@0	2381	template parameter of the LCleanedupPtr class template.
sl@0	2382
sl@0	2383	@param aPtr A pointer of a type that is convertible to T* that can
sl@0	2384	be cleaned up using the cleanup strategy.
sl@0	2385
sl@0	2386	@pre aPtr is of a type convertible to T* and can be cleaned up
sl@0	2387	using the cleanup strategy.
sl@0	2388
sl@0	2389	@post Get() == aPtr
sl@0	2390	*/
sl@0	2391	explicit LCleanedupPtr(T* aPtr)
sl@0	2392	: LCleanedupPtrBase(aPtr)
sl@0	2393	{
sl@0	2394	}
sl@0	2395
sl@0	2396	/**
sl@0	2397	Assigns a new pointer to be managed. The new pointer must be of a
sl@0	2398	type convertible to T* and it must be possible to use the cleanup
sl@0	2399	strategy of the LCleanedupPtr object for the cleanup of the new
sl@0	2400	managed pointer. If the LCleanedupPtr object already contains a
sl@0	2401	managed pointer, then the cleanup strategy is invoked with the
sl@0	2402	managed pointer before assigning the new managed pointer.
sl@0	2403
sl@0	2404	@param aPtr A pointer of a type that is convertible to T* that can
sl@0	2405	be cleaned up using the cleanup strategy.
sl@0	2406
sl@0	2407	@pre aPtr is a pointer of a type that is convertible to T* and can
sl@0	2408	be cleaned up using the cleanup strategy.
sl@0	2409
sl@0	2410	@post Get() == aPtr
sl@0	2411	*/
sl@0	2412	LCleanedupPtr& operator=(T* aPtr)
sl@0	2413	{
sl@0	2414	LCleanedupPtrBase::operator=(aPtr);
sl@0	2415	return *this;
sl@0	2416	}
sl@0	2417
sl@0	2418	/**
sl@0	2419	Assigns a new pointer to be managed. The new pointer must be of a
sl@0	2420	type convertible to T* and it must be possible to use the cleanup
sl@0	2421	strategy of the LCleanedupPtr object for the cleanup of the new
sl@0	2422	managed pointer. If the LCleanedupPtr object already contains a
sl@0	2423	managed pointer, then the cleanup strategy is invoked with the
sl@0	2424	managed pointer before assigning the new managed pointer.
sl@0	2425
sl@0	2426	@param aPtr A pointer of a type that is convertible to T* that can
sl@0	2427	be cleaned up using the cleanup strategy.
sl@0	2428
sl@0	2429	@pre aPtr is a pointer of a type that is convertible to T* and can
sl@0	2430	be cleaned up using the cleanup strategy.
sl@0	2431
sl@0	2432	@post Get() == aPtr
sl@0	2433	*/
sl@0	2434	template<typename U>
sl@0	2435	LCleanedupPtr& operator=(U* aPtr)
sl@0	2436	{
sl@0	2437	LCleanedupPtrBase::operator=(aPtr);
sl@0	2438	return *this;
sl@0	2439	}
sl@0	2440
sl@0	2441
sl@0	2442	/**
sl@0	2443	If automatic resource management is enabled, the specified cleanup
sl@0	2444	strategy is invoked with the managed pointer and the automatic
sl@0	2445	resource management is then disabled. The underlying pointer is
sl@0	2446	reset to NULL.
sl@0	2447
sl@0	2448	@post Get() == NULL
sl@0	2449	*/
sl@0	2450	using LCleanedupPtrBase::ReleaseResource;
sl@0	2451
sl@0	2452	/**
sl@0	2453	Disables the automatic resource management for this object and
sl@0	2454	returns a pointer to the object of type T.
sl@0	2455
sl@0	2456	@return A pointer to the object of type T.
sl@0	2457	*/
sl@0	2458	T* Unmanage()
sl@0	2459	{
sl@0	2460	return static_cast<T*>(LCleanedupPtrBase::Unmanage());
sl@0	2461	}
sl@0	2462
sl@0	2463	/**
sl@0	2464	Returns ETrue if automatic resource management is enabled; EFalse
sl@0	2465	otherwise.
sl@0	2466
sl@0	2467	@return ETrue if automatic resource management is enabled; EFalse
sl@0	2468	otherwise.
sl@0	2469	*/
sl@0	2470	using LCleanedupPtrBase::IsEnabled;
sl@0	2471
sl@0	2472	/**
sl@0	2473	Returns a pointer to the managed object of type T.
sl@0	2474
sl@0	2475	@return A pointer to the managed object of type T.
sl@0	2476	*/
sl@0	2477	T* Get() const
sl@0	2478	{
sl@0	2479	return static_cast<T*>(iPtr);
sl@0	2480	}
sl@0	2481
sl@0	2482	/**
sl@0	2483	Overloaded indirection operator function.
sl@0	2484
sl@0	2485	@return A reference to the managed object of type T.
sl@0	2486	*/
sl@0	2487	T& operator*() const
sl@0	2488	{
sl@0	2489	return (static_cast<T>(iPtr));
sl@0	2490	}
sl@0	2491
sl@0	2492	/**
sl@0	2493	Overloaded class member access operator function.
sl@0	2494
sl@0	2495	@return A pointer to the managed object of type T.
sl@0	2496	*/
sl@0	2497	T* operator->() const
sl@0	2498	{
sl@0	2499	return static_cast<T*>(iPtr);
sl@0	2500	}
sl@0	2501
sl@0	2502	// Implementation type - do not use
sl@0	2503	typedef typename LCleanedupPtrBase::BaseManagedType* LCleanedupPtr<T, CleanupStrategy>::*TUnspecifiedBoolType;
sl@0	2504
sl@0	2505	/**
sl@0	2506	Conversion operator that enables LCleanedupPtr objects to be used
sl@0	2507	in boolean contexts.
sl@0	2508
sl@0	2509	@return An unspecified value of an unspecified type convertible to
sl@0	2510	boolean, which has a boolean value equal to Get() != NULL
sl@0	2511	*/
sl@0	2512	operator TUnspecifiedBoolType()
sl@0	2513	{
sl@0	2514	return iPtr ? &LCleanedupPtr::iPtr : NULL;
sl@0	2515	}
sl@0	2516
sl@0	2517	using LCleanedupPtrBase::Disable;
sl@0	2518
sl@0	2519	void Swap(LCleanedupPtr& aCleanedupPtr)
sl@0	2520	{
sl@0	2521	LCleanedupPtrBase::Swap(aCleanedupPtr);
sl@0	2522	}
sl@0	2523
sl@0	2524	private:
sl@0	2525	using LCleanedupPtrBase::iPtr;
sl@0	2526	};
sl@0	2527
sl@0	2528
sl@0	2529	// function template used for comparing two LCleanedupPtr-managed
sl@0	2530	// pointers for equality
sl@0	2531	template<typename T, typename U>
sl@0	2532	TBool operator==(const LCleanedupPtr<T>& aPtr1, const LCleanedupPtr<U>& aPtr2)
sl@0	2533	{
sl@0	2534	return aPtr1.Get() == aPtr2.Get();
sl@0	2535	}
sl@0	2536
sl@0	2537	// function template used for comparing two LCleanedupPtr-managed
sl@0	2538	// pointers for inequality
sl@0	2539	template<typename T, typename U>
sl@0	2540	TBool operator!=(const LCleanedupPtr<T>& aPtr1, const LCleanedupPtr<U>& aPtr2)
sl@0	2541	{
sl@0	2542	return aPtr1.Get() != aPtr2.Get();
sl@0	2543	}
sl@0	2544
sl@0	2545	// function template used for testing the ordering of two
sl@0	2546	// LCleanedupPtr-managed pointers
sl@0	2547	template<typename T, typename U>
sl@0	2548	TBool operator<(const LCleanedupPtr<T>& aPtr1, const LCleanedupPtr<U>& aPtr2)
sl@0	2549	{
sl@0	2550	return aPtr1.Get() < aPtr2.Get();
sl@0	2551	}
sl@0	2552
sl@0	2553
sl@0	2554	/**
sl@0	2555	A class template that provides CleanupStack-based local-scope
sl@0	2556	automatic management of arrays.
sl@0	2557
sl@0	2558	@note This class can only be used to define locals, never
sl@0	2559	data members. See below for an explanation and links to management
sl@0	2560	classes suitable for use in different contexts. It should never be
sl@0	2561	used in the same function as code that uses the CleanupStack API
sl@0	2562	directly
sl@0	2563
sl@0	2564	@par
sl@0	2565
sl@0	2566	@note This class can only be used with raw arrays, which are used
sl@0	2567	only rarely on Symbian OS. Instances of Symbian array container
sl@0	2568	classes (e.g. RArray, RPointerArray) should be managed using the
sl@0	2569	automatic management template classes appropriate for the array's
sl@0	2570	type (LCleanedupHandle template classes for Symbian R arrays or
sl@0	2571	LCleanedupPtr template classes for Symbian C arrays).
sl@0	2572
sl@0	2573	This class template can be used to protect a heap-allocated array
sl@0	2574	of objects of type T such that the array of T referred to is
sl@0	2575	automatically cleaned up when either of the following occur:
sl@0	2576
sl@0	2577	- The referring local variable goes out of scope normally
sl@0	2578	- The referring local variable goes out of scope due to an
sl@0	2579	untrapped leave causing the scope to be exited non-locally
sl@0	2580
sl@0	2581	The default cleanup strategy is to deallocate the managed array
sl@0	2582	using arrray delete (delete[]), assuming that the array is
sl@0	2583	heap-allocated. An alternative cleanup strategy can be selected by
sl@0	2584	specifying a cleanup strategy template class as the optional second
sl@0	2585	template argument (corresponding to the CleanupStrategy template
sl@0	2586	parameter).
sl@0	2587
sl@0	2588	The constructors of this class may leave.
sl@0	2589
sl@0	2590	As a convenience, the elements of the managed array may be accessed
sl@0	2591	via "[]" notation directly on the management object.
sl@0	2592
sl@0	2593	Automatic cleanup may be disabled at any time by calling
sl@0	2594	Unmanage(), while cleanup may be forced at any time by calling
sl@0	2595	ReleaseResource().
sl@0	2596
sl@0	2597	@code
sl@0	2598	// block scope example
sl@0	2599	{
sl@0	2600	LCleanedupArray<TValue> arrayp(new(ELeave) TValue[KArraySize]);
sl@0	2601	arrayp[0].DoSomethingL(); // leave-safe
sl@0	2602	if (arrayp[0].Finished())
sl@0	2603	return; // the array is deleted automatically when exiting from scope
sl@0	2604	arrayp[1].DoSomethingElseL(); // leave-safe
sl@0	2605	// the array is deleted automatically when exiting from scope
sl@0	2606	}
sl@0	2607	@endcode
sl@0	2608
sl@0	2609	Behind the scenes, this class template is implemented in terms of
sl@0	2610	the thread-local CleanupStack, restricting its use to locals on the
sl@0	2611	stack. This use of the CleanupStack ensures a consistent cleanup
sl@0	2612	order between functions that call one another, even if they use
sl@0	2613	different cleanup idioms.
sl@0	2614
sl@0	2615	This class template together with the cleanup strategy class
sl@0	2616	templates provide a template-based implementation of the Strategy
sl@0	2617	design pattern (See also: Policy-based design).
sl@0	2618
sl@0	2619	@see LManagedArray which has the same interface, but does not use
sl@0	2620	the cleanup stack and is suitable for protecting the data members
sl@0	2621	of classes
sl@0	2622	*/
sl@0	2623	template<typename T,
sl@0	2624	class CleanupStrategyType = TArrayDelete>
sl@0	2625	class LCleanedupArray: protected LAutoPtrBase<T>
sl@0	2626	{
sl@0	2627	typedef LAutoPtrBase<T> LAutoPtrBase;
sl@0	2628
sl@0	2629	public:
sl@0	2630	typedef T ManagedType;
sl@0	2631	typedef CleanupStrategyType CleanupStrategy;
sl@0	2632
sl@0	2633	/**
sl@0	2634	Default constructor. Constructs an empty LCleanedupArray object.
sl@0	2635
sl@0	2636	@post Get() == NULL
sl@0	2637	*/
sl@0	2638	LCleanedupArray()
sl@0	2639	{
sl@0	2640	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2641	}
sl@0	2642
sl@0	2643	/**
sl@0	2644	Explicit constructor. Constructs a LCleanedupArray object that
sl@0	2645	manages an array of objects of type T that can be cleaned up using
sl@0	2646	the cleanup strategy of the LCleanedupArray class. The default
sl@0	2647	cleanup strategy is to deallocate the heap-allocated array by using
sl@0	2648	array delete. An alternative cleanup strategy can be selected by
sl@0	2649	specifying a cleanup strategy template class as the optional second
sl@0	2650	template argument (corresponding to the CleanupStrategy template
sl@0	2651	parameter).
sl@0	2652
sl@0	2653	@param aPtr A pointer to the first element of an array of objects
sl@0	2654	of type T, array that can be cleaned up using the cleanup strategy
sl@0	2655	of the the LCleanedupArray class.
sl@0	2656
sl@0	2657	@pre The array can be cleaned up using the cleanup strategy.
sl@0	2658
sl@0	2659	@post Get() == aPtr
sl@0	2660	*/
sl@0	2661	explicit LCleanedupArray(T* aPtr)
sl@0	2662	: LAutoPtrBase(aPtr)
sl@0	2663	{
sl@0	2664	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2665	}
sl@0	2666
sl@0	2667
sl@0	2668	/**
sl@0	2669	Destructor. When automatic resource management is enabled, the
sl@0	2670	destructor invokes the specified cleanup strategy for the managed
sl@0	2671	pointer.
sl@0	2672	*/
sl@0	2673	~LCleanedupArray()
sl@0	2674	{
sl@0	2675	ManagedPopCleanupStackItem(LAutoPtrBase::IsEnabled());
sl@0	2676	}
sl@0	2677
sl@0	2678	/**
sl@0	2679	Assigns a new array of objects of type T to be managed. It needs
sl@0	2680	to be be possible to use the cleanup strategy of the
sl@0	2681	LCleanedupArray object for the cleanup of the new managed array.
sl@0	2682	The default cleanup strategy is to delete the heap-allocated array
sl@0	2683	by using array delete (delete[]). If the LCleanedupArray object
sl@0	2684	already manages an array, then the cleanup strategy is invoked with
sl@0	2685	the managed array before assigning the new managed array.
sl@0	2686
sl@0	2687	@param aPtr A pointer to the first element of the array of objects
sl@0	2688	of type T - array that can be cleaned up using the cleanup
sl@0	2689	strategy.
sl@0	2690
sl@0	2691	@pre The new array to be managed can be cleaned up using the
sl@0	2692	cleanup strategy.
sl@0	2693
sl@0	2694	@post Get() == aPtr
sl@0	2695	*/
sl@0	2696	LCleanedupArray& operator=(T* aPtr)
sl@0	2697	{
sl@0	2698	ReleaseResource();
sl@0	2699	LAutoPtrBase::operator=(aPtr);
sl@0	2700	return *this;
sl@0	2701	}
sl@0	2702
sl@0	2703	/**
sl@0	2704	If automatic resource management is enabled, the specified cleanup
sl@0	2705	strategy is invoked for the managed pointer and the automatic
sl@0	2706	resource management is then disabled. The underlying pointer is
sl@0	2707	reset to NULL.
sl@0	2708
sl@0	2709	@post Get() == NULL
sl@0	2710	*/
sl@0	2711	void ReleaseResource()
sl@0	2712	{
sl@0	2713	if (!LAutoPtrBase::IsEnabled())
sl@0	2714	return;
sl@0	2715
sl@0	2716	CleanupStrategy::Cleanup(iPtr);
sl@0	2717	iPtr = NULL;
sl@0	2718	}
sl@0	2719
sl@0	2720
sl@0	2721	/**
sl@0	2722	Disables the automatic resource management for this object and
sl@0	2723	returns a pointer to the first element of the array of objects of
sl@0	2724	type T.
sl@0	2725
sl@0	2726	@return A pointer to the first element of the array of objects of
sl@0	2727	type T.
sl@0	2728	*/
sl@0	2729	using LAutoPtrBase::Unmanage;
sl@0	2730
sl@0	2731	/**
sl@0	2732	Returns ETrue if automatic resource management is enabled; EFalse
sl@0	2733	otherwise.
sl@0	2734
sl@0	2735	@return ETrue if automatic resource management is enabled; EFalse
sl@0	2736	otherwise.
sl@0	2737	*/
sl@0	2738	using LAutoPtrBase::IsEnabled;
sl@0	2739
sl@0	2740	/**
sl@0	2741	Returns a pointer to the first element of the managed array of
sl@0	2742	objects of type T.
sl@0	2743
sl@0	2744	@return A pointer to the first element of the managed array of
sl@0	2745	objects of type T.
sl@0	2746	*/
sl@0	2747	using LAutoPtrBase::Get;
sl@0	2748
sl@0	2749	/**
sl@0	2750	Overloaded subscript operator.
sl@0	2751
sl@0	2752	@return A reference to the object of type T at the position aIndex.
sl@0	2753	*/
sl@0	2754	T& operator[](TInt aIndex) const
sl@0	2755	{
sl@0	2756	return iPtr[aIndex];
sl@0	2757	}
sl@0	2758
sl@0	2759	static void Cleanup(TAny* aPtr)
sl@0	2760	{
sl@0	2761	LCleanedupArray* cleanupPtr = static_cast<LCleanedupArray*>(aPtr);
sl@0	2762
sl@0	2763	if (cleanupPtr->IsEnabled())
sl@0	2764	{
sl@0	2765	CleanupStrategy::Cleanup(cleanupPtr->iPtr);
sl@0	2766	}
sl@0	2767	}
sl@0	2768
sl@0	2769	using LAutoPtrBase::Disable;
sl@0	2770
sl@0	2771	void Swap(LCleanedupArray& aArray)
sl@0	2772	{
sl@0	2773	LAutoPtrBase::Swap(aArray);
sl@0	2774	}
sl@0	2775
sl@0	2776	private:
sl@0	2777	using LAutoPtrBase::iPtr;
sl@0	2778	};
sl@0	2779
sl@0	2780
sl@0	2781	/**
sl@0	2782	A class template that provides CleanupStack-based local-scope
sl@0	2783	automatic management of references to resource handles (often
sl@0	2784	instances of R-classes).
sl@0	2785
sl@0	2786	@note This class can only be used to define locals, never
sl@0	2787	data members. See below for an explanation and links to management
sl@0	2788	classes suitable for use in different contexts. It should never be
sl@0	2789	used in the same function as code that uses the CleanupStack API
sl@0	2790	directly.
sl@0	2791
sl@0	2792	Unlike LCleanedupHandle which creates a fresh instance of its
sl@0	2793	managed type, this class template can be used to reference and
sl@0	2794	protect an existing resource handle of type T (typically an
sl@0	2795	R-class). The instance of T referred to has a cleanup operation run
sl@0	2796	on it automatically when either of the following occur:
sl@0	2797
sl@0	2798	- The referring local variable goes out of scope normally
sl@0	2799	- The referring local variable goes out of scope due to an
sl@0	2800	untrapped leave causing the scope to be exited non-locally
sl@0	2801
sl@0	2802	By default, the cleanup action is to call the Close() member
sl@0	2803	function of the referenced handle. An alternative cleanup strategy
sl@0	2804	may be selected by specifying a cleanup strategy template class in
sl@0	2805	the optional second template parameter position. The most common
sl@0	2806	alternative cleanup strategies are predefined. It is also possible
sl@0	2807	to specialize the default cleanup action for a given class using
sl@0	2808	the DEFINE_CLEANUP_FUNCTION macro.
sl@0	2809
sl@0	2810	The constructors of this class may leave.
sl@0	2811
sl@0	2812	As a convenience, the methods of the managed handle may be
sl@0	2813	accessed via "->" notation directly on the management object, while
sl@0	2814	"." notation is used to access the interface of the management
sl@0	2815	object itself. Using "*" to dereference the management object
sl@0	2816	yields a T&, and is often useful when passing the managed object as
sl@0	2817	an argument.
sl@0	2818
sl@0	2819	Automatic cleanup may be disabled at any time by calling
sl@0	2820	Unmanage(), while cleanup may be forced at any time by calling
sl@0	2821	ReleaseResource().
sl@0	2822
sl@0	2823	Example:
sl@0	2824	@code
sl@0	2825	// block scope example
sl@0	2826	void DoWithClosable(RClosable& aObj)
sl@0	2827	{
sl@0	2828	LCleanedupRef<RClosable> obj(aObj);
sl@0	2829	obj->DoSomethingL(); // leave-safe
sl@0	2830	if (obj->Finished())
sl@0	2831	return; // RClosable::Close is invoked automatically
sl@0	2832	obj->DoSomethingElseL(); // leave-safe
sl@0	2833	// RClosable::Close is invoked automatically
sl@0	2834	}
sl@0	2835	@endcode
sl@0	2836
sl@0	2837	Behind the scenes, this class template is implemented in terms of
sl@0	2838	the thread-local CleanupStack, restricting its use to locals on the
sl@0	2839	stack. This use of the CleanupStack ensures a consistent cleanup
sl@0	2840	order between functions that call one another, even if they use
sl@0	2841	different cleanup idioms.
sl@0	2842
sl@0	2843	This class template together with the cleanup strategy class
sl@0	2844	templates provide a template-based implementation of the Strategy
sl@0	2845	design pattern (See also: Policy-based design).
sl@0	2846
sl@0	2847	@see TClose which implements the default Close() calling cleanup strategy
sl@0	2848	@see TResetAndDestroy which implements an alternative
sl@0	2849	ResetAndDestroy() calling cleanup strategy
sl@0	2850	@see TFree which implements an alternative Free() calling cleanup
sl@0	2851	strategy
sl@0	2852	@see TDestroy which implements an alternative Destroy() calling
sl@0	2853	cleanup strategy
sl@0	2854	@see TRelease which implements an alternative Release() calling
sl@0	2855	cleanup strategy
sl@0	2856	@see LManagedRef which has the same interface, but does not use
sl@0	2857	the cleanup stack and is suitable for protecting the data members of
sl@0	2858	classes
sl@0	2859	@see LCleanedupHandle which has a similar interface but creates a
sl@0	2860	fresh local instance of T
sl@0	2861	*/
sl@0	2862	template<typename T,
sl@0	2863	class CleanupStrategyType = TResourceCleanupStrategy>
sl@0	2864	class LCleanedupRef: protected LAutoRefBase<T>
sl@0	2865	{
sl@0	2866	typedef LAutoRefBase<T> LAutoRefBase;
sl@0	2867
sl@0	2868	public:
sl@0	2869	typedef T ManagedType;
sl@0	2870	typedef CleanupStrategyType CleanupStrategy;
sl@0	2871
sl@0	2872	/**
sl@0	2873	Explicit constructor.
sl@0	2874	*/
sl@0	2875	template<typename U>
sl@0	2876	explicit LCleanedupRef(U& aRef)
sl@0	2877	: LAutoRefBase(aRef)
sl@0	2878	{
sl@0	2879	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	2880	}
sl@0	2881
sl@0	2882	/**
sl@0	2883	Destructor. When automatic resource management is enabled, the
sl@0	2884	destructor invokes the specified cleanup strategy for the managed
sl@0	2885	reference.
sl@0	2886	*/
sl@0	2887	~LCleanedupRef()
sl@0	2888	{
sl@0	2889	ManagedPopCleanupStackItem(LAutoRefBase::IsEnabled());
sl@0	2890	}
sl@0	2891
sl@0	2892	/**
sl@0	2893	Assigns a new reference to be managed. If the LCleanedupRef
sl@0	2894	object already contains a managed reference, then the specified
sl@0	2895	cleanup strategy is invoked for the managed reference before
sl@0	2896	assigning the new managed reference.
sl@0	2897	*/
sl@0	2898	template<typename U>
sl@0	2899	LCleanedupRef& operator=(U& aRef)
sl@0	2900	{
sl@0	2901	ReleaseResource();
sl@0	2902	LAutoRefBase::operator=(aRef);
sl@0	2903	return *this;
sl@0	2904	}
sl@0	2905
sl@0	2906	/**
sl@0	2907	If automatic resource management is enabled, the specified cleanup
sl@0	2908	strategy is invoked for the managed reference and the automatic
sl@0	2909	resource management is then disabled.
sl@0	2910	*/
sl@0	2911	void ReleaseResource()
sl@0	2912	{
sl@0	2913	if (!LAutoRefBase::IsEnabled())
sl@0	2914	return;
sl@0	2915
sl@0	2916	CleanupStrategy::Cleanup(iPtr);
sl@0	2917	iPtr = NULL;
sl@0	2918	}
sl@0	2919
sl@0	2920	/**
sl@0	2921	Disables the automatic resource management for this object and
sl@0	2922	returns a reference to the object of type T.
sl@0	2923
sl@0	2924	@return A reference to the object of type T.
sl@0	2925	*/
sl@0	2926	using LAutoRefBase::Unmanage;
sl@0	2927
sl@0	2928	/**
sl@0	2929	Returns ETrue if automatic resource management is enabled; EFalse
sl@0	2930	otherwise.
sl@0	2931
sl@0	2932	@return ETrue if automatic resource management is enabled; EFalse
sl@0	2933	otherwise.
sl@0	2934	*/
sl@0	2935	using LAutoRefBase::IsEnabled;
sl@0	2936
sl@0	2937	/**
sl@0	2938	Returns a reference to the managed object of type T.
sl@0	2939
sl@0	2940	@return A reference to the managed object of type T.
sl@0	2941	*/
sl@0	2942	using LAutoRefBase::Get;
sl@0	2943
sl@0	2944	/**
sl@0	2945	Overloaded indirection operator function.
sl@0	2946
sl@0	2947	@return A reference to the managed object of type T.
sl@0	2948	*/
sl@0	2949	using LAutoRefBase::operator*;
sl@0	2950
sl@0	2951	/**
sl@0	2952	Overloaded class member access operator function.
sl@0	2953
sl@0	2954	@return A pointer to the managed object of type T.
sl@0	2955	*/
sl@0	2956	using LAutoRefBase::operator->;
sl@0	2957
sl@0	2958
sl@0	2959	static void Cleanup(TAny* aPtr)
sl@0	2960	{
sl@0	2961	LCleanedupRef* cleanupRef = static_cast<LCleanedupRef*>(aPtr);
sl@0	2962
sl@0	2963	if (cleanupRef->IsEnabled())
sl@0	2964	{
sl@0	2965	CleanupStrategy::Cleanup(cleanupRef->iPtr);
sl@0	2966	}
sl@0	2967	}
sl@0	2968
sl@0	2969	using LAutoRefBase::Disable;
sl@0	2970
sl@0	2971	void Swap(LCleanedupRef& aRef)
sl@0	2972	{
sl@0	2973	LAutoRefBase::Swap(aRef);
sl@0	2974	}
sl@0	2975
sl@0	2976	private:
sl@0	2977	using LAutoRefBase::iPtr;
sl@0	2978	};
sl@0	2979
sl@0	2980
sl@0	2981	/**
sl@0	2982	A class that provides automatic cleanup using a TCleanupOperation
sl@0	2983	on the destruction of the LManagedGuard object.
sl@0	2984
sl@0	2985	@note This class can only be used to define object scoped cleanup
sl@0	2986	to guard object destruction, never local stack scoped cleanup. See
sl@0	2987	below for an explanation and links to management classes suitable
sl@0	2988	for use in different contexts.
sl@0	2989
sl@0	2990	This class can be used to manage a TCleanupOperation in such a way
sl@0	2991	that the specified cleanup operation is guaranteed to be called
sl@0	2992	when the guarding object is destroyed; typically when the object
sl@0	2993	containing it is deleted.
sl@0	2994
sl@0	2995	The constructors of this class never leave, so data members defined with
sl@0	2996	this type may be initialized safely during any phase of
sl@0	2997	construction of the owning class.
sl@0	2998
sl@0	2999	Automatic cleanup may be disabled at any time by calling
sl@0	3000	Dismiss(), while cleanup may be forced at any time by calling
sl@0	3001	Execute().
sl@0	3002
sl@0	3003	@code
sl@0	3004	class CComposite : public CBase
sl@0	3005	{
sl@0	3006	public:
sl@0	3007	CONSTRUCTORS_MAY_LEAVE
sl@0	3008
sl@0	3009	CComposite(RCleanable* aObj)
sl@0	3010	: iObj(RCleanable::Cleanup, aObj)
sl@0	3011	{
sl@0	3012	}
sl@0	3013
sl@0	3014	~CComposite()
sl@0	3015	{
sl@0	3016	// RCleanable::Cleanup(iObj) is automatically invoked
sl@0	3017	}
sl@0	3018
sl@0	3019	private:
sl@0	3020	LManagedGuard<RCleanable> iObj;
sl@0	3021	};
sl@0	3022	@endcode
sl@0	3023
sl@0	3024	Behind the scenes, this class template simply relies on reliable
sl@0	3025	execution of its destructor. If used for a local variable rather
sl@0	3026	than a data member, cleanup will occur but out-of-order compared to
sl@0	3027	objects protected using the LCleanupXxx variants or the
sl@0	3028	CleanupStack directly. Therefore it is not recommended for use in
sl@0	3029	that context.
sl@0	3030
sl@0	3031	These management classes may be used as the basis for implementing
sl@0	3032	leave-safe single-phase construction, since fully initialized
sl@0	3033	data members protected in this way will get destroyed (so reliably
sl@0	3034	triggering cleanup) if their containing classes leave during
sl@0	3035	execution of their constructors. Note, however, that single-phase
sl@0	3036	construction must be explicitly enabled in the containing class
sl@0	3037	using the CONSTRUCTORS_MAY_LEAVE macro.
sl@0	3038
sl@0	3039	@see LCleanedupGuard which has the same interface, but uses the cleanup
sl@0	3040	stack and is suitable for use as a local to guard local scope exit
sl@0	3041	@see CONSTRUCTORS_MAY_LEAVE
sl@0	3042	*/
sl@0	3043	class LManagedGuard
sl@0	3044	{
sl@0	3045	public:
sl@0	3046	/**
sl@0	3047	Constructor. Creates a LCleanedupGuard object that, when enabled,
sl@0	3048	automatically invokes upon destruction a cleanup operation
sl@0	3049	specified by the aCleanupOperation parameter with the pointer to
sl@0	3050	data specified by the aData parameter.
sl@0	3051
sl@0	3052	@param aCleanupOperation A cleanup operation.
sl@0	3053	@param aData Pointer to data to be passed to the cleanup operation
sl@0	3054	*/
sl@0	3055	LManagedGuard(TCleanupOperation aCleanupOperation, TAny* aData = 0)
sl@0	3056	: iCleanupOperation(aCleanupOperation),
sl@0	3057	iData(aData)
sl@0	3058	{
sl@0	3059	}
sl@0	3060
sl@0	3061	/**
sl@0	3062	Destructor.
sl@0	3063	*/
sl@0	3064	~LManagedGuard()
sl@0	3065	{
sl@0	3066	Execute();
sl@0	3067	}
sl@0	3068
sl@0	3069	/**
sl@0	3070	Executes the guard cleanup operation.
sl@0	3071	*/
sl@0	3072	void Execute()
sl@0	3073	{
sl@0	3074	if (iCleanupOperation)
sl@0	3075	{
sl@0	3076	iCleanupOperation(iData);
sl@0	3077	}
sl@0	3078	}
sl@0	3079
sl@0	3080	/**
sl@0	3081	Disables the guard.
sl@0	3082	*/
sl@0	3083	void Dismiss()
sl@0	3084	{
sl@0	3085	iCleanupOperation = NULL;
sl@0	3086	}
sl@0	3087
sl@0	3088	private:
sl@0	3089	LManagedGuard(const LManagedGuard&);
sl@0	3090	LManagedGuard& operator=(const LManagedGuard&);
sl@0	3091
sl@0	3092	TCleanupOperation iCleanupOperation;
sl@0	3093	TAny* iData;
sl@0	3094	};
sl@0	3095
sl@0	3096
sl@0	3097	/**
sl@0	3098	A class that provides CleanupStack-based local-scope automatic
sl@0	3099	cleanup using a TCleanupOperation on the destruction of the
sl@0	3100	LManagedGuard object.
sl@0	3101
sl@0	3102	@note This class can only be used to define a local stack scoped
sl@0	3103	cleanup, never an object scoped cleanup to guard object
sl@0	3104	destruction. See below for an explanation and links to management
sl@0	3105	classes suitable for use in different contexts.
sl@0	3106
sl@0	3107	This class can be used to manage a TCleanupOperation in such a way
sl@0	3108	that the specified cleanup operation is guaranteed to be called
sl@0	3109	when either of the following occur:
sl@0	3110
sl@0	3111	- The guarding local variable goes out of scope normally
sl@0	3112	- The guarding local variable goes out of scope due to an
sl@0	3113	untrapped leave causing the scope to be exited non-locally
sl@0	3114
sl@0	3115	The constructors of this class may leave.
sl@0	3116
sl@0	3117	Automatic cleanup may be disabled at any time by calling
sl@0	3118	Dismiss(), while cleanup may be forced at any time by calling
sl@0	3119	Execute().
sl@0	3120
sl@0	3121	@code
sl@0	3122	// block scope example
sl@0	3123	{
sl@0	3124	RCleanable obj;
sl@0	3125	LCleanedupGuard cleanGuard(RCleanable::Cleanup, &obj);
sl@0	3126
sl@0	3127	obj.DoSomethingL(); // leave-safe
sl@0	3128	if (Finished())
sl@0	3129	return; // RCleanable::Cleanup is invoked automatically when exiting from scope
sl@0	3130	obj.DoSomethingElseL(); // leave-safe
sl@0	3131	// RCleanable::Cleanup is invoked automatically when exiting from scope
sl@0	3132	}
sl@0	3133	@endcode
sl@0	3134
sl@0	3135	Behind the scenes, this class template is implemented in terms of
sl@0	3136	the thread-local CleanupStack, restricting its use to local stack
sl@0	3137	scope. This use of the CleanupStack ensures a consistent cleanup
sl@0	3138	order between functions that call one another, even if they use
sl@0	3139	different cleanup idioms.
sl@0	3140
sl@0	3141	@see LManagedGuard which has the same interface, but does not use the cleanup
sl@0	3142	stack and is suitable for use as the data member of a class to guard
sl@0	3143	object destruction.
sl@0	3144	*/
sl@0	3145	class LCleanedupGuard
sl@0	3146	{
sl@0	3147	public:
sl@0	3148	/**
sl@0	3149	Constructor. Creates a LCleanedupGuard object that, when enabled,
sl@0	3150	automatically invokes upon destruction a cleanup operation
sl@0	3151	specified by the aCleanupOperation parameter with the pointer to
sl@0	3152	data specified by the aData parameter.
sl@0	3153
sl@0	3154	@param aCleanupOperation A cleanup operation.
sl@0	3155	@param aData Pointer to data to be passed to the cleanup operation
sl@0	3156	*/
sl@0	3157	LCleanedupGuard(TCleanupOperation aCleanupOperation, TAny* aData = 0)
sl@0	3158	: iCleanupOperation(aCleanupOperation),
sl@0	3159	iData(aData)
sl@0	3160	{
sl@0	3161	CleanupStack::PushL(TCleanupItem(Cleanup, this));
sl@0	3162	}
sl@0	3163
sl@0	3164	/**
sl@0	3165	Destructor.
sl@0	3166	*/
sl@0	3167	~LCleanedupGuard()
sl@0	3168	{
sl@0	3169	ManagedPopCleanupStackItem(iCleanupOperation);
sl@0	3170	}
sl@0	3171
sl@0	3172	/**
sl@0	3173	Executes the guard cleanup operation.
sl@0	3174	*/
sl@0	3175	void Execute()
sl@0	3176	{
sl@0	3177	if (iCleanupOperation)
sl@0	3178	{
sl@0	3179	iCleanupOperation(iData);
sl@0	3180	}
sl@0	3181	}
sl@0	3182
sl@0	3183	/**
sl@0	3184	Disables the guard.
sl@0	3185	*/
sl@0	3186	void Dismiss()
sl@0	3187	{
sl@0	3188	iCleanupOperation = NULL;
sl@0	3189	}
sl@0	3190
sl@0	3191	static void Cleanup(TAny* aPtr)
sl@0	3192	{
sl@0	3193	LCleanedupGuard* guard = static_cast<LCleanedupGuard*>(aPtr);
sl@0	3194	guard->Execute();
sl@0	3195	}
sl@0	3196
sl@0	3197	private:
sl@0	3198	LCleanedupGuard(const LCleanedupGuard&);
sl@0	3199	LCleanedupGuard& operator=(const LCleanedupGuard&);
sl@0	3200
sl@0	3201
sl@0	3202	TCleanupOperation iCleanupOperation;
sl@0	3203	TAny* iData;
sl@0	3204	};
sl@0	3205
sl@0	3206	#endif // !EMANAGED_H
sl@0	3207

author	sl
	Tue, 10 Jun 2014 14:32:02 +0200
changeset 1	260cb5ec6c19
permissions	-rw-r--r--