1 // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // 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
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // The definitions required for the use
15 // of the ECOM framework by a client are contained / defined here.
24 //////////////////////////////////////////////////////////////////////////////
31 #include <ecom/ecomerrorcodes.h>
32 #include <ecom/ecomresolverparams.h>
33 #include <ecom/implementationinformation.h>
36 //////////////////////////////////////////////////////////////////////////////
37 // Forward declarations
42 //////////////////////////////////////////////////////////////////////////////
46 The UID identifying the ROM-Only CResolver Interface Implementation.
47 This resolver only returns implementations present on R/O internal media
48 (built-in) or upgrades of such implementations on R/W media. It does not
49 return implementations that solely reside on R/W media.
54 const TUid KRomOnlyResolverUid = {0x10009D92};
57 //////////////////////////////////////////////////////////////////////////////
61 The REComSession singleton class provides an API to identify (resolution),
62 instantiate, and destroy interface class implementations requested by
63 ECOM clients. It manages the session connection to the ECOM Server itself so
64 that typically only one connection is made to the ECOM Server per thread.
65 It provides an un-initialise function where it releases memory and handles
66 of unused plug-ins, see the FinalClose() function. It also ensures that all
67 necessary clean-up is performed in the event of a Leave by any of the
68 ListImplementationsL() or CreateImplementationL() methods.
70 Note: Although a public default constructor is provided in this class
71 it is strongly recommended this object is never created by users of this
72 API on the stack or heap by value. To access the non-static methods of this
73 API use the static OpenL() method to obtain a pointer or a
74 reference to the single reference counted session in use. Close() must be
75 called when finished with.
77 Special care must be taken when using aDtorIDKey. It is a 32-bit instance key
78 that is returned from a call to one of the CreateImplementationL() methods.
79 This instance key must only be used with DestroyedImplementation() to identify
80 the implementation instance for destruction, or GetImplementationUidL() to
81 retrieve the Implementation Uid of the instance it refers to.
82 No meaning must be attached to this instance key by ECOM clients
83 and it must not be used for any other purpose.
86 @see REComSession::FinalClose()
90 class REComSession : public RSessionBase
92 friend class CGlobalData;
95 IMPORT_C REComSession();
96 IMPORT_C static REComSession& OpenL();
97 IMPORT_C void Close();
99 // Notification API declarations
101 IMPORT_C void NotifyOnChange(TRequestStatus& aStatus);
102 IMPORT_C void CancelNotifyOnChange(TRequestStatus& aStatus);
104 // List implementations API declarations
106 // Use LI1 to list all implementations, unfiltered.
107 // Use LI2 when default resolving required on the returned list.
108 // Use LI3 when custom resolving required on the returned list.
110 // ListImplementationsL - LI1
111 IMPORT_C static void ListImplementationsL(
113 RImplInfoPtrArray& aImplInfoArray);
115 // ListImplementationsL - LI2
116 IMPORT_C static void ListImplementationsL(
118 const TEComResolverParams& aResolutionParameters,
119 RImplInfoPtrArray& aImplInfoArray);
121 // ListImplementationsL - LI3
122 IMPORT_C static void ListImplementationsL(
124 const TEComResolverParams& aResolutionParameters,
126 RImplInfoPtrArray& aImplInfoArray);
128 // Create implementations API declarations
130 // When Implementation UID is known:
132 // Use CI3, CI4 when you have construction parameters.
134 // When the Interface UID is known and default resolving is required:
136 // Use CI7, CI8 when you have construction parameters.
138 // When the Interface UID is known and custom resolving is required:
140 // Use CI11, CI12 when you have construction parameters.
142 // CreateImplementationL - CI1
143 IMPORT_C static TAny* CreateImplementationL(
144 TUid aImplementationUid,
147 // CreateImplementationL - CI2
148 IMPORT_C static TAny* CreateImplementationL(
149 TUid aImplementationUid,
152 // CreateImplementationL - CI3
153 IMPORT_C static TAny* CreateImplementationL(
154 TUid aImplementationUid,
156 TAny* aConstructionParameters);
158 // CreateImplementationL - CI4
159 IMPORT_C static TAny* CreateImplementationL(
160 TUid aImplementationUid,
162 TAny* aConstructionParameters);
164 // CreateImplementationL - CI5
165 IMPORT_C static TAny* CreateImplementationL(
168 const TEComResolverParams& aResolutionParameters);
170 // CreateImplementationL - CI6
171 IMPORT_C static TAny* CreateImplementationL(
174 const TEComResolverParams& aResolutionParameters);
176 // CreateImplementationL - CI7
177 IMPORT_C static TAny* CreateImplementationL(
180 TAny* aConstructionParameters,
181 const TEComResolverParams& aResolutionParameters);
183 // CreateImplementationL - CI8
184 IMPORT_C static TAny* CreateImplementationL(
187 TAny* aConstructionParameters,
188 const TEComResolverParams& aResolutionParameters);
190 // CreateImplementationL - CI9
191 IMPORT_C static TAny* CreateImplementationL(
194 const TEComResolverParams& aResolutionParameters,
197 // CreateImplementationL - CI10
198 IMPORT_C static TAny* CreateImplementationL(
201 const TEComResolverParams& aResolutionParameters,
204 // CreateImplementationL - CI11
205 IMPORT_C static TAny* CreateImplementationL(
208 TAny* aConstructionParameters,
209 const TEComResolverParams& aResolutionParameters,
212 // CreateImplementationL - CI12
213 IMPORT_C static TAny* CreateImplementationL(
216 TAny* aConstructionParameters,
217 const TEComResolverParams& aResolutionParameters,
220 // Get Implementation Uid from a Destructor Id Key
221 IMPORT_C static TUid GetImplementationUidL(
224 // Destroy Implementation API declaration
225 IMPORT_C static void DestroyedImplementation(
229 // See developer documentation for use of FinalClose.
230 IMPORT_C static void FinalClose();
234 static REComSession& OpenLC();
239 void ListImplementationsL(
242 const TEComResolverParams& aResolutionParameters,
244 RImplInfoPtrArray& aImplInfoArray);
246 TAny* ResolveAndCreateImplL(
247 TUid aImplementationUid,
249 TAny* aCreationParameters,
250 TBool aCreationParamsFlag);
252 TAny* ResolveAndCreateImplL(
254 const TEComResolverParams& aResolutionParameters,
256 TAny* aCreationParameters,
257 TBool aCreationParamsFlag);
259 TAny* ResolveAndCreateImplL(
261 const TEComResolverParams& aResolutionParameters,
264 TAny* aCreationParameters,
265 TBool aCreationParamsFlag);
267 TAny* ResolveAndCreateImplL(
270 const TEComResolverParams& aResolutionParameters,
273 TAny* aCreationParameters,
274 TBool aCreationParamsFlag);
277 //This API is for internal use only and for testing purposes.
278 IMPORT_C static void SetGetParametersL(const TIpcArgs &aArgs);