williamr@2: // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: // Written by Brendan, Dec 1996
williamr@2: // Library associated files for pluggable components
williamr@2: // 
williamr@2: //
williamr@2: 
williamr@2: #if !defined(__LIBASSOC_H__)
williamr@2: #define __LIBASSOC_H__
williamr@2: #if !defined(__F32FILE_H__)
williamr@2: #include <f32file.h>
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: class TLibAssocBase
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: This is an implementation base class for TLibAssoc.
williamr@2: */
williamr@2: 	{
williamr@2: protected:
williamr@2: 	inline TLibAssocBase();
williamr@2: 	IMPORT_C TLibAssocBase(const RLibrary& aLib,TAny* aPtr);
williamr@2: 	IMPORT_C void Set(const RLibrary& aLib,TAny* aPtr);
williamr@2: 	IMPORT_C static void DoUnload(TAny* aThis);
williamr@2: public:
williamr@2: 	inline TBool IsNull() const;
williamr@2: private:
williamr@2: 	RLibrary iLibrary;
williamr@2: protected:
williamr@2: 
williamr@2:     /**
williamr@2:     A Pointer to the class instance.
williamr@2:     */
williamr@2: 	TAny* iPtr;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: //	class TLibAssoc inlines
williamr@2: inline TLibAssocBase::TLibAssocBase()
williamr@2: 	: iPtr(NULL)
williamr@2: /**
williamr@2: Default constructor.
williamr@2: 
williamr@2: It sets the member TLibAssocBase::iPtr to NULL.
williamr@2: */	
williamr@2: 	{}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: inline TBool TLibAssocBase::IsNull() const
williamr@2: /**
williamr@2: Tests whether the pointer to the class instance is NULL.
williamr@2: 
williamr@2: @return ETrue, if the pointer is NULL; EFalse, otherwise.
williamr@2: */
williamr@2: 	{return iPtr==NULL;}
williamr@2: 
williamr@2: 
williamr@2: //
williamr@2: //	class TLibAssoc
williamr@2: //
williamr@2: template <class T>
williamr@2: class TLibAssoc : public TLibAssocBase
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Associates a dynamically loadable DLL and an instance of a class that,
williamr@2: typically, will have been created using the ordinal 1 function of that DLL.
williamr@2: 
williamr@2: An object of this type is useful when cleanup behaviour requires that
williamr@2: a class instance be deleted and the associated DLL be closed.
williamr@2: 
williamr@2: The DLL is expected to be already open when the TLibAssoc object is created.
williamr@2: */
williamr@2: 	{
williamr@2: public:
williamr@2: 	inline TLibAssoc();
williamr@2: 	inline TLibAssoc(const RLibrary& aLib,T* aClass);
williamr@2: 	inline void Set(const RLibrary& aLib,T* aClass);
williamr@2: 	//
williamr@2: 	inline void Unload();
williamr@2: 	//
williamr@2: 	inline operator TCleanupItem();
williamr@2: 	operator TLibAssoc*(); // undefined, but here to prevent accidental delete(TLibAssoc)
williamr@2: 	//
williamr@2: 	inline T* Ptr();
williamr@2: 	inline const T* PtrC() const;
williamr@2: 	//
williamr@2: 	inline operator T*();
williamr@2: 	inline operator const T*() const;
williamr@2: 	//
williamr@2: 	inline T* operator->();
williamr@2: 	inline const T* operator->() const;
williamr@2: private:
williamr@2: 	static void Cleanup(TAny* aThis); // for TCleanupOperation
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: inline TLibAssoc<T>::TLibAssoc()
williamr@2: /**
williamr@2: Default constructor.
williamr@2: 
williamr@2: An association between a DLL and a class instance can be made
williamr@2: after construction using the Set() function.
williamr@2: */
williamr@2: 	{}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: inline TLibAssoc<T>::TLibAssoc(const RLibrary& aLib,T* aClass)
williamr@2: 	: TLibAssocBase(aLib,aClass)
williamr@2: /**
williamr@2: Constructs the object taking the specified DLL and an instance of
williamr@2: the specified class.
williamr@2: 
williamr@2: @param aLib   A reference to a DLL that has already been opened.
williamr@2: @param aClass A pointer to an object to be associated with the DLL.
williamr@2:               Typically, this object will have been created using
williamr@2:               the ordinal 1 function from that DLL.
williamr@2: */	
williamr@2: 	{}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: inline void TLibAssoc<T>::Set(const RLibrary& aLib,T* aClass)
williamr@2: /**
williamr@2: Makes an association between the specified DLL and an instance of
williamr@2: the specified class.
williamr@2: 
williamr@2: @param aLib   A reference to a DLL that has already been opened.
williamr@2: @param aClass A pointer to an object to be associated with the DLL.
williamr@2:               Typically, this object will have been created using
williamr@2:               the ordinal 1 function from that DLL.
williamr@2: */
williamr@2: 	{TLibAssocBase::Set(aLib,aClass);}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: inline T* TLibAssoc<T>::Ptr()
williamr@2: /**
williamr@2: Gets a pointer to the class instance.
williamr@2: 
williamr@2: @return A pointer to the class instance.
williamr@2: */
williamr@2: 	{return (T*)iPtr;}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: inline const T* TLibAssoc<T>::PtrC() const
williamr@2: /**
williamr@2: Gets a pointer to the const class instance.
williamr@2: 
williamr@2: @return A pointer to the const class instance.
williamr@2: */
williamr@2: 	{return (const T*)iPtr;}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: inline TLibAssoc<T>::operator T*()
williamr@2: /**
williamr@2: Conversion operator.
williamr@2: 
williamr@2: Invoked by the compiler when a TLibAssoc<T> type is passed to a function that
williamr@2: is prototyped to take a T* type.
williamr@2: */
williamr@2: 	{return (T*)iPtr;}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: inline TLibAssoc<T>::operator const T*() const
williamr@2: /**
williamr@2: Const conversion operator.
williamr@2: 
williamr@2: Invoked by the compiler when a TLibAssoc<T> type is passed to a function that
williamr@2: is prototyped to take a const T* type.
williamr@2: */
williamr@2: 	{return (const T*)iPtr;}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: inline T* TLibAssoc<T>::operator->()
williamr@2: /**
williamr@2: Dereferencing operator.
williamr@2: 
williamr@2: @return A pointer to the class instance.
williamr@2: */
williamr@2: 	{return (T*)iPtr;}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: inline const T* TLibAssoc<T>::operator->() const
williamr@2: /**
williamr@2: Const dereferencing operator.
williamr@2: 
williamr@2: @return A pointer to the const class instance.
williamr@2: */
williamr@2: 	{return (const T*)iPtr;}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: inline TLibAssoc<T>::operator TCleanupItem()
williamr@2: /**
williamr@2: The TCleanupItem conversion operator.
williamr@2: 
williamr@2: Invoked by the compiler when a TLibAssoc<T> type is passed to a function that
williamr@2: is prototyped to take a TCleanupItem type.
williamr@2: 
williamr@2: The most common usage is to put a cleanup item onto the cleanup stack using
williamr@2: CleanupStack::PushL(). The cleanup operation is represented by the private
williamr@2: static function Cleanup().
williamr@2: 
williamr@2: For example, if we declare
williamr@2: 
williamr@2: @code
williamr@2: TLibAssoc<A> a;
williamr@2: @endcode 
williamr@2: 
williamr@2: then we can simply put a cleanup item onto the cleanup stack
williamr@2: by calling
williamr@2: 
williamr@2: @code
williamr@2: CleanupStack::PushL(a);
williamr@2: @endcode
williamr@2: 
williamr@2: @see TCleanupItem
williamr@2: @see CleanupStack::PushL
williamr@2: */
williamr@2: 	{return(TCleanupItem(Cleanup,this));}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: inline void TLibAssoc<T>::Unload()
williamr@2: /**
williamr@2: Deletes the class instance and calls Close() on the associated DLL.
williamr@2: 
williamr@2: @see RLibrary::Close
williamr@2: */
williamr@2: 	{Cleanup(this);}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: template <class T>
williamr@2: void TLibAssoc<T>::Cleanup(TAny* aThis)
williamr@2: /**
williamr@2: The cleanup operation.
williamr@2: 
williamr@2: The implementation deletes the class instance and calls Close() on
williamr@2: the associated DLL.
williamr@2: 
williamr@2: Note that this function is internal and is not intended for use; it is documented
williamr@2: for completeness.
williamr@2: */
williamr@2: 	{
williamr@2: 	delete (T*)(((TLibAssoc<T>*)aThis)->iPtr);
williamr@2: 	TLibAssocBase::DoUnload(aThis);
williamr@2: 	}
williamr@2: 
williamr@2: #endif