1 // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies). |
1 // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies). |
2 // All rights reserved. |
2 // All rights reserved. |
3 // This component and the accompanying materials are made available |
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 |
4 // under the terms of "Eclipse Public License v1.0" |
5 // which accompanies this distribution, and is available |
5 // which accompanies this distribution, and is available |
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
7 // |
7 // |
8 // Initial Contributors: |
8 // Initial Contributors: |
9 // Nokia Corporation - initial contribution. |
9 // Nokia Corporation - initial contribution. |
10 // |
10 // |
11 // Contributors: |
11 // Contributors: |
12 // |
12 // |
13 // Description: |
13 // Description: |
14 // The definitions required for the use |
14 // The API definitions required for the use of the ECOM framework by a client |
15 // of the ECOM framework by a client are contained / defined here. |
15 // are contained / defined here. |
16 // |
16 // |
17 // |
17 // |
18 |
18 |
19 |
19 /** |
|
20 @file |
|
21 @publishedAll |
|
22 @released |
|
23 */ |
20 |
24 |
21 #ifndef __ECOM_H__ |
25 #ifndef __ECOM_H__ |
22 #define __ECOM_H__ |
26 #define __ECOM_H__ |
23 |
27 |
24 ////////////////////////////////////////////////////////////////////////////// |
28 // ____________________________________________________________________________ |
25 // Include Files |
29 // INCLUDES |
26 |
30 |
27 #include <e32base.h> |
31 #include <e32base.h> |
28 #include <s32std.h> |
32 #include <s32std.h> |
29 #include <f32file.h> |
33 #include <f32file.h> |
30 |
34 |
31 #include <ecom/ecomerrorcodes.h> |
35 #include <ecom/ecomerrorcodes.h> |
32 #include <ecom/ecomresolverparams.h> |
36 #include <ecom/ecomresolverparams.h> |
33 #include <ecom/implementationinformation.h> |
37 #include <ecom/implementationinformation.h> |
34 |
38 |
35 |
39 |
36 ////////////////////////////////////////////////////////////////////////////// |
40 // ____________________________________________________________________________ |
37 // Forward declarations |
41 // CONSTANTS |
38 |
42 |
39 class CGlobalData; |
43 class CGlobalData; |
40 |
|
41 |
|
42 ////////////////////////////////////////////////////////////////////////////// |
|
43 // Global Constants |
|
44 |
44 |
45 /** |
45 /** |
46 The UID identifying the ROM-Only CResolver Interface Implementation. |
46 The UID identifying the ROM-Only CResolver Interface Implementation. |
47 This resolver only returns implementations present on R/O internal media |
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 |
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. |
49 return implementations that solely reside on R/W media. |
50 |
|
51 @publishedAll |
|
52 @released |
|
53 */ |
50 */ |
54 const TUid KRomOnlyResolverUid = {0x10009D92}; |
51 const TUid KRomOnlyResolverUid = {0x10009D92}; |
55 |
52 |
56 |
53 |
57 ////////////////////////////////////////////////////////////////////////////// |
54 // ____________________________________________________________________________ |
58 // REComSession class |
55 // CLASSES |
59 |
56 |
60 /** |
57 /** |
61 The REComSession singleton class provides an API to identify (resolution), |
58 The REComSession singleton class provides an API to identify (resolution), |
62 instantiate, and destroy interface class implementations requested by |
59 instantiate, and destroy interface class implementations requested by |
63 ECOM clients. It manages the session connection to the ECOM Server itself so |
60 ECOM clients. It manages the session connection to the ECOM Server itself so |
72 API on the stack or heap by value. To access the non-static methods of this |
69 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 |
70 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 |
71 reference to the single reference counted session in use. Close() must be |
75 called when finished with. |
72 called when finished with. |
76 |
73 |
77 Special care must be taken when using aDtorIDKey. It is a 32-bit instance key |
74 Special care must be taken when using aInstanceKey. It is a 32-bit instance key |
78 that is returned from a call to one of the CreateImplementationL() methods. |
75 that is returned from a call to one of the CreateImplementationL() methods. |
79 This instance key must only be used with DestroyedImplementation() to identify |
76 This instance key must only be used with DestroyedImplementation() to identify |
80 the implementation instance for destruction, or GetImplementationUidL() to |
77 the implementation instance for destruction, or GetImplementationUidL() to |
81 retrieve the Implementation Uid of the instance it refers to. |
78 retrieve the Implementation Uid of the instance it refers to. |
82 No meaning must be attached to this instance key by ECOM clients |
79 No meaning must be attached to this instance key by ECOM clients |
83 and it must not be used for any other purpose. |
80 and it must not be used for any other purpose. |
84 |
81 |
85 |
82 |
86 @see REComSession::FinalClose() |
83 @see REComSession::FinalClose() |
87 @publishedAll |
|
88 @released |
|
89 */ |
84 */ |
90 class REComSession : public RSessionBase |
85 class REComSession : public RSessionBase |
91 { |
86 { |
92 friend class CGlobalData; |
87 friend class CGlobalData; |
93 public: |
88 |
|
89 public: // publishedAll APIs |
|
90 // Available for use by all clients |
94 |
91 |
95 IMPORT_C REComSession(); |
92 IMPORT_C REComSession(); |
|
93 |
96 IMPORT_C static REComSession& OpenL(); |
94 IMPORT_C static REComSession& OpenL(); |
97 IMPORT_C void Close(); |
95 IMPORT_C void Close(); |
98 |
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 |
99 // Notification API declarations |
109 // Notification API declarations |
|
110 // |
100 |
111 |
101 IMPORT_C void NotifyOnChange(TRequestStatus& aStatus); |
112 IMPORT_C void NotifyOnChange(TRequestStatus& aStatus); |
102 IMPORT_C void CancelNotifyOnChange(TRequestStatus& aStatus); |
113 IMPORT_C void CancelNotifyOnChange(TRequestStatus& aStatus); |
|
114 |
103 |
115 |
104 // List implementations API declarations |
116 // List implementations API declarations |
105 // |
117 // |
106 // Use LI1 to list all implementations, unfiltered. |
118 // Use LI1 to list all implementations, unfiltered. |
107 // Use LI2 when default resolving required on the returned list. |
119 // Use LI2 when default resolving required on the returned list. |
108 // Use LI3 when custom resolving required on the returned list. |
120 // Use LI3 when custom resolving required on the returned list. |
109 |
121 |
110 // ListImplementationsL - LI1 |
122 // ListImplementationsL - LI1 |
111 IMPORT_C static void ListImplementationsL( |
123 IMPORT_C static void ListImplementationsL( |
112 TUid aInterfaceUid, |
124 TUid aInterfaceUid, |
113 RImplInfoPtrArray& aImplInfoArray); |
125 RImplInfoPtrArray& aImplInfoArray); |
114 |
126 |
136 // Use CI7, CI8 when you have construction parameters. |
171 // Use CI7, CI8 when you have construction parameters. |
137 // |
172 // |
138 // When the Interface UID is known and custom resolving is required: |
173 // When the Interface UID is known and custom resolving is required: |
139 // Use CI9, CI10. |
174 // Use CI9, CI10. |
140 // Use CI11, CI12 when you have construction parameters. |
175 // Use CI11, CI12 when you have construction parameters. |
141 |
176 |
142 // CreateImplementationL - CI1 |
177 // CreateImplementationL - CI1 |
143 IMPORT_C static TAny* CreateImplementationL( |
178 IMPORT_C static TAny* CreateImplementationL( |
144 TUid aImplementationUid, |
179 TUid aImplementationUid, |
145 TUid& aDtorIDKey); |
180 TUid& aInstanceKey); |
146 |
181 |
147 // CreateImplementationL - CI2 |
182 // CreateImplementationL - CI2 |
148 IMPORT_C static TAny* CreateImplementationL( |
183 IMPORT_C static TAny* CreateImplementationL( |
149 TUid aImplementationUid, |
184 TUid aImplementationUid, |
150 TInt32 aKeyOffset); |
185 TInt32 aKeyOffset); |
151 |
186 |
152 // CreateImplementationL - CI3 |
187 // CreateImplementationL - CI3 |
153 IMPORT_C static TAny* CreateImplementationL( |
188 IMPORT_C static TAny* CreateImplementationL( |
154 TUid aImplementationUid, |
189 TUid aImplementationUid, |
155 TUid& aDtorIDKey, |
190 TUid& aInstanceKey, |
156 TAny* aConstructionParameters); |
191 TAny* aConstructionParameters); |
157 |
192 |
158 // CreateImplementationL - CI4 |
193 // CreateImplementationL - CI4 |
159 IMPORT_C static TAny* CreateImplementationL( |
194 IMPORT_C static TAny* CreateImplementationL( |
160 TUid aImplementationUid, |
195 TUid aImplementationUid, |
215 TInt32 aKeyOffset, |
250 TInt32 aKeyOffset, |
216 TAny* aConstructionParameters, |
251 TAny* aConstructionParameters, |
217 const TEComResolverParams& aResolutionParameters, |
252 const TEComResolverParams& aResolutionParameters, |
218 TUid aResolverUid); |
253 TUid aResolverUid); |
219 |
254 |
220 // Get Implementation Uid from a Destructor Id Key |
255 |
221 IMPORT_C static TUid GetImplementationUidL( |
256 public: // publishedPartner APIs |
222 TUid aDtorIDKey); |
257 // Extended interfaces API declarations available for use by |
223 |
258 // all system software i.e by phone manufacturers and internally (i.e. not supported for use by 3rd parties) |
224 // Destroy Implementation API declaration |
259 // See Symbian OS Developer Library and ECOM How To/FAQ documentation. |
225 IMPORT_C static void DestroyedImplementation( |
260 |
226 TUid aDtorIDKey); |
261 |
227 |
262 // List implementations API declarations |
228 |
263 // |
229 // See developer documentation for use of FinalClose. |
264 // Use L14 to list all implementations which satisfy interface, extended |
230 IMPORT_C static void FinalClose(); |
265 // interfaces |
231 |
266 // Use L15 to list all implementations which satisfy interface, extended |
232 private: |
267 // interfaces when default resolving required on the list returned |
233 |
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 |
234 static REComSession& OpenLC(); |
362 static REComSession& OpenLC(); |
235 |
363 |
236 void ConstructL(); |
364 void ConstructL(); |
237 void ReallyClose(); |
365 void ReallyClose(); |
238 |
366 |
239 void ListImplementationsL( |
367 void ListImplementationsL( |
240 TInt aServiceId, |
368 TInt aServiceId, |
241 TUid aInterfaceUid, |
369 TUid aInterfaceUid, |
|
370 const RExtendedInterfacesArray& aExtendedInterfaces, |
242 const TEComResolverParams& aResolutionParameters, |
371 const TEComResolverParams& aResolutionParameters, |
243 TUid aResolverUid, |
372 TUid aResolverUid, |
244 RImplInfoPtrArray& aImplInfoArray); |
373 RImplInfoPtrArray& aImplInfoArray, |
|
374 TBool aCapabilityCheck = ETrue); |
245 |
375 |
246 TAny* ResolveAndCreateImplL( |
376 TAny* ResolveAndCreateImplL( |
247 TUid aImplementationUid, |
377 TUid aImplementationUid, |
248 TUid& aDtorIDKey, |
378 TUid& aInstanceKey, |
249 TAny* aCreationParameters, |
379 TAny* aCreationParameters, |
250 TBool aCreationParamsFlag); |
380 TBool aCreationParamsFlag); |
251 |
381 |
252 TAny* ResolveAndCreateImplL( |
382 TAny* ResolveAndCreateImplL( |
253 TUid aInterfaceUid, |
383 TUid aInterfaceUid, |
254 const TEComResolverParams& aResolutionParameters, |
384 const TEComResolverParams& aResolutionParameters, |
255 TUid& aDtorIDKey, |
385 TUid& aInstanceKey, |
256 TAny* aCreationParameters, |
386 TAny* aCreationParameters, |
257 TBool aCreationParamsFlag); |
387 TBool aCreationParamsFlag); |
258 |
388 |
259 TAny* ResolveAndCreateImplL( |
389 TAny* ResolveAndCreateImplL( |
260 TUid aInterfaceUid, |
390 TUid aInterfaceUid, |
261 const TEComResolverParams& aResolutionParameters, |
391 const TEComResolverParams& aResolutionParameters, |
262 TUid aResolverUid, |
392 TUid aResolverUid, |
263 TUid& aDtorIDKey, |
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, |
264 TAny* aCreationParameters, |
402 TAny* aCreationParameters, |
265 TBool aCreationParamsFlag); |
403 TBool aCreationParamsFlag); |
266 |
404 |
267 TAny* ResolveAndCreateImplL( |
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( |
268 TInt aServiceId, |
415 TInt aServiceId, |
269 TUid aInterfaceUid, |
416 TUid aInterfaceUid, |
|
417 const RExtendedInterfacesArray& aExtendedInterfaces, |
270 const TEComResolverParams& aResolutionParameters, |
418 const TEComResolverParams& aResolutionParameters, |
271 TUid aResolverUid, |
419 TUid aResolverUid, |
272 TUid& aDtorIDKey, |
420 TUid& aInstanceKey, |
273 TAny* aCreationParameters, |
421 TAny* aCreationParameters, |
274 TBool aCreationParamsFlag); |
422 TBool aCreationParamsFlag); |
275 |
423 |
276 public: |
424 void ProcessListExtendedInterfacesL( |
277 //This API is for internal use only and for testing purposes. |
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. |
278 IMPORT_C static void SetGetParametersL(const TIpcArgs &aArgs); |
438 IMPORT_C static void SetGetParametersL(const TIpcArgs &aArgs); |
279 |
439 |
|
440 |
280 private: |
441 private: |
281 /** Not used */ |
442 /** Not used */ |
282 TInt iReserved1; |
443 TInt iReserved1; |
283 |
444 |
284 /** Not used */ |
445 /** not used */ |
285 TBool iReserved3; |
446 TInt iReserved3; |
286 |
|
287 /** not used */ |
447 /** not used */ |
288 TInt iReserved2; |
448 TInt iReserved2; |
289 }; |
449 }; |
290 |
450 |
291 |
|
292 #endif // __ECOM_H__ |
451 #endif // __ECOM_H__ |