diff -r 000000000000 -r e4d67989cc36 lowlevellibsandfws/pluginfw/Framework/inc/ECom.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lowlevellibsandfws/pluginfw/Framework/inc/ECom.h Tue Feb 02 02:01:42 2010 +0200 @@ -0,0 +1,451 @@ +// 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 "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// The API definitions required for the use of the ECOM framework by a client +// are contained / defined here. +// +// + +/** + @file + @publishedAll + @released +*/ + +#ifndef __ECOM_H__ +#define __ECOM_H__ + +// ____________________________________________________________________________ +// INCLUDES + +#include +#include +#include + +#include +#include +#include + + +// ____________________________________________________________________________ +// CONSTANTS + +class CGlobalData; + +/** +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. +*/ +const TUid KRomOnlyResolverUid = {0x10009D92}; + + +// ____________________________________________________________________________ +// CLASSES + +/** +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 aInstanceKey. 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() +*/ +class REComSession : public RSessionBase + { + friend class CGlobalData; + +public: // publishedAll APIs + // Available for use by all clients + + IMPORT_C REComSession(); + + IMPORT_C static REComSession& OpenL(); + IMPORT_C void Close(); + + // Get Implementation Uid from an Instance Key + IMPORT_C static TUid GetImplementationUidL( + TUid aInstanceKey); + + // Destroy Implementation API declaration + IMPORT_C static void DestroyedImplementation( + TUid aInstanceKey); + + // See developer documentation for use of FinalClose. + IMPORT_C static void FinalClose(); + + + // 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); + + // Use LI7 to list all implementations, unfiltered and with no capability chaeck. + // Use LI8 when default resolving required on the returned list and with no capability chaeck. + // Use LI9 when custom resolving required on the returned list and with no capability chaeck. + + // ListImplementationsL - LI7 + IMPORT_C static void ListImplementationsL( + TUid aInterfaceUid, + RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck); + + // ListImplementationsL - LI8 + IMPORT_C static void ListImplementationsL( + TUid aInterfaceUid, + const TEComResolverParams& aResolutionParameters, + RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck); + + // ListImplementationsL - LI9 + IMPORT_C static void ListImplementationsL( + TUid aInterfaceUid, + const TEComResolverParams& aResolutionParameters, + TUid aResolverUid, + RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck); + + + // 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& aInstanceKey); + + // CreateImplementationL - CI2 + IMPORT_C static TAny* CreateImplementationL( + TUid aImplementationUid, + TInt32 aKeyOffset); + + // CreateImplementationL - CI3 + IMPORT_C static TAny* CreateImplementationL( + TUid aImplementationUid, + TUid& aInstanceKey, + 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& aInstanceKey, + 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& aInstanceKey, + 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& aInstanceKey, + 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& aInstanceKey, + 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); + + +public: // publishedPartner APIs + // Extended interfaces API declarations available for use by + // all system software i.e by phone manufacturers and internally (i.e. not supported for use by 3rd parties) + // See Symbian OS Developer Library and ECOM How To/FAQ documentation. + + + // List implementations API declarations + // + // Use L14 to list all implementations which satisfy interface, extended + // interfaces + // Use L15 to list all implementations which satisfy interface, extended + // interfaces when default resolving required on the list returned + // Use L16 to list all implementations which satisfy interface, extended + // interfaces when custom resolving required on the list returned + + // ListImplementationsL - LI4 + IMPORT_C static void ListImplementationsL( + TUid aInterfaceUid, + RExtendedInterfacesArray& aExtendedInterfaces, + RImplInfoPtrArray& aImplInfoArray); + + // ListImplementationsL - LI5 + IMPORT_C static void ListImplementationsL( + TUid aInterfaceUid, + RExtendedInterfacesArray& aExtendedInterfaces, + const TEComResolverParams& aResolutionParameters, + RImplInfoPtrArray& aImplInfoArray); + + // ListImplementationsL - LI6 + IMPORT_C static void ListImplementationsL( + TUid aInterfaceUid, + RExtendedInterfacesArray& aExtendedInterfaces, + const TEComResolverParams& aResolutionParameters, + TUid aResolverUid, + RImplInfoPtrArray& aImplInfoArray); + + + // Create implementations API declarations + // + // When the interface UID and the extended interface UID's are known + // and default resolving is required. The construction parameters may + // optionally be provided. + // Use CI13: Instance key is returned + // Use CI14: An offset to aInstanceKey returned by the ECom framework + // to identify this instance to the framework + // When the interface UID and the extended interface UID's are known + // and custom resolving is required. The construction parameters may + // optionally be provided. + // Use CI15: Instance key is returned + // Use CI16: An offset to aInstanceKey returned by the ECom framework + // to identify this instance to the framework + + // CreateImplementationL - CI13 + IMPORT_C static TAny* CreateImplementationL( + TUid aInterfaceUid, + const RExtendedInterfacesArray& aExtendedInterfaces, + TUid& aInstanceKey, + const TEComResolverParams& aResolutionParameters, + TAny* aConstructionParameters = NULL); + + // CreateImplementationL - CI14 + IMPORT_C static TAny* CreateImplementationL( + TUid aInterfaceUid, + const RExtendedInterfacesArray& aExtendedInterfaces, + TInt32 aKeyOffset, + const TEComResolverParams& aResolutionParameters, + TAny* aConstructionParameters = NULL); + + // CreateImplementationL - CI15 + IMPORT_C static TAny* CreateImplementationL( + TUid aInterfaceUid, + const RExtendedInterfacesArray& aExtendedInterfaces, + TUid& aInstanceKey, + const TEComResolverParams& aResolutionParameters, + TUid aResolverUid, + TAny* aConstructionParameters = NULL); + + // CreateImplementationL - CI16 + IMPORT_C static TAny* CreateImplementationL( + TUid aInterfaceUid, + const RExtendedInterfacesArray& aExtendedInterfaces, + TInt32 aKeyOffset, + const TEComResolverParams& aResolutionParameters, + TUid aResolverUid, + TAny* aConstructionParameters = NULL); + + + // Extended Interface query and management API declarations + // + + IMPORT_C static TAny* GetExtendedInterfaceL( + const TUid& aInstanceKey, + const TUid& aExtendedInterfaceUid); + + IMPORT_C static void ListExtendedInterfacesL( + const TUid& aImplementationUid, + RExtendedInterfacesArray& aIfInfo); + + IMPORT_C static void ManuallyReleaseExtendedInterfaceL( + const TUid& aInstanceKey, + const TUid& aExtendedInterfaceUid); + + +private: // @internalComponent APIs + // This API is for internal testing purposes.Should not be used externally by clients. + + static REComSession& OpenLC(); + + void ConstructL(); + void ReallyClose(); + + void ListImplementationsL( + TInt aServiceId, + TUid aInterfaceUid, + const RExtendedInterfacesArray& aExtendedInterfaces, + const TEComResolverParams& aResolutionParameters, + TUid aResolverUid, + RImplInfoPtrArray& aImplInfoArray, + TBool aCapabilityCheck = ETrue); + + TAny* ResolveAndCreateImplL( + TUid aImplementationUid, + TUid& aInstanceKey, + TAny* aCreationParameters, + TBool aCreationParamsFlag); + + TAny* ResolveAndCreateImplL( + TUid aInterfaceUid, + const TEComResolverParams& aResolutionParameters, + TUid& aInstanceKey, + TAny* aCreationParameters, + TBool aCreationParamsFlag); + + TAny* ResolveAndCreateImplL( + TUid aInterfaceUid, + const TEComResolverParams& aResolutionParameters, + TUid aResolverUid, + TUid& aInstanceKey, + TAny* aCreationParameters, + TBool aCreationParamsFlag); + + TAny* ResolveAndCreateImplL( + TUid aInterfaceUid, + const RExtendedInterfacesArray& aExtendedInterfaces, + const TEComResolverParams& aResolutionParameters, + TUid& aInstanceKey, + TAny* aCreationParameters, + TBool aCreationParamsFlag); + + TAny* ResolveAndCreateImplL( + TUid aInterfaceUid, + const RExtendedInterfacesArray& aExtendedInterfaces, + const TEComResolverParams& aResolutionParameters, + TUid aResolverUid, + TUid& aInstanceKey, + TAny* aCreationParameters, + TBool aCreationParamsFlag); + + TAny* ResolveAndCreateImplL( + TInt aServiceId, + TUid aInterfaceUid, + const RExtendedInterfacesArray& aExtendedInterfaces, + const TEComResolverParams& aResolutionParameters, + TUid aResolverUid, + TUid& aInstanceKey, + TAny* aCreationParameters, + TBool aCreationParamsFlag); + + void ProcessListExtendedInterfacesL( + const TUid& aImplementationUid, + RExtendedInterfacesArray& aIfInfo); + + void PackMatchStrAndExtendedInterfacesL( + const TEComResolverParams& aResolutionParameters, + const RExtendedInterfacesArray& aExtendedInterfaces, + RBuf8& aMatchStrExtInfBuf); + + +public: // @internalComponent APIs + // Internal methods used inside ECOM, not for client use. + + // This API is for internal testing purposes. + IMPORT_C static void SetGetParametersL(const TIpcArgs &aArgs); + + +private: + /** Not used */ + TInt iReserved1; + + /** not used */ + TInt iReserved3; + /** not used */ + TInt iReserved2; + }; + +#endif // __ECOM_H__