1 ecom.h |
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". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // The definitions required for the use |
|
15 // of the ECOM framework by a client are contained / defined here. |
|
16 // |
|
17 // |
|
18 |
|
19 |
|
20 |
|
21 #ifndef __ECOM_H__ |
|
22 #define __ECOM_H__ |
|
23 |
|
24 ////////////////////////////////////////////////////////////////////////////// |
|
25 // Include Files |
|
26 |
|
27 #include <e32base.h> |
|
28 #include <s32std.h> |
|
29 #include <f32file.h> |
|
30 |
|
31 #include <ecom/ecomerrorcodes.h> |
|
32 #include <ecom/ecomresolverparams.h> |
|
33 #include <ecom/implementationinformation.h> |
|
34 |
|
35 |
|
36 ////////////////////////////////////////////////////////////////////////////// |
|
37 // Forward declarations |
|
38 |
|
39 class CGlobalData; |
|
40 |
|
41 |
|
42 ////////////////////////////////////////////////////////////////////////////// |
|
43 // Global Constants |
|
44 |
|
45 /** |
|
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. |
|
50 |
|
51 @publishedAll |
|
52 @released |
|
53 */ |
|
54 const TUid KRomOnlyResolverUid = {0x10009D92}; |
|
55 |
|
56 |
|
57 ////////////////////////////////////////////////////////////////////////////// |
|
58 // REComSession class |
|
59 |
|
60 /** |
|
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. |
|
69 |
|
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. |
|
76 |
|
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. |
|
84 |
|
85 |
|
86 @see REComSession::FinalClose() |
|
87 @publishedAll |
|
88 @released |
|
89 */ |
|
90 class REComSession : public RSessionBase |
|
91 { |
|
92 friend class CGlobalData; |
|
93 public: |
|
94 |
|
95 IMPORT_C REComSession(); |
|
96 IMPORT_C static REComSession& OpenL(); |
|
97 IMPORT_C void Close(); |
|
98 |
|
99 // Notification API declarations |
|
100 |
|
101 IMPORT_C void NotifyOnChange(TRequestStatus& aStatus); |
|
102 IMPORT_C void CancelNotifyOnChange(TRequestStatus& aStatus); |
|
103 |
|
104 // List implementations API declarations |
|
105 // |
|
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. |
|
109 |
|
110 // ListImplementationsL - LI1 |
|
111 IMPORT_C static void ListImplementationsL( |
|
112 TUid aInterfaceUid, |
|
113 RImplInfoPtrArray& aImplInfoArray); |
|
114 |
|
115 // ListImplementationsL - LI2 |
|
116 IMPORT_C static void ListImplementationsL( |
|
117 TUid aInterfaceUid, |
|
118 const TEComResolverParams& aResolutionParameters, |
|
119 RImplInfoPtrArray& aImplInfoArray); |
|
120 |
|
121 // ListImplementationsL - LI3 |
|
122 IMPORT_C static void ListImplementationsL( |
|
123 TUid aInterfaceUid, |
|
124 const TEComResolverParams& aResolutionParameters, |
|
125 TUid aResolverUid, |
|
126 RImplInfoPtrArray& aImplInfoArray); |
|
127 |
|
128 // Create implementations API declarations |
|
129 // |
|
130 // When Implementation UID is known: |
|
131 // Use CI1, CI2. |
|
132 // Use CI3, CI4 when you have construction parameters. |
|
133 // |
|
134 // When the Interface UID is known and default resolving is required: |
|
135 // Use CI5, CI6. |
|
136 // Use CI7, CI8 when you have construction parameters. |
|
137 // |
|
138 // When the Interface UID is known and custom resolving is required: |
|
139 // Use CI9, CI10. |
|
140 // Use CI11, CI12 when you have construction parameters. |
|
141 |
|
142 // CreateImplementationL - CI1 |
|
143 IMPORT_C static TAny* CreateImplementationL( |
|
144 TUid aImplementationUid, |
|
145 TUid& aDtorIDKey); |
|
146 |
|
147 // CreateImplementationL - CI2 |
|
148 IMPORT_C static TAny* CreateImplementationL( |
|
149 TUid aImplementationUid, |
|
150 TInt32 aKeyOffset); |
|
151 |
|
152 // CreateImplementationL - CI3 |
|
153 IMPORT_C static TAny* CreateImplementationL( |
|
154 TUid aImplementationUid, |
|
155 TUid& aDtorIDKey, |
|
156 TAny* aConstructionParameters); |
|
157 |
|
158 // CreateImplementationL - CI4 |
|
159 IMPORT_C static TAny* CreateImplementationL( |
|
160 TUid aImplementationUid, |
|
161 TInt32 aKeyOffset, |
|
162 TAny* aConstructionParameters); |
|
163 |
|
164 // CreateImplementationL - CI5 |
|
165 IMPORT_C static TAny* CreateImplementationL( |
|
166 TUid aInterfaceUid, |
|
167 TUid& aDtorIDKey, |
|
168 const TEComResolverParams& aResolutionParameters); |
|
169 |
|
170 // CreateImplementationL - CI6 |
|
171 IMPORT_C static TAny* CreateImplementationL( |
|
172 TUid aInterfaceUid, |
|
173 TInt32 aKeyOffset, |
|
174 const TEComResolverParams& aResolutionParameters); |
|
175 |
|
176 // CreateImplementationL - CI7 |
|
177 IMPORT_C static TAny* CreateImplementationL( |
|
178 TUid aInterfaceUid, |
|
179 TUid& aDtorIDKey, |
|
180 TAny* aConstructionParameters, |
|
181 const TEComResolverParams& aResolutionParameters); |
|
182 |
|
183 // CreateImplementationL - CI8 |
|
184 IMPORT_C static TAny* CreateImplementationL( |
|
185 TUid aInterfaceUid, |
|
186 TInt32 aKeyOffset, |
|
187 TAny* aConstructionParameters, |
|
188 const TEComResolverParams& aResolutionParameters); |
|
189 |
|
190 // CreateImplementationL - CI9 |
|
191 IMPORT_C static TAny* CreateImplementationL( |
|
192 TUid aInterfaceUid, |
|
193 TUid& aDtorIDKey, |
|
194 const TEComResolverParams& aResolutionParameters, |
|
195 TUid aResolverUid); |
|
196 |
|
197 // CreateImplementationL - CI10 |
|
198 IMPORT_C static TAny* CreateImplementationL( |
|
199 TUid aInterfaceUid, |
|
200 TInt32 aKeyOffset, |
|
201 const TEComResolverParams& aResolutionParameters, |
|
202 TUid aResolverUid); |
|
203 |
|
204 // CreateImplementationL - CI11 |
|
205 IMPORT_C static TAny* CreateImplementationL( |
|
206 TUid aInterfaceUid, |
|
207 TUid& aDtorIDKey, |
|
208 TAny* aConstructionParameters, |
|
209 const TEComResolverParams& aResolutionParameters, |
|
210 TUid aResolverUid); |
|
211 |
|
212 // CreateImplementationL - CI12 |
|
213 IMPORT_C static TAny* CreateImplementationL( |
|
214 TUid aInterfaceUid, |
|
215 TInt32 aKeyOffset, |
|
216 TAny* aConstructionParameters, |
|
217 const TEComResolverParams& aResolutionParameters, |
|
218 TUid aResolverUid); |
|
219 |
|
220 // Get Implementation Uid from a Destructor Id Key |
|
221 IMPORT_C static TUid GetImplementationUidL( |
|
222 TUid aDtorIDKey); |
|
223 |
|
224 // Destroy Implementation API declaration |
|
225 IMPORT_C static void DestroyedImplementation( |
|
226 TUid aDtorIDKey); |
|
227 |
|
228 |
|
229 // See developer documentation for use of FinalClose. |
|
230 IMPORT_C static void FinalClose(); |
|
231 |
|
232 private: |
|
233 |
|
234 static REComSession& OpenLC(); |
|
235 |
|
236 void ConstructL(); |
|
237 void ReallyClose(); |
|
238 |
|
239 void ListImplementationsL( |
|
240 TInt aServiceId, |
|
241 TUid aInterfaceUid, |
|
242 const TEComResolverParams& aResolutionParameters, |
|
243 TUid aResolverUid, |
|
244 RImplInfoPtrArray& aImplInfoArray); |
|
245 |
|
246 TAny* ResolveAndCreateImplL( |
|
247 TUid aImplementationUid, |
|
248 TUid& aDtorIDKey, |
|
249 TAny* aCreationParameters, |
|
250 TBool aCreationParamsFlag); |
|
251 |
|
252 TAny* ResolveAndCreateImplL( |
|
253 TUid aInterfaceUid, |
|
254 const TEComResolverParams& aResolutionParameters, |
|
255 TUid& aDtorIDKey, |
|
256 TAny* aCreationParameters, |
|
257 TBool aCreationParamsFlag); |
|
258 |
|
259 TAny* ResolveAndCreateImplL( |
|
260 TUid aInterfaceUid, |
|
261 const TEComResolverParams& aResolutionParameters, |
|
262 TUid aResolverUid, |
|
263 TUid& aDtorIDKey, |
|
264 TAny* aCreationParameters, |
|
265 TBool aCreationParamsFlag); |
|
266 |
|
267 TAny* ResolveAndCreateImplL( |
|
268 TInt aServiceId, |
|
269 TUid aInterfaceUid, |
|
270 const TEComResolverParams& aResolutionParameters, |
|
271 TUid aResolverUid, |
|
272 TUid& aDtorIDKey, |
|
273 TAny* aCreationParameters, |
|
274 TBool aCreationParamsFlag); |
|
275 |
|
276 public: |
|
277 //This API is for internal use only and for testing purposes. |
|
278 IMPORT_C static void SetGetParametersL(const TIpcArgs &aArgs); |
|
279 |
|
280 private: |
|
281 /** Not used */ |
|
282 TInt iReserved1; |
|
283 |
|
284 /** Not used */ |
|
285 TBool iReserved3; |
|
286 |
|
287 /** not used */ |
|
288 TInt iReserved2; |
|
289 }; |
|
290 |
|
291 |
|
292 #endif // __ECOM_H__ |