1.1 --- a/epoc32/include/ecom/ecom.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/ecom/ecom.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,292 @@
1.4 -ecom.h
1.5 +// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// 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
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +// The definitions required for the use
1.19 +// of the ECOM framework by a client are contained / defined here.
1.20 +//
1.21 +//
1.22 +
1.23 +
1.24 +
1.25 +#ifndef __ECOM_H__
1.26 +#define __ECOM_H__
1.27 +
1.28 +//////////////////////////////////////////////////////////////////////////////
1.29 +// Include Files
1.30 +
1.31 +#include <e32base.h>
1.32 +#include <s32std.h>
1.33 +#include <f32file.h>
1.34 +
1.35 +#include <ecom/ecomerrorcodes.h>
1.36 +#include <ecom/ecomresolverparams.h>
1.37 +#include <ecom/implementationinformation.h>
1.38 +
1.39 +
1.40 +//////////////////////////////////////////////////////////////////////////////
1.41 +// Forward declarations
1.42 +
1.43 +class CGlobalData;
1.44 +
1.45 +
1.46 +//////////////////////////////////////////////////////////////////////////////
1.47 +// Global Constants
1.48 +
1.49 +/**
1.50 +The UID identifying the ROM-Only CResolver Interface Implementation.
1.51 +This resolver only returns implementations present on R/O internal media
1.52 +(built-in) or upgrades of such implementations on R/W media. It does not
1.53 +return implementations that solely reside on R/W media.
1.54 +
1.55 +@publishedAll
1.56 +@released
1.57 +*/
1.58 +const TUid KRomOnlyResolverUid = {0x10009D92};
1.59 +
1.60 +
1.61 +//////////////////////////////////////////////////////////////////////////////
1.62 +// REComSession class
1.63 +
1.64 +/**
1.65 +The REComSession singleton class provides an API to identify (resolution),
1.66 +instantiate, and destroy interface class implementations requested by
1.67 +ECOM clients. It manages the session connection to the ECOM Server itself so
1.68 +that typically only one connection is made to the ECOM Server per thread.
1.69 +It provides an un-initialise function where it releases memory and handles
1.70 +of unused plug-ins, see the FinalClose() function. It also ensures that all
1.71 +necessary clean-up is performed in the event of a Leave by any of the
1.72 +ListImplementationsL() or CreateImplementationL() methods.
1.73 +
1.74 +Note: Although a public default constructor is provided in this class
1.75 +it is strongly recommended this object is never created by users of this
1.76 +API on the stack or heap by value. To access the non-static methods of this
1.77 +API use the static OpenL() method to obtain a pointer or a
1.78 +reference to the single reference counted session in use. Close() must be
1.79 +called when finished with.
1.80 +
1.81 +Special care must be taken when using aDtorIDKey. It is a 32-bit instance key
1.82 +that is returned from a call to one of the CreateImplementationL() methods.
1.83 +This instance key must only be used with DestroyedImplementation() to identify
1.84 +the implementation instance for destruction, or GetImplementationUidL() to
1.85 +retrieve the Implementation Uid of the instance it refers to.
1.86 +No meaning must be attached to this instance key by ECOM clients
1.87 +and it must not be used for any other purpose.
1.88 +
1.89 +
1.90 +@see REComSession::FinalClose()
1.91 +@publishedAll
1.92 +@released
1.93 +*/
1.94 +class REComSession : public RSessionBase
1.95 + {
1.96 + friend class CGlobalData;
1.97 +public:
1.98 +
1.99 + IMPORT_C REComSession();
1.100 + IMPORT_C static REComSession& OpenL();
1.101 + IMPORT_C void Close();
1.102 +
1.103 + // Notification API declarations
1.104 +
1.105 + IMPORT_C void NotifyOnChange(TRequestStatus& aStatus);
1.106 + IMPORT_C void CancelNotifyOnChange(TRequestStatus& aStatus);
1.107 +
1.108 + // List implementations API declarations
1.109 + //
1.110 + // Use LI1 to list all implementations, unfiltered.
1.111 + // Use LI2 when default resolving required on the returned list.
1.112 + // Use LI3 when custom resolving required on the returned list.
1.113 +
1.114 + // ListImplementationsL - LI1
1.115 + IMPORT_C static void ListImplementationsL(
1.116 + TUid aInterfaceUid,
1.117 + RImplInfoPtrArray& aImplInfoArray);
1.118 +
1.119 + // ListImplementationsL - LI2
1.120 + IMPORT_C static void ListImplementationsL(
1.121 + TUid aInterfaceUid,
1.122 + const TEComResolverParams& aResolutionParameters,
1.123 + RImplInfoPtrArray& aImplInfoArray);
1.124 +
1.125 + // ListImplementationsL - LI3
1.126 + IMPORT_C static void ListImplementationsL(
1.127 + TUid aInterfaceUid,
1.128 + const TEComResolverParams& aResolutionParameters,
1.129 + TUid aResolverUid,
1.130 + RImplInfoPtrArray& aImplInfoArray);
1.131 +
1.132 + // Create implementations API declarations
1.133 + //
1.134 + // When Implementation UID is known:
1.135 + // Use CI1, CI2.
1.136 + // Use CI3, CI4 when you have construction parameters.
1.137 + //
1.138 + // When the Interface UID is known and default resolving is required:
1.139 + // Use CI5, CI6.
1.140 + // Use CI7, CI8 when you have construction parameters.
1.141 + //
1.142 + // When the Interface UID is known and custom resolving is required:
1.143 + // Use CI9, CI10.
1.144 + // Use CI11, CI12 when you have construction parameters.
1.145 +
1.146 + // CreateImplementationL - CI1
1.147 + IMPORT_C static TAny* CreateImplementationL(
1.148 + TUid aImplementationUid,
1.149 + TUid& aDtorIDKey);
1.150 +
1.151 + // CreateImplementationL - CI2
1.152 + IMPORT_C static TAny* CreateImplementationL(
1.153 + TUid aImplementationUid,
1.154 + TInt32 aKeyOffset);
1.155 +
1.156 + // CreateImplementationL - CI3
1.157 + IMPORT_C static TAny* CreateImplementationL(
1.158 + TUid aImplementationUid,
1.159 + TUid& aDtorIDKey,
1.160 + TAny* aConstructionParameters);
1.161 +
1.162 + // CreateImplementationL - CI4
1.163 + IMPORT_C static TAny* CreateImplementationL(
1.164 + TUid aImplementationUid,
1.165 + TInt32 aKeyOffset,
1.166 + TAny* aConstructionParameters);
1.167 +
1.168 + // CreateImplementationL - CI5
1.169 + IMPORT_C static TAny* CreateImplementationL(
1.170 + TUid aInterfaceUid,
1.171 + TUid& aDtorIDKey,
1.172 + const TEComResolverParams& aResolutionParameters);
1.173 +
1.174 + // CreateImplementationL - CI6
1.175 + IMPORT_C static TAny* CreateImplementationL(
1.176 + TUid aInterfaceUid,
1.177 + TInt32 aKeyOffset,
1.178 + const TEComResolverParams& aResolutionParameters);
1.179 +
1.180 + // CreateImplementationL - CI7
1.181 + IMPORT_C static TAny* CreateImplementationL(
1.182 + TUid aInterfaceUid,
1.183 + TUid& aDtorIDKey,
1.184 + TAny* aConstructionParameters,
1.185 + const TEComResolverParams& aResolutionParameters);
1.186 +
1.187 + // CreateImplementationL - CI8
1.188 + IMPORT_C static TAny* CreateImplementationL(
1.189 + TUid aInterfaceUid,
1.190 + TInt32 aKeyOffset,
1.191 + TAny* aConstructionParameters,
1.192 + const TEComResolverParams& aResolutionParameters);
1.193 +
1.194 + // CreateImplementationL - CI9
1.195 + IMPORT_C static TAny* CreateImplementationL(
1.196 + TUid aInterfaceUid,
1.197 + TUid& aDtorIDKey,
1.198 + const TEComResolverParams& aResolutionParameters,
1.199 + TUid aResolverUid);
1.200 +
1.201 + // CreateImplementationL - CI10
1.202 + IMPORT_C static TAny* CreateImplementationL(
1.203 + TUid aInterfaceUid,
1.204 + TInt32 aKeyOffset,
1.205 + const TEComResolverParams& aResolutionParameters,
1.206 + TUid aResolverUid);
1.207 +
1.208 + // CreateImplementationL - CI11
1.209 + IMPORT_C static TAny* CreateImplementationL(
1.210 + TUid aInterfaceUid,
1.211 + TUid& aDtorIDKey,
1.212 + TAny* aConstructionParameters,
1.213 + const TEComResolverParams& aResolutionParameters,
1.214 + TUid aResolverUid);
1.215 +
1.216 + // CreateImplementationL - CI12
1.217 + IMPORT_C static TAny* CreateImplementationL(
1.218 + TUid aInterfaceUid,
1.219 + TInt32 aKeyOffset,
1.220 + TAny* aConstructionParameters,
1.221 + const TEComResolverParams& aResolutionParameters,
1.222 + TUid aResolverUid);
1.223 +
1.224 + // Get Implementation Uid from a Destructor Id Key
1.225 + IMPORT_C static TUid GetImplementationUidL(
1.226 + TUid aDtorIDKey);
1.227 +
1.228 + // Destroy Implementation API declaration
1.229 + IMPORT_C static void DestroyedImplementation(
1.230 + TUid aDtorIDKey);
1.231 +
1.232 +
1.233 + // See developer documentation for use of FinalClose.
1.234 + IMPORT_C static void FinalClose();
1.235 +
1.236 +private:
1.237 +
1.238 + static REComSession& OpenLC();
1.239 +
1.240 + void ConstructL();
1.241 + void ReallyClose();
1.242 +
1.243 + void ListImplementationsL(
1.244 + TInt aServiceId,
1.245 + TUid aInterfaceUid,
1.246 + const TEComResolverParams& aResolutionParameters,
1.247 + TUid aResolverUid,
1.248 + RImplInfoPtrArray& aImplInfoArray);
1.249 +
1.250 + TAny* ResolveAndCreateImplL(
1.251 + TUid aImplementationUid,
1.252 + TUid& aDtorIDKey,
1.253 + TAny* aCreationParameters,
1.254 + TBool aCreationParamsFlag);
1.255 +
1.256 + TAny* ResolveAndCreateImplL(
1.257 + TUid aInterfaceUid,
1.258 + const TEComResolverParams& aResolutionParameters,
1.259 + TUid& aDtorIDKey,
1.260 + TAny* aCreationParameters,
1.261 + TBool aCreationParamsFlag);
1.262 +
1.263 + TAny* ResolveAndCreateImplL(
1.264 + TUid aInterfaceUid,
1.265 + const TEComResolverParams& aResolutionParameters,
1.266 + TUid aResolverUid,
1.267 + TUid& aDtorIDKey,
1.268 + TAny* aCreationParameters,
1.269 + TBool aCreationParamsFlag);
1.270 +
1.271 + TAny* ResolveAndCreateImplL(
1.272 + TInt aServiceId,
1.273 + TUid aInterfaceUid,
1.274 + const TEComResolverParams& aResolutionParameters,
1.275 + TUid aResolverUid,
1.276 + TUid& aDtorIDKey,
1.277 + TAny* aCreationParameters,
1.278 + TBool aCreationParamsFlag);
1.279 +
1.280 +public:
1.281 + //This API is for internal use only and for testing purposes.
1.282 + IMPORT_C static void SetGetParametersL(const TIpcArgs &aArgs);
1.283 +
1.284 +private:
1.285 + /** Not used */
1.286 + TInt iReserved1;
1.287 +
1.288 + /** Not used */
1.289 + TBool iReserved3;
1.290 +
1.291 + /** not used */
1.292 + TInt iReserved2;
1.293 + };
1.294 +
1.295 +
1.296 +#endif // __ECOM_H__