williamr@2: // Copyright (c) 2001-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@2: // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: // which accompanies this distribution, and is available
williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.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: // The definitions required for the use
williamr@2: // of the ECOM framework by a client are contained / defined here.
williamr@2: // 
williamr@2: //
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef __ECOM_H__
williamr@2: #define __ECOM_H__
williamr@2: 
williamr@2: //////////////////////////////////////////////////////////////////////////////
williamr@2: // Include Files
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: #include <s32std.h>
williamr@2: #include <f32file.h>
williamr@2: 
williamr@2: #include <ecom/ecomerrorcodes.h>
williamr@2: #include <ecom/ecomresolverparams.h>
williamr@2: #include <ecom/implementationinformation.h>
williamr@2: 
williamr@2: 
williamr@2: //////////////////////////////////////////////////////////////////////////////
williamr@2: // Forward declarations
williamr@2: 
williamr@2: class CGlobalData;
williamr@2: 
williamr@2: 
williamr@2: //////////////////////////////////////////////////////////////////////////////
williamr@2: // Global Constants
williamr@2: 
williamr@2: /** 
williamr@2: The UID identifying the ROM-Only CResolver Interface Implementation. 
williamr@2: This resolver only returns implementations present on R/O internal media
williamr@2: (built-in) or upgrades of such implementations on R/W media. It does not 
williamr@2: return implementations that solely reside on R/W media. 
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TUid KRomOnlyResolverUid = {0x10009D92};
williamr@2: 
williamr@2: 
williamr@2: //////////////////////////////////////////////////////////////////////////////
williamr@2: // REComSession class
williamr@2: 
williamr@2: /**
williamr@2: The REComSession singleton class provides an API to identify (resolution), 
williamr@2: instantiate, and destroy interface class implementations requested by 
williamr@2: ECOM clients. It manages the session connection to the ECOM Server itself so 
williamr@2: that typically only one connection is made to the ECOM Server per thread.
williamr@2: It provides an un-initialise function where it releases memory and handles
williamr@2: of unused plug-ins, see the FinalClose() function. It also ensures that all
williamr@2: necessary clean-up is performed in the event of a Leave by any of the
williamr@2: ListImplementationsL() or CreateImplementationL() methods.
williamr@2: 
williamr@2: Note: Although a public default constructor is provided in this class
williamr@2: it is strongly recommended this object is never created by users of this
williamr@2: API on the stack or heap by value. To access the non-static methods of this
williamr@2: API use the static OpenL() method to obtain a pointer or a 
williamr@2: reference to the single reference counted session in use. Close() must be 
williamr@2: called when finished with.
williamr@2: 
williamr@2: Special care must be taken when using aDtorIDKey. It is a 32-bit instance key
williamr@2: that is returned from a call to one of the CreateImplementationL() methods. 
williamr@2: This instance key must only be used with DestroyedImplementation() to identify
williamr@2: the implementation instance for destruction, or GetImplementationUidL() to
williamr@2: retrieve the Implementation Uid of the instance it refers to.
williamr@2: No meaning must be attached to this instance key by ECOM clients 
williamr@2: and it must not be used for any other purpose.
williamr@2: 
williamr@2: 
williamr@2: @see REComSession::FinalClose()
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: class REComSession  : public RSessionBase
williamr@2: 	{
williamr@2: 	friend class CGlobalData;
williamr@2: public:
williamr@2: 
williamr@2: 	IMPORT_C REComSession();
williamr@2: 	IMPORT_C static REComSession& OpenL();
williamr@2: 	IMPORT_C void Close();
williamr@2: 	
williamr@2: 	// Notification API declarations
williamr@2:      
williamr@2: 	IMPORT_C void NotifyOnChange(TRequestStatus& aStatus);
williamr@2: 	IMPORT_C void CancelNotifyOnChange(TRequestStatus& aStatus);
williamr@2: 	
williamr@2: 	// List implementations API declarations
williamr@2: 	//
williamr@2: 	// Use LI1 to list all implementations, unfiltered.
williamr@2: 	// Use LI2 when default resolving required on the returned list.
williamr@2: 	// Use LI3 when custom resolving required on the returned list.
williamr@2: 	
williamr@2: 	// ListImplementationsL - LI1
williamr@2: 	IMPORT_C static void ListImplementationsL(
williamr@2:                             TUid aInterfaceUid,
williamr@2: 							RImplInfoPtrArray& aImplInfoArray);
williamr@2: 							
williamr@2: 	// ListImplementationsL - LI2
williamr@2: 	IMPORT_C static void ListImplementationsL(
williamr@2:                             TUid aInterfaceUid, 
williamr@2: 							const TEComResolverParams& aResolutionParameters,
williamr@2: 							RImplInfoPtrArray& aImplInfoArray);
williamr@2: 							
williamr@2: 	// ListImplementationsL - LI3
williamr@2: 	IMPORT_C static void ListImplementationsL(
williamr@2:                             TUid aInterfaceUid, 
williamr@2: 							const TEComResolverParams& aResolutionParameters, 
williamr@2: 							TUid aResolverUid,
williamr@2: 							RImplInfoPtrArray& aImplInfoArray);
williamr@2: 
williamr@2: 	// Create implementations API declarations
williamr@2:     //
williamr@2:     // When Implementation UID is known: 
williamr@2:     // Use CI1, CI2. 
williamr@2:     // Use CI3, CI4 when you have construction parameters.
williamr@2:     //
williamr@2:     // When the Interface UID is known and default resolving is required:
williamr@2:     // Use CI5, CI6. 
williamr@2:     // Use CI7, CI8 when you have construction parameters.
williamr@2:     // 
williamr@2:     // When the Interface UID is known and custom resolving is required:
williamr@2:     // Use CI9, CI10.
williamr@2:     // Use CI11, CI12 when you have construction parameters.
williamr@2: 	
williamr@2: 	// CreateImplementationL - CI1
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aImplementationUid, 
williamr@2:                             TUid& aDtorIDKey);
williamr@2:                             
williamr@2: 	// CreateImplementationL - CI2
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aImplementationUid, 
williamr@2: 							TInt32 aKeyOffset);
williamr@2: 							
williamr@2: 	// CreateImplementationL - CI3
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aImplementationUid, 
williamr@2: 							TUid& aDtorIDKey, 
williamr@2: 							TAny* aConstructionParameters);
williamr@2: 							
williamr@2: 	// CreateImplementationL - CI4
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aImplementationUid, 
williamr@2: 							TInt32 aKeyOffset,
williamr@2: 							TAny* aConstructionParameters);
williamr@2: 							
williamr@2: 	// CreateImplementationL - CI5
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aInterfaceUid, 
williamr@2: 							TUid& aDtorIDKey,
williamr@2: 							const TEComResolverParams& aResolutionParameters);
williamr@2: 							
williamr@2: 	// CreateImplementationL - CI6
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aInterfaceUid, 
williamr@2: 							TInt32 aKeyOffset, 
williamr@2: 							const TEComResolverParams& aResolutionParameters);
williamr@2: 							
williamr@2: 	// CreateImplementationL - CI7
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aInterfaceUid, 
williamr@2: 							TUid& aDtorIDKey, 
williamr@2: 							TAny* aConstructionParameters, 
williamr@2: 							const TEComResolverParams& aResolutionParameters);
williamr@2: 							
williamr@2: 	// CreateImplementationL - CI8
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aInterfaceUid, 
williamr@2: 							TInt32 aKeyOffset, 
williamr@2: 							TAny* aConstructionParameters, 
williamr@2: 							const TEComResolverParams& aResolutionParameters);
williamr@2: 							
williamr@2: 	// CreateImplementationL - CI9
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aInterfaceUid, 
williamr@2: 							TUid& aDtorIDKey, 
williamr@2: 							const TEComResolverParams& aResolutionParameters,
williamr@2: 							TUid aResolverUid);
williamr@2: 												
williamr@2: 	// CreateImplementationL - CI10
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aInterfaceUid, 
williamr@2: 							TInt32 aKeyOffset,
williamr@2: 							const TEComResolverParams& aResolutionParameters, 
williamr@2: 							TUid aResolverUid);
williamr@2: 												
williamr@2: 	// CreateImplementationL - CI11
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aInterfaceUid, 
williamr@2: 							TUid& aDtorIDKey, 
williamr@2: 							TAny* aConstructionParameters,
williamr@2: 							const TEComResolverParams& aResolutionParameters, 
williamr@2: 							TUid aResolverUid);
williamr@2: 												
williamr@2: 	// CreateImplementationL - CI12
williamr@2: 	IMPORT_C static TAny* CreateImplementationL(
williamr@2:                             TUid aInterfaceUid, 
williamr@2: 							TInt32 aKeyOffset, 
williamr@2: 							TAny* aConstructionParameters,
williamr@2: 							const TEComResolverParams& aResolutionParameters,
williamr@2: 							TUid aResolverUid);
williamr@2: 	
williamr@2: 	// Get Implementation Uid from a Destructor Id Key
williamr@2: 	IMPORT_C static TUid GetImplementationUidL(
williamr@2: 							TUid aDtorIDKey);
williamr@2: 	
williamr@2:     // Destroy Implementation API declaration											
williamr@2: 	IMPORT_C static void DestroyedImplementation(
williamr@2:                             TUid aDtorIDKey);
williamr@2: 
williamr@2: 
williamr@2: 	// See developer documentation for use of FinalClose.
williamr@2: 	IMPORT_C static void FinalClose();
williamr@2: 
williamr@2: private:
williamr@2: 	
williamr@2: 	static REComSession& OpenLC();
williamr@2: 	
williamr@2: 	void ConstructL();
williamr@2: 	void ReallyClose();
williamr@2: 	
williamr@2: 	void ListImplementationsL(
williamr@2:             TInt aServiceId, 
williamr@2: 			TUid aInterfaceUid, 
williamr@2: 			const TEComResolverParams& aResolutionParameters, 
williamr@2: 			TUid aResolverUid,
williamr@2: 			RImplInfoPtrArray& aImplInfoArray);
williamr@2: 			
williamr@2: 	TAny* ResolveAndCreateImplL(
williamr@2:             TUid aImplementationUid, 
williamr@2: 			TUid& aDtorIDKey, 
williamr@2: 			TAny* aCreationParameters, 
williamr@2:             TBool aCreationParamsFlag);
williamr@2:                                      
williamr@2: 	TAny* ResolveAndCreateImplL(
williamr@2:             TUid aInterfaceUid, 
williamr@2: 			const TEComResolverParams& aResolutionParameters, 
williamr@2: 			TUid& aDtorIDKey, 
williamr@2: 			TAny* aCreationParameters, 
williamr@2:             TBool aCreationParamsFlag);
williamr@2:                                      
williamr@2: 	TAny* ResolveAndCreateImplL(
williamr@2:             TUid aInterfaceUid, 
williamr@2: 			const TEComResolverParams& aResolutionParameters, 
williamr@2: 			TUid aResolverUid, 
williamr@2: 			TUid& aDtorIDKey, 
williamr@2: 			TAny* aCreationParameters, 
williamr@2:             TBool aCreationParamsFlag);
williamr@2:                                      
williamr@2: 	TAny* ResolveAndCreateImplL(
williamr@2:             TInt aServiceId,
williamr@2: 			TUid aInterfaceUid, 
williamr@2: 			const TEComResolverParams& aResolutionParameters, 
williamr@2: 			TUid aResolverUid, 
williamr@2: 			TUid& aDtorIDKey, 
williamr@2: 			TAny* aCreationParameters, 
williamr@2:             TBool aCreationParamsFlag);
williamr@2: 
williamr@2: public:
williamr@2:     //This API is for internal use only and for testing purposes.
williamr@2: 	IMPORT_C static void SetGetParametersL(const TIpcArgs &aArgs);
williamr@2: 												
williamr@2: private:
williamr@2:     /** Not used */
williamr@2: 	TInt iReserved1;
williamr@2: 
williamr@2: 	/** Not used */
williamr@2: 	TBool iReserved3;
williamr@2: 
williamr@2:     /** not used */
williamr@2: 	TInt iReserved2;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: #endif	// __ECOM_H__