--- /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 <e32base.h>
+#include <s32std.h>
+#include <f32file.h>
+
+#include <ecom/ecomerrorcodes.h>
+#include <ecom/ecomresolverparams.h>
+#include <ecom/implementationinformation.h>
+
+
+// ____________________________________________________________________________
+// 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__