diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/ecom/ecom.h --- 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 #include @@ -33,29 +37,22 @@ #include -////////////////////////////////////////////////////////////////////////////// -// 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__