--- a/epoc32/include/ecom/ecom.h Wed Mar 31 12:27:01 2010 +0100
+++ b/epoc32/include/ecom/ecom.h Wed Mar 31 12:33:34 2010 +0100
@@ -1,9 +1,9 @@
// 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
+// under the terms of "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
-// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
@@ -11,18 +11,22 @@
// Contributors:
//
// Description:
-// The definitions required for the use
-// of the ECOM framework by a client are contained / defined here.
+// 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__
-//////////////////////////////////////////////////////////////////////////////
-// Include Files
+// ____________________________________________________________________________
+// INCLUDES
#include <e32base.h>
#include <s32std.h>
@@ -33,29 +37,22 @@
#include <ecom/implementationinformation.h>
-//////////////////////////////////////////////////////////////////////////////
-// Forward declarations
+// ____________________________________________________________________________
+// CONSTANTS
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
+// ____________________________________________________________________________
+// CLASSES
/**
The REComSession singleton class provides an API to identify (resolution),
@@ -74,7 +71,7 @@
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
+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
@@ -84,29 +81,44 @@
@see REComSession::FinalClose()
-@publishedAll
-@released
*/
class REComSession : public RSessionBase
{
friend class CGlobalData;
-public:
+
+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,
@@ -124,6 +136,29 @@
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
//
@@ -138,11 +173,11 @@
// 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);
+ TUid& aInstanceKey);
// CreateImplementationL - CI2
IMPORT_C static TAny* CreateImplementationL(
@@ -152,7 +187,7 @@
// CreateImplementationL - CI3
IMPORT_C static TAny* CreateImplementationL(
TUid aImplementationUid,
- TUid& aDtorIDKey,
+ TUid& aInstanceKey,
TAny* aConstructionParameters);
// CreateImplementationL - CI4
@@ -164,7 +199,7 @@
// CreateImplementationL - CI5
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
- TUid& aDtorIDKey,
+ TUid& aInstanceKey,
const TEComResolverParams& aResolutionParameters);
// CreateImplementationL - CI6
@@ -176,7 +211,7 @@
// CreateImplementationL - CI7
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
- TUid& aDtorIDKey,
+ TUid& aInstanceKey,
TAny* aConstructionParameters,
const TEComResolverParams& aResolutionParameters);
@@ -190,7 +225,7 @@
// CreateImplementationL - CI9
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
- TUid& aDtorIDKey,
+ TUid& aInstanceKey,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid);
@@ -204,7 +239,7 @@
// CreateImplementationL - CI11
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
- TUid& aDtorIDKey,
+ TUid& aInstanceKey,
TAny* aConstructionParameters,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid);
@@ -217,20 +252,113 @@
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid);
- // Get Implementation Uid from a Destructor Id Key
- IMPORT_C static TUid GetImplementationUidL(
- TUid aDtorIDKey);
+
+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);
- // Destroy Implementation API declaration
- IMPORT_C static void DestroyedImplementation(
- TUid aDtorIDKey);
-
+ IMPORT_C static void ListExtendedInterfacesL(
+ const TUid& aImplementationUid,
+ RExtendedInterfacesArray& aIfInfo);
+
+ IMPORT_C static void ManuallyReleaseExtendedInterfaceL(
+ const TUid& aInstanceKey,
+ const TUid& aExtendedInterfaceUid);
+
- // See developer documentation for use of FinalClose.
- IMPORT_C static void FinalClose();
+private: // @internalComponent APIs
+ // This API is for internal testing purposes.Should not be used externally by clients.
-private:
-
static REComSession& OpenLC();
void ConstructL();
@@ -239,20 +367,22 @@
void ListImplementationsL(
TInt aServiceId,
TUid aInterfaceUid,
+ const RExtendedInterfacesArray& aExtendedInterfaces,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
- RImplInfoPtrArray& aImplInfoArray);
+ RImplInfoPtrArray& aImplInfoArray,
+ TBool aCapabilityCheck = ETrue);
TAny* ResolveAndCreateImplL(
TUid aImplementationUid,
- TUid& aDtorIDKey,
+ TUid& aInstanceKey,
TAny* aCreationParameters,
TBool aCreationParamsFlag);
TAny* ResolveAndCreateImplL(
TUid aInterfaceUid,
const TEComResolverParams& aResolutionParameters,
- TUid& aDtorIDKey,
+ TUid& aInstanceKey,
TAny* aCreationParameters,
TBool aCreationParamsFlag);
@@ -260,33 +390,62 @@
TUid aInterfaceUid,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
- TUid& aDtorIDKey,
+ TUid& aInstanceKey,
+ TAny* aCreationParameters,
+ TBool aCreationParamsFlag);
+
+ TAny* ResolveAndCreateImplL(
+ TUid aInterfaceUid,
+ const RExtendedInterfacesArray& aExtendedInterfaces,
+ const TEComResolverParams& aResolutionParameters,
+ TUid& aInstanceKey,
TAny* aCreationParameters,
TBool aCreationParamsFlag);
TAny* ResolveAndCreateImplL(
- TInt aServiceId,
- TUid aInterfaceUid,
+ TUid aInterfaceUid,
+ const RExtendedInterfacesArray& aExtendedInterfaces,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
- TUid& aDtorIDKey,
+ TUid& aInstanceKey,
TAny* aCreationParameters,
TBool aCreationParamsFlag);
-public:
- //This API is for internal use only and for testing purposes.
+ 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 */
- TBool iReserved3;
-
+ /** not used */
+ TInt iReserved3;
/** not used */
TInt iReserved2;
};
-
#endif // __ECOM_H__