epoc32/include/ecom/ecom.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100 (2010-03-31)
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     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__