|
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 "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // The API definitions required for the use of the ECOM framework by a client |
|
15 // are contained / defined here. |
|
16 // |
|
17 // |
|
18 |
|
19 /** |
|
20 @file |
|
21 @publishedAll |
|
22 @released |
|
23 */ |
|
24 |
|
25 #ifndef __ECOM_H__ |
|
26 #define __ECOM_H__ |
|
27 |
|
28 // ____________________________________________________________________________ |
|
29 // INCLUDES |
|
30 |
|
31 #include <e32base.h> |
|
32 #include <s32std.h> |
|
33 #include <f32file.h> |
|
34 |
|
35 #include <ecom/ecomerrorcodes.h> |
|
36 #include <ecom/ecomresolverparams.h> |
|
37 #include <ecom/implementationinformation.h> |
|
38 |
|
39 |
|
40 // ____________________________________________________________________________ |
|
41 // CONSTANTS |
|
42 |
|
43 class CGlobalData; |
|
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 const TUid KRomOnlyResolverUid = {0x10009D92}; |
|
52 |
|
53 |
|
54 // ____________________________________________________________________________ |
|
55 // CLASSES |
|
56 |
|
57 /** |
|
58 The REComSession singleton class provides an API to identify (resolution), |
|
59 instantiate, and destroy interface class implementations requested by |
|
60 ECOM clients. It manages the session connection to the ECOM Server itself so |
|
61 that typically only one connection is made to the ECOM Server per thread. |
|
62 It provides an un-initialise function where it releases memory and handles |
|
63 of unused plug-ins, see the FinalClose() function. It also ensures that all |
|
64 necessary clean-up is performed in the event of a Leave by any of the |
|
65 ListImplementationsL() or CreateImplementationL() methods. |
|
66 |
|
67 Note: Although a public default constructor is provided in this class |
|
68 it is strongly recommended this object is never created by users of this |
|
69 API on the stack or heap by value. To access the non-static methods of this |
|
70 API use the static OpenL() method to obtain a pointer or a |
|
71 reference to the single reference counted session in use. Close() must be |
|
72 called when finished with. |
|
73 |
|
74 Special care must be taken when using aInstanceKey. It is a 32-bit instance key |
|
75 that is returned from a call to one of the CreateImplementationL() methods. |
|
76 This instance key must only be used with DestroyedImplementation() to identify |
|
77 the implementation instance for destruction, or GetImplementationUidL() to |
|
78 retrieve the Implementation Uid of the instance it refers to. |
|
79 No meaning must be attached to this instance key by ECOM clients |
|
80 and it must not be used for any other purpose. |
|
81 |
|
82 |
|
83 @see REComSession::FinalClose() |
|
84 */ |
|
85 class REComSession : public RSessionBase |
|
86 { |
|
87 friend class CGlobalData; |
|
88 |
|
89 public: // publishedAll APIs |
|
90 // Available for use by all clients |
|
91 |
|
92 IMPORT_C REComSession(); |
|
93 |
|
94 IMPORT_C static REComSession& OpenL(); |
|
95 IMPORT_C void Close(); |
|
96 |
|
97 // Get Implementation Uid from an Instance Key |
|
98 IMPORT_C static TUid GetImplementationUidL( |
|
99 TUid aInstanceKey); |
|
100 |
|
101 // Destroy Implementation API declaration |
|
102 IMPORT_C static void DestroyedImplementation( |
|
103 TUid aInstanceKey); |
|
104 |
|
105 // See developer documentation for use of FinalClose. |
|
106 IMPORT_C static void FinalClose(); |
|
107 |
|
108 |
|
109 // Notification API declarations |
|
110 // |
|
111 |
|
112 IMPORT_C void NotifyOnChange(TRequestStatus& aStatus); |
|
113 IMPORT_C void CancelNotifyOnChange(TRequestStatus& aStatus); |
|
114 |
|
115 |
|
116 // List implementations API declarations |
|
117 // |
|
118 // Use LI1 to list all implementations, unfiltered. |
|
119 // Use LI2 when default resolving required on the returned list. |
|
120 // Use LI3 when custom resolving required on the returned list. |
|
121 |
|
122 // ListImplementationsL - LI1 |
|
123 IMPORT_C static void ListImplementationsL( |
|
124 TUid aInterfaceUid, |
|
125 RImplInfoPtrArray& aImplInfoArray); |
|
126 |
|
127 // ListImplementationsL - LI2 |
|
128 IMPORT_C static void ListImplementationsL( |
|
129 TUid aInterfaceUid, |
|
130 const TEComResolverParams& aResolutionParameters, |
|
131 RImplInfoPtrArray& aImplInfoArray); |
|
132 |
|
133 // ListImplementationsL - LI3 |
|
134 IMPORT_C static void ListImplementationsL( |
|
135 TUid aInterfaceUid, |
|
136 const TEComResolverParams& aResolutionParameters, |
|
137 TUid aResolverUid, |
|
138 RImplInfoPtrArray& aImplInfoArray); |
|
139 |
|
140 // Use LI7 to list all implementations, unfiltered and with no capability chaeck. |
|
141 // Use LI8 when default resolving required on the returned list and with no capability chaeck. |
|
142 // Use LI9 when custom resolving required on the returned list and with no capability chaeck. |
|
143 |
|
144 // ListImplementationsL - LI7 |
|
145 IMPORT_C static void ListImplementationsL( |
|
146 TUid aInterfaceUid, |
|
147 RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck); |
|
148 |
|
149 // ListImplementationsL - LI8 |
|
150 IMPORT_C static void ListImplementationsL( |
|
151 TUid aInterfaceUid, |
|
152 const TEComResolverParams& aResolutionParameters, |
|
153 RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck); |
|
154 |
|
155 // ListImplementationsL - LI9 |
|
156 IMPORT_C static void ListImplementationsL( |
|
157 TUid aInterfaceUid, |
|
158 const TEComResolverParams& aResolutionParameters, |
|
159 TUid aResolverUid, |
|
160 RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck); |
|
161 |
|
162 |
|
163 // Create implementations API declarations |
|
164 // |
|
165 // When Implementation UID is known: |
|
166 // Use CI1, CI2. |
|
167 // Use CI3, CI4 when you have construction parameters. |
|
168 // |
|
169 // When the Interface UID is known and default resolving is required: |
|
170 // Use CI5, CI6. |
|
171 // Use CI7, CI8 when you have construction parameters. |
|
172 // |
|
173 // When the Interface UID is known and custom resolving is required: |
|
174 // Use CI9, CI10. |
|
175 // Use CI11, CI12 when you have construction parameters. |
|
176 |
|
177 // CreateImplementationL - CI1 |
|
178 IMPORT_C static TAny* CreateImplementationL( |
|
179 TUid aImplementationUid, |
|
180 TUid& aInstanceKey); |
|
181 |
|
182 // CreateImplementationL - CI2 |
|
183 IMPORT_C static TAny* CreateImplementationL( |
|
184 TUid aImplementationUid, |
|
185 TInt32 aKeyOffset); |
|
186 |
|
187 // CreateImplementationL - CI3 |
|
188 IMPORT_C static TAny* CreateImplementationL( |
|
189 TUid aImplementationUid, |
|
190 TUid& aInstanceKey, |
|
191 TAny* aConstructionParameters); |
|
192 |
|
193 // CreateImplementationL - CI4 |
|
194 IMPORT_C static TAny* CreateImplementationL( |
|
195 TUid aImplementationUid, |
|
196 TInt32 aKeyOffset, |
|
197 TAny* aConstructionParameters); |
|
198 |
|
199 // CreateImplementationL - CI5 |
|
200 IMPORT_C static TAny* CreateImplementationL( |
|
201 TUid aInterfaceUid, |
|
202 TUid& aInstanceKey, |
|
203 const TEComResolverParams& aResolutionParameters); |
|
204 |
|
205 // CreateImplementationL - CI6 |
|
206 IMPORT_C static TAny* CreateImplementationL( |
|
207 TUid aInterfaceUid, |
|
208 TInt32 aKeyOffset, |
|
209 const TEComResolverParams& aResolutionParameters); |
|
210 |
|
211 // CreateImplementationL - CI7 |
|
212 IMPORT_C static TAny* CreateImplementationL( |
|
213 TUid aInterfaceUid, |
|
214 TUid& aInstanceKey, |
|
215 TAny* aConstructionParameters, |
|
216 const TEComResolverParams& aResolutionParameters); |
|
217 |
|
218 // CreateImplementationL - CI8 |
|
219 IMPORT_C static TAny* CreateImplementationL( |
|
220 TUid aInterfaceUid, |
|
221 TInt32 aKeyOffset, |
|
222 TAny* aConstructionParameters, |
|
223 const TEComResolverParams& aResolutionParameters); |
|
224 |
|
225 // CreateImplementationL - CI9 |
|
226 IMPORT_C static TAny* CreateImplementationL( |
|
227 TUid aInterfaceUid, |
|
228 TUid& aInstanceKey, |
|
229 const TEComResolverParams& aResolutionParameters, |
|
230 TUid aResolverUid); |
|
231 |
|
232 // CreateImplementationL - CI10 |
|
233 IMPORT_C static TAny* CreateImplementationL( |
|
234 TUid aInterfaceUid, |
|
235 TInt32 aKeyOffset, |
|
236 const TEComResolverParams& aResolutionParameters, |
|
237 TUid aResolverUid); |
|
238 |
|
239 // CreateImplementationL - CI11 |
|
240 IMPORT_C static TAny* CreateImplementationL( |
|
241 TUid aInterfaceUid, |
|
242 TUid& aInstanceKey, |
|
243 TAny* aConstructionParameters, |
|
244 const TEComResolverParams& aResolutionParameters, |
|
245 TUid aResolverUid); |
|
246 |
|
247 // CreateImplementationL - CI12 |
|
248 IMPORT_C static TAny* CreateImplementationL( |
|
249 TUid aInterfaceUid, |
|
250 TInt32 aKeyOffset, |
|
251 TAny* aConstructionParameters, |
|
252 const TEComResolverParams& aResolutionParameters, |
|
253 TUid aResolverUid); |
|
254 |
|
255 |
|
256 public: // publishedPartner APIs |
|
257 // Extended interfaces API declarations available for use by |
|
258 // all system software i.e by phone manufacturers and internally (i.e. not supported for use by 3rd parties) |
|
259 // See Symbian OS Developer Library and ECOM How To/FAQ documentation. |
|
260 |
|
261 |
|
262 // List implementations API declarations |
|
263 // |
|
264 // Use L14 to list all implementations which satisfy interface, extended |
|
265 // interfaces |
|
266 // Use L15 to list all implementations which satisfy interface, extended |
|
267 // interfaces when default resolving required on the list returned |
|
268 // Use L16 to list all implementations which satisfy interface, extended |
|
269 // interfaces when custom resolving required on the list returned |
|
270 |
|
271 // ListImplementationsL - LI4 |
|
272 IMPORT_C static void ListImplementationsL( |
|
273 TUid aInterfaceUid, |
|
274 RExtendedInterfacesArray& aExtendedInterfaces, |
|
275 RImplInfoPtrArray& aImplInfoArray); |
|
276 |
|
277 // ListImplementationsL - LI5 |
|
278 IMPORT_C static void ListImplementationsL( |
|
279 TUid aInterfaceUid, |
|
280 RExtendedInterfacesArray& aExtendedInterfaces, |
|
281 const TEComResolverParams& aResolutionParameters, |
|
282 RImplInfoPtrArray& aImplInfoArray); |
|
283 |
|
284 // ListImplementationsL - LI6 |
|
285 IMPORT_C static void ListImplementationsL( |
|
286 TUid aInterfaceUid, |
|
287 RExtendedInterfacesArray& aExtendedInterfaces, |
|
288 const TEComResolverParams& aResolutionParameters, |
|
289 TUid aResolverUid, |
|
290 RImplInfoPtrArray& aImplInfoArray); |
|
291 |
|
292 |
|
293 // Create implementations API declarations |
|
294 // |
|
295 // When the interface UID and the extended interface UID's are known |
|
296 // and default resolving is required. The construction parameters may |
|
297 // optionally be provided. |
|
298 // Use CI13: Instance key is returned |
|
299 // Use CI14: An offset to aInstanceKey returned by the ECom framework |
|
300 // to identify this instance to the framework |
|
301 // When the interface UID and the extended interface UID's are known |
|
302 // and custom resolving is required. The construction parameters may |
|
303 // optionally be provided. |
|
304 // Use CI15: Instance key is returned |
|
305 // Use CI16: An offset to aInstanceKey returned by the ECom framework |
|
306 // to identify this instance to the framework |
|
307 |
|
308 // CreateImplementationL - CI13 |
|
309 IMPORT_C static TAny* CreateImplementationL( |
|
310 TUid aInterfaceUid, |
|
311 const RExtendedInterfacesArray& aExtendedInterfaces, |
|
312 TUid& aInstanceKey, |
|
313 const TEComResolverParams& aResolutionParameters, |
|
314 TAny* aConstructionParameters = NULL); |
|
315 |
|
316 // CreateImplementationL - CI14 |
|
317 IMPORT_C static TAny* CreateImplementationL( |
|
318 TUid aInterfaceUid, |
|
319 const RExtendedInterfacesArray& aExtendedInterfaces, |
|
320 TInt32 aKeyOffset, |
|
321 const TEComResolverParams& aResolutionParameters, |
|
322 TAny* aConstructionParameters = NULL); |
|
323 |
|
324 // CreateImplementationL - CI15 |
|
325 IMPORT_C static TAny* CreateImplementationL( |
|
326 TUid aInterfaceUid, |
|
327 const RExtendedInterfacesArray& aExtendedInterfaces, |
|
328 TUid& aInstanceKey, |
|
329 const TEComResolverParams& aResolutionParameters, |
|
330 TUid aResolverUid, |
|
331 TAny* aConstructionParameters = NULL); |
|
332 |
|
333 // CreateImplementationL - CI16 |
|
334 IMPORT_C static TAny* CreateImplementationL( |
|
335 TUid aInterfaceUid, |
|
336 const RExtendedInterfacesArray& aExtendedInterfaces, |
|
337 TInt32 aKeyOffset, |
|
338 const TEComResolverParams& aResolutionParameters, |
|
339 TUid aResolverUid, |
|
340 TAny* aConstructionParameters = NULL); |
|
341 |
|
342 |
|
343 // Extended Interface query and management API declarations |
|
344 // |
|
345 |
|
346 IMPORT_C static TAny* GetExtendedInterfaceL( |
|
347 const TUid& aInstanceKey, |
|
348 const TUid& aExtendedInterfaceUid); |
|
349 |
|
350 IMPORT_C static void ListExtendedInterfacesL( |
|
351 const TUid& aImplementationUid, |
|
352 RExtendedInterfacesArray& aIfInfo); |
|
353 |
|
354 IMPORT_C static void ManuallyReleaseExtendedInterfaceL( |
|
355 const TUid& aInstanceKey, |
|
356 const TUid& aExtendedInterfaceUid); |
|
357 |
|
358 |
|
359 private: // @internalComponent APIs |
|
360 // This API is for internal testing purposes.Should not be used externally by clients. |
|
361 |
|
362 static REComSession& OpenLC(); |
|
363 |
|
364 void ConstructL(); |
|
365 void ReallyClose(); |
|
366 |
|
367 void ListImplementationsL( |
|
368 TInt aServiceId, |
|
369 TUid aInterfaceUid, |
|
370 const RExtendedInterfacesArray& aExtendedInterfaces, |
|
371 const TEComResolverParams& aResolutionParameters, |
|
372 TUid aResolverUid, |
|
373 RImplInfoPtrArray& aImplInfoArray, |
|
374 TBool aCapabilityCheck = ETrue); |
|
375 |
|
376 TAny* ResolveAndCreateImplL( |
|
377 TUid aImplementationUid, |
|
378 TUid& aInstanceKey, |
|
379 TAny* aCreationParameters, |
|
380 TBool aCreationParamsFlag); |
|
381 |
|
382 TAny* ResolveAndCreateImplL( |
|
383 TUid aInterfaceUid, |
|
384 const TEComResolverParams& aResolutionParameters, |
|
385 TUid& aInstanceKey, |
|
386 TAny* aCreationParameters, |
|
387 TBool aCreationParamsFlag); |
|
388 |
|
389 TAny* ResolveAndCreateImplL( |
|
390 TUid aInterfaceUid, |
|
391 const TEComResolverParams& aResolutionParameters, |
|
392 TUid aResolverUid, |
|
393 TUid& aInstanceKey, |
|
394 TAny* aCreationParameters, |
|
395 TBool aCreationParamsFlag); |
|
396 |
|
397 TAny* ResolveAndCreateImplL( |
|
398 TUid aInterfaceUid, |
|
399 const RExtendedInterfacesArray& aExtendedInterfaces, |
|
400 const TEComResolverParams& aResolutionParameters, |
|
401 TUid& aInstanceKey, |
|
402 TAny* aCreationParameters, |
|
403 TBool aCreationParamsFlag); |
|
404 |
|
405 TAny* ResolveAndCreateImplL( |
|
406 TUid aInterfaceUid, |
|
407 const RExtendedInterfacesArray& aExtendedInterfaces, |
|
408 const TEComResolverParams& aResolutionParameters, |
|
409 TUid aResolverUid, |
|
410 TUid& aInstanceKey, |
|
411 TAny* aCreationParameters, |
|
412 TBool aCreationParamsFlag); |
|
413 |
|
414 TAny* ResolveAndCreateImplL( |
|
415 TInt aServiceId, |
|
416 TUid aInterfaceUid, |
|
417 const RExtendedInterfacesArray& aExtendedInterfaces, |
|
418 const TEComResolverParams& aResolutionParameters, |
|
419 TUid aResolverUid, |
|
420 TUid& aInstanceKey, |
|
421 TAny* aCreationParameters, |
|
422 TBool aCreationParamsFlag); |
|
423 |
|
424 void ProcessListExtendedInterfacesL( |
|
425 const TUid& aImplementationUid, |
|
426 RExtendedInterfacesArray& aIfInfo); |
|
427 |
|
428 void PackMatchStrAndExtendedInterfacesL( |
|
429 const TEComResolverParams& aResolutionParameters, |
|
430 const RExtendedInterfacesArray& aExtendedInterfaces, |
|
431 RBuf8& aMatchStrExtInfBuf); |
|
432 |
|
433 |
|
434 public: // @internalComponent APIs |
|
435 // Internal methods used inside ECOM, not for client use. |
|
436 |
|
437 // This API is for internal testing purposes. |
|
438 IMPORT_C static void SetGetParametersL(const TIpcArgs &aArgs); |
|
439 |
|
440 |
|
441 private: |
|
442 /** Not used */ |
|
443 TInt iReserved1; |
|
444 |
|
445 /** not used */ |
|
446 TInt iReserved3; |
|
447 /** not used */ |
|
448 TInt iReserved2; |
|
449 }; |
|
450 |
|
451 #endif // __ECOM_H__ |