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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // The API definitions required for the use of the ECOM framework by a client
15 // are contained / defined here.
28 // ____________________________________________________________________________
35 #include <ecom/ecomerrorcodes.h>
36 #include <ecom/ecomresolverparams.h>
37 #include <ecom/implementationinformation.h>
40 // ____________________________________________________________________________
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.
51 const TUid KRomOnlyResolverUid = {0x10009D92};
54 // ____________________________________________________________________________
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.
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.
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.
83 @see REComSession::FinalClose()
85 class REComSession : public RSessionBase
87 friend class CGlobalData;
89 public: // publishedAll APIs
90 // Available for use by all clients
92 IMPORT_C REComSession();
94 IMPORT_C static REComSession& OpenL();
95 IMPORT_C void Close();
97 // Get Implementation Uid from an Instance Key
98 IMPORT_C static TUid GetImplementationUidL(
101 // Destroy Implementation API declaration
102 IMPORT_C static void DestroyedImplementation(
105 // See developer documentation for use of FinalClose.
106 IMPORT_C static void FinalClose();
109 // Notification API declarations
112 IMPORT_C void NotifyOnChange(TRequestStatus& aStatus);
113 IMPORT_C void CancelNotifyOnChange(TRequestStatus& aStatus);
116 // List implementations API declarations
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.
122 // ListImplementationsL - LI1
123 IMPORT_C static void ListImplementationsL(
125 RImplInfoPtrArray& aImplInfoArray);
127 // ListImplementationsL - LI2
128 IMPORT_C static void ListImplementationsL(
130 const TEComResolverParams& aResolutionParameters,
131 RImplInfoPtrArray& aImplInfoArray);
133 // ListImplementationsL - LI3
134 IMPORT_C static void ListImplementationsL(
136 const TEComResolverParams& aResolutionParameters,
138 RImplInfoPtrArray& aImplInfoArray);
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.
144 // ListImplementationsL - LI7
145 IMPORT_C static void ListImplementationsL(
147 RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck);
149 // ListImplementationsL - LI8
150 IMPORT_C static void ListImplementationsL(
152 const TEComResolverParams& aResolutionParameters,
153 RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck);
155 // ListImplementationsL - LI9
156 IMPORT_C static void ListImplementationsL(
158 const TEComResolverParams& aResolutionParameters,
160 RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck);
163 // Create implementations API declarations
165 // When Implementation UID is known:
167 // Use CI3, CI4 when you have construction parameters.
169 // When the Interface UID is known and default resolving is required:
171 // Use CI7, CI8 when you have construction parameters.
173 // When the Interface UID is known and custom resolving is required:
175 // Use CI11, CI12 when you have construction parameters.
177 // CreateImplementationL - CI1
178 IMPORT_C static TAny* CreateImplementationL(
179 TUid aImplementationUid,
182 // CreateImplementationL - CI2
183 IMPORT_C static TAny* CreateImplementationL(
184 TUid aImplementationUid,
187 // CreateImplementationL - CI3
188 IMPORT_C static TAny* CreateImplementationL(
189 TUid aImplementationUid,
191 TAny* aConstructionParameters);
193 // CreateImplementationL - CI4
194 IMPORT_C static TAny* CreateImplementationL(
195 TUid aImplementationUid,
197 TAny* aConstructionParameters);
199 // CreateImplementationL - CI5
200 IMPORT_C static TAny* CreateImplementationL(
203 const TEComResolverParams& aResolutionParameters);
205 // CreateImplementationL - CI6
206 IMPORT_C static TAny* CreateImplementationL(
209 const TEComResolverParams& aResolutionParameters);
211 // CreateImplementationL - CI7
212 IMPORT_C static TAny* CreateImplementationL(
215 TAny* aConstructionParameters,
216 const TEComResolverParams& aResolutionParameters);
218 // CreateImplementationL - CI8
219 IMPORT_C static TAny* CreateImplementationL(
222 TAny* aConstructionParameters,
223 const TEComResolverParams& aResolutionParameters);
225 // CreateImplementationL - CI9
226 IMPORT_C static TAny* CreateImplementationL(
229 const TEComResolverParams& aResolutionParameters,
232 // CreateImplementationL - CI10
233 IMPORT_C static TAny* CreateImplementationL(
236 const TEComResolverParams& aResolutionParameters,
239 // CreateImplementationL - CI11
240 IMPORT_C static TAny* CreateImplementationL(
243 TAny* aConstructionParameters,
244 const TEComResolverParams& aResolutionParameters,
247 // CreateImplementationL - CI12
248 IMPORT_C static TAny* CreateImplementationL(
251 TAny* aConstructionParameters,
252 const TEComResolverParams& aResolutionParameters,
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.
262 // List implementations API declarations
264 // Use L14 to list all implementations which satisfy interface, extended
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
271 // ListImplementationsL - LI4
272 IMPORT_C static void ListImplementationsL(
274 RExtendedInterfacesArray& aExtendedInterfaces,
275 RImplInfoPtrArray& aImplInfoArray);
277 // ListImplementationsL - LI5
278 IMPORT_C static void ListImplementationsL(
280 RExtendedInterfacesArray& aExtendedInterfaces,
281 const TEComResolverParams& aResolutionParameters,
282 RImplInfoPtrArray& aImplInfoArray);
284 // ListImplementationsL - LI6
285 IMPORT_C static void ListImplementationsL(
287 RExtendedInterfacesArray& aExtendedInterfaces,
288 const TEComResolverParams& aResolutionParameters,
290 RImplInfoPtrArray& aImplInfoArray);
293 // Create implementations API declarations
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
308 // CreateImplementationL - CI13
309 IMPORT_C static TAny* CreateImplementationL(
311 const RExtendedInterfacesArray& aExtendedInterfaces,
313 const TEComResolverParams& aResolutionParameters,
314 TAny* aConstructionParameters = NULL);
316 // CreateImplementationL - CI14
317 IMPORT_C static TAny* CreateImplementationL(
319 const RExtendedInterfacesArray& aExtendedInterfaces,
321 const TEComResolverParams& aResolutionParameters,
322 TAny* aConstructionParameters = NULL);
324 // CreateImplementationL - CI15
325 IMPORT_C static TAny* CreateImplementationL(
327 const RExtendedInterfacesArray& aExtendedInterfaces,
329 const TEComResolverParams& aResolutionParameters,
331 TAny* aConstructionParameters = NULL);
333 // CreateImplementationL - CI16
334 IMPORT_C static TAny* CreateImplementationL(
336 const RExtendedInterfacesArray& aExtendedInterfaces,
338 const TEComResolverParams& aResolutionParameters,
340 TAny* aConstructionParameters = NULL);
343 // Extended Interface query and management API declarations
346 IMPORT_C static TAny* GetExtendedInterfaceL(
347 const TUid& aInstanceKey,
348 const TUid& aExtendedInterfaceUid);
350 IMPORT_C static void ListExtendedInterfacesL(
351 const TUid& aImplementationUid,
352 RExtendedInterfacesArray& aIfInfo);
354 IMPORT_C static void ManuallyReleaseExtendedInterfaceL(
355 const TUid& aInstanceKey,
356 const TUid& aExtendedInterfaceUid);
359 private: // @internalComponent APIs
360 // This API is for internal testing purposes.Should not be used externally by clients.
362 static REComSession& OpenLC();
367 void ListImplementationsL(
370 const RExtendedInterfacesArray& aExtendedInterfaces,
371 const TEComResolverParams& aResolutionParameters,
373 RImplInfoPtrArray& aImplInfoArray,
374 TBool aCapabilityCheck = ETrue);
376 TAny* ResolveAndCreateImplL(
377 TUid aImplementationUid,
379 TAny* aCreationParameters,
380 TBool aCreationParamsFlag);
382 TAny* ResolveAndCreateImplL(
384 const TEComResolverParams& aResolutionParameters,
386 TAny* aCreationParameters,
387 TBool aCreationParamsFlag);
389 TAny* ResolveAndCreateImplL(
391 const TEComResolverParams& aResolutionParameters,
394 TAny* aCreationParameters,
395 TBool aCreationParamsFlag);
397 TAny* ResolveAndCreateImplL(
399 const RExtendedInterfacesArray& aExtendedInterfaces,
400 const TEComResolverParams& aResolutionParameters,
402 TAny* aCreationParameters,
403 TBool aCreationParamsFlag);
405 TAny* ResolveAndCreateImplL(
407 const RExtendedInterfacesArray& aExtendedInterfaces,
408 const TEComResolverParams& aResolutionParameters,
411 TAny* aCreationParameters,
412 TBool aCreationParamsFlag);
414 TAny* ResolveAndCreateImplL(
417 const RExtendedInterfacesArray& aExtendedInterfaces,
418 const TEComResolverParams& aResolutionParameters,
421 TAny* aCreationParameters,
422 TBool aCreationParamsFlag);
424 void ProcessListExtendedInterfacesL(
425 const TUid& aImplementationUid,
426 RExtendedInterfacesArray& aIfInfo);
428 void PackMatchStrAndExtendedInterfacesL(
429 const TEComResolverParams& aResolutionParameters,
430 const RExtendedInterfacesArray& aExtendedInterfaces,
431 RBuf8& aMatchStrExtInfBuf);
434 public: // @internalComponent APIs
435 // Internal methods used inside ECOM, not for client use.
437 // This API is for internal testing purposes.
438 IMPORT_C static void SetGetParametersL(const TIpcArgs &aArgs);