// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

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

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// The definitions required for the use

// of the ECOM framework by a client are contained / defined here.

// 

//

#ifndef __ECOM_H__

#define __ECOM_H__

//////////////////////////////////////////////////////////////////////////////

// Include Files

#include <e32base.h>

#include <s32std.h>

#include <f32file.h>

#include <ecom/ecomerrorcodes.h>

#include <ecom/ecomresolverparams.h>

#include <ecom/implementationinformation.h>

//////////////////////////////////////////////////////////////////////////////

// Forward declarations

class CGlobalData;

//////////////////////////////////////////////////////////////////////////////

// Global Constants

/** 

The UID identifying the ROM-Only CResolver Interface Implementation. 

This resolver only returns implementations present on R/O internal media

(built-in) or upgrades of such implementations on R/W media. It does not 

return implementations that solely reside on R/W media. 

@publishedAll

@released

*/

const TUid KRomOnlyResolverUid = {0x10009D92};

//////////////////////////////////////////////////////////////////////////////

// REComSession class

/**

The REComSession singleton class provides an API to identify (resolution), 

instantiate, and destroy interface class implementations requested by 

ECOM clients. It manages the session connection to the ECOM Server itself so 

that typically only one connection is made to the ECOM Server per thread.

It provides an un-initialise function where it releases memory and handles

of unused plug-ins, see the FinalClose() function. It also ensures that all

necessary clean-up is performed in the event of a Leave by any of the

ListImplementationsL() or CreateImplementationL() methods.

Note: Although a public default constructor is provided in this class

it is strongly recommended this object is never created by users of this

API on the stack or heap by value. To access the non-static methods of this

API use the static OpenL() method to obtain a pointer or a 

reference to the single reference counted session in use. Close() must be 

called when finished with.

Special care must be taken when using aDtorIDKey. It is a 32-bit instance key

that is returned from a call to one of the CreateImplementationL() methods. 

This instance key must only be used with DestroyedImplementation() to identify

the implementation instance for destruction, or GetImplementationUidL() to

retrieve the Implementation Uid of the instance it refers to.

No meaning must be attached to this instance key by ECOM clients 

and it must not be used for any other purpose.

@see REComSession::FinalClose()

@publishedAll

@released

*/

class REComSession  : public RSessionBase

	{

	friend class CGlobalData;

public:

	IMPORT_C REComSession();

	IMPORT_C static REComSession& OpenL();

	IMPORT_C void Close();

	// Notification API declarations

	IMPORT_C void NotifyOnChange(TRequestStatus& aStatus);

	IMPORT_C void CancelNotifyOnChange(TRequestStatus& aStatus);

	// List implementations API declarations

	//

	// Use LI1 to list all implementations, unfiltered.

	// Use LI2 when default resolving required on the returned list.

	// Use LI3 when custom resolving required on the returned list.

	// ListImplementationsL - LI1

	IMPORT_C static void ListImplementationsL(

                            TUid aInterfaceUid,

							RImplInfoPtrArray& aImplInfoArray);

	// ListImplementationsL - LI2

	IMPORT_C static void ListImplementationsL(

                            TUid aInterfaceUid, 

							const TEComResolverParams& aResolutionParameters,

							RImplInfoPtrArray& aImplInfoArray);

	// ListImplementationsL - LI3

	IMPORT_C static void ListImplementationsL(

                            TUid aInterfaceUid, 

							const TEComResolverParams& aResolutionParameters, 

							TUid aResolverUid,

							RImplInfoPtrArray& aImplInfoArray);

	// Create implementations API declarations

    //

    // When Implementation UID is known: 

    // Use CI1, CI2. 

    // Use CI3, CI4 when you have construction parameters.

    //

    // When the Interface UID is known and default resolving is required:

    // Use CI5, CI6. 

    // Use CI7, CI8 when you have construction parameters.

    // 

    // When the Interface UID is known and custom resolving is required:

    // Use CI9, CI10.

    // Use CI11, CI12 when you have construction parameters.

	// CreateImplementationL - CI1

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aImplementationUid, 

                            TUid& aDtorIDKey);

	// CreateImplementationL - CI2

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aImplementationUid, 

							TInt32 aKeyOffset);

	// CreateImplementationL - CI3

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aImplementationUid, 

							TUid& aDtorIDKey, 

							TAny* aConstructionParameters);

	// CreateImplementationL - CI4

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aImplementationUid, 

							TInt32 aKeyOffset,

							TAny* aConstructionParameters);

	// CreateImplementationL - CI5

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aInterfaceUid, 

							TUid& aDtorIDKey,

							const TEComResolverParams& aResolutionParameters);

	// CreateImplementationL - CI6

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aInterfaceUid, 

							TInt32 aKeyOffset, 

							const TEComResolverParams& aResolutionParameters);

	// CreateImplementationL - CI7

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aInterfaceUid, 

							TUid& aDtorIDKey, 

							TAny* aConstructionParameters, 

							const TEComResolverParams& aResolutionParameters);

	// CreateImplementationL - CI8

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aInterfaceUid, 

							TInt32 aKeyOffset, 

							TAny* aConstructionParameters, 

							const TEComResolverParams& aResolutionParameters);

	// CreateImplementationL - CI9

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aInterfaceUid, 

							TUid& aDtorIDKey, 

							const TEComResolverParams& aResolutionParameters,

							TUid aResolverUid);

	// CreateImplementationL - CI10

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aInterfaceUid, 

							TInt32 aKeyOffset,

							const TEComResolverParams& aResolutionParameters, 

							TUid aResolverUid);

	// CreateImplementationL - CI11

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aInterfaceUid, 

							TUid& aDtorIDKey, 

							TAny* aConstructionParameters,

							const TEComResolverParams& aResolutionParameters, 

							TUid aResolverUid);

	// CreateImplementationL - CI12

	IMPORT_C static TAny* CreateImplementationL(

                            TUid aInterfaceUid, 

							TInt32 aKeyOffset, 

							TAny* aConstructionParameters,

							const TEComResolverParams& aResolutionParameters,

							TUid aResolverUid);

	// Get Implementation Uid from a Destructor Id Key

	IMPORT_C static TUid GetImplementationUidL(

							TUid aDtorIDKey);

    // Destroy Implementation API declaration											

	IMPORT_C static void DestroyedImplementation(

                            TUid aDtorIDKey);

	// See developer documentation for use of FinalClose.

	IMPORT_C static void FinalClose();

private:

	static REComSession& OpenLC();

	void ConstructL();

	void ReallyClose();

	void ListImplementationsL(

            TInt aServiceId, 

			TUid aInterfaceUid, 

			const TEComResolverParams& aResolutionParameters, 

			TUid aResolverUid,

			RImplInfoPtrArray& aImplInfoArray);

	TAny* ResolveAndCreateImplL(

            TUid aImplementationUid, 

			TUid& aDtorIDKey, 

			TAny* aCreationParameters, 

            TBool aCreationParamsFlag);

	TAny* ResolveAndCreateImplL(

            TUid aInterfaceUid, 

			const TEComResolverParams& aResolutionParameters, 

			TUid& aDtorIDKey, 

			TAny* aCreationParameters, 

            TBool aCreationParamsFlag);

	TAny* ResolveAndCreateImplL(

            TUid aInterfaceUid, 

			const TEComResolverParams& aResolutionParameters, 

			TUid aResolverUid, 

			TUid& aDtorIDKey, 

			TAny* aCreationParameters, 

            TBool aCreationParamsFlag);

	TAny* ResolveAndCreateImplL(

            TInt aServiceId,

			TUid aInterfaceUid, 

			const TEComResolverParams& aResolutionParameters, 

			TUid aResolverUid, 

			TUid& aDtorIDKey, 

			TAny* aCreationParameters, 

            TBool aCreationParamsFlag);

public:

    //This API is for internal use only and for testing purposes.

	IMPORT_C static void SetGetParametersL(const TIpcArgs &aArgs);

private:

    /** Not used */

	TInt iReserved1;

	/** Not used */

	TBool iReserved3;

    /** not used */

	TInt iReserved2;

	};

#endif	// __ECOM_H__