epoc32/include/ecom/ecom.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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__