»
UIQ 3.1 SDK »
Symbian OS v9.2 »
Symbian OS reference »
C++ component reference »
Syslibs ECom »
REComSession
Location:
ECom.h
Link against: ecom.lib
class REComSession : public RSessionBase;
Description
The REComSession singleton class provides an API to identify (resolution), instantiate, and destroy interface class implementations requested by ECOM clients. It manages the session connection to the ECOM Server itself so that typically only one connection is made to the ECOM Server per thread. It also provides an un-initialise function where it releases memory and handles of unused plug-ins, see the FinalClose() function.
Note: Although a public default constructor is provided in this class it is strongly recommended this object is never created by users of this API on the stack or heap by value. To access the non-static methods of this API use the static OpenL() method to obtain a pointer or a reference to the single reference counted session in use. Close() must be called when finished with.
Derivation
RHandleBase - A handle to an objectRSessionBase - Client-side handle to a session with a serverREComSession - The REComSession singleton class provides an API to identify (resolution), instantiate, and destroy interface class implementations requested by ECOM clients
Members
Defined in REComSession:
CancelNotifyOnChange(), Close(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), DestroyedImplementation(), FinalClose(), ListImplementationsL(), ListImplementationsL(), ListImplementationsL(), NotifyOnChange(), OpenL(), REComSession()
Inherited from RHandleBase:
Attributes(),
Duplicate(),
FullName(),
Handle(),
HandleInfo(),
Name(),
SetHandle(),
SetHandleNC(),
iHandle
Inherited from RSessionBase:
CreateSession(),
EAutoAttach,
EExplicitAttach,
Open(),
Send(),
SendReceive(),
SetReturnedHandle(),
ShareAuto(),
ShareProtected(),
TAttachMode
See also:
Construction and destruction
IMPORT_C REComSession();
Description
static IMPORT_C REComSession &OpenL();
Description
This method returns a reference to the singleton client/server session object maintained by the ECOM client library, referenced counted. If it does not exist it is initialised and then returned. Clients should store the handle returned by refernce or by pointer. Storage by value is highly discouraged.
It is only necessary to use the Open()/Close() API directly if you need access to the notification methods. Access to the static API does not require these to be used. Please remeber each call to Open() must have an equivalent Close().
Post-Condition
REComSession is connected and ready to issue ECOM requests.
Return value
Leave codes
... |
One of the system-wide error codes |
|
IMPORT_C void Close();
Pre-Condition
REComSession must have been opened.
Description
Closes the open handle on the ECOM framework. Reference count is decremented and the ECOM client/server session is closed.
Post-Condition
REComSession reference count is decremented, server session closed
IMPORT_C void NotifyOnChange(TRequestStatus &aStatus);
Pre-Condition
REComSession must have been opened.
Description
Registers for notification messages when the underlying ECOM registration data changes. The client must not call this api again until their request is Completed as this could result in a 'stray signal'. This api should be placed first in the RunL of an Active Object otherwise changes could be lost. RunError should be implemented to cater for any Leaves. For example, it could retry after a second if the ECom server is busy rebuilding its indexes. CancelNotifyOnChange should be called to cancel this request and should NOT be part of the RunL.
Post-Condition
The caller is registered for receipt of notifications if the server's registry data changes.
Parameters
TRequestStatus &aStatus |
A request status object to complete for notification signalling. |
|
IMPORT_C void CancelNotifyOnChange(TRequestStatus &aStatus);
Pre-Condition
REComSession must have been opened.
Description
De-registers for notification messages.
Post-Condition
The caller's registeration for reciept of notifications of registry data changes has been cancelled.
Parameters
static IMPORT_C void ListImplementationsL(TUid aInterfaceUid, RImplInfoPtrArray &aImplInfoArray);
Description
Retrieves a list of all the implementations which satisfy the specified interface. The aImplInfoArray on exit contains the plug-in implementations who's plug-in DLLs have sufficient capabilities to be loaded by the calling client process.
Post-Condition
REComSession has not changed, and aImplInfoArray contains the list of Implementation information for the interface.
Parameters
TUid aInterfaceUid |
A UID specifying the required interface. |
RImplInfoPtrArray &aImplInfoArray |
A reference to a client owned array which will be filled with interface implementation data. The array will first be cleared and all items destroyed before adding new data. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
|
static IMPORT_C void ListImplementationsL(TUid aInterfaceUid, const TEComResolverParams &aResolutionParameters, RImplInfoPtrArray &aImplInfoArray);
Description
Retrieves a list of all the implementations which satisfy the specified interface with selection restriction to the specified parameters. The aImplInfoArray on exit contains the plug-in implementations who's plug-in DLLs have sufficient capabilities to be loaded by the calling client process.
Post-Condition
REComSession has not changed, and aImplInfoArray contains the list of Implementation information for the interface.
Parameters
TUid aInterfaceUid |
A UID specifying the required interface. |
const TEComResolverParams &aResolutionParameters |
A descriptor specifying any additional implementation characteristics to be fulfilled. |
RImplInfoPtrArray &aImplInfoArray |
A reference to a client owned array which will be filled with interface implementation data. The array will first be cleared and all items destroyed before adding new data. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
|
static IMPORT_C void ListImplementationsL(TUid aInterfaceUid, const TEComResolverParams &aResolutionParameters, TUid aResolverUid, RImplInfoPtrArray &aImplInfoArray);
Description
Retrieves a list of all the implementations which satisfy the specified interface with selection restriction to the specified parameters. The aImplInfoArray on exit contains the plug-in implementations who's plug-in DLLs have sufficient capabilities to be loaded by the calling client process. Overload with a client provided CResolver.
Post-Condition
REComSession has not changed, and aImplInfoArray contains the list of Implementation information for the interface.
Parameters
TUid aInterfaceUid |
A UID specifying the required interface. |
const TEComResolverParams &aResolutionParameters |
A descriptor specifying any additional implementation characteristics to be fulfilled. |
TUid aResolverUid |
The CResolver UID which identifies the resolver implementation with the required client defined behaviour. |
RImplInfoPtrArray &aImplInfoArray |
A reference to a client owned array which will be filled with interface implementation data. The array will first be cleared and all items destroyed before adding new data. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied |
|
|
static IMPORT_C TAny *CreateImplementationL(TUid aImplementationUid, TUid &aDtorIDKey);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aImplementationUid |
A UID specifying the required interface implementation. |
TUid &aDtorIDKey |
A 32 bit identifer returned by ECom to identify this instance to the framework. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
static IMPORT_C TAny *CreateImplementationL(TUid aImplementationUid, TInt32 aKeyOffset);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aImplementationUid |
A UID specifying the required interface implementation. |
TInt32 aKeyOffset |
An offset to the 32 bit identifer returned by the ECom framework to identify this instance to the framework. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
static IMPORT_C TAny *CreateImplementationL(TUid aImplementationUid, TUid &aDtorIDKey, TAny *aConstructionParameters);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aImplementationUid |
A UID specifying the required interface implementation. |
TUid &aDtorIDKey |
A 32 bit identifer returned by the ECom framework to identify this instance to the framework. |
TAny *aConstructionParameters |
The parameter structure to pass to the object creation method. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
static IMPORT_C TAny *CreateImplementationL(TUid aImplementationUid, TInt32 aKeyOffset, TAny *aConstructionParameters);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aImplementationUid |
A UID specifying the required interface implementation. |
TInt32 aKeyOffset |
An offset to the 32 bit identifer returned by the ECom framework to identify this instance to the framework. |
TAny *aConstructionParameters |
The parameter structure to pass to the object creation method. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
static IMPORT_C TAny *CreateImplementationL(TUid aInterfaceUid, TUid &aDtorIDKey, const TEComResolverParams &aResolutionParameters);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aInterfaceUid |
A UID specifying the required interface implementation. |
TUid &aDtorIDKey |
A 32 bit identifer returned by the ECom framework to identify this instance to the framework. |
const TEComResolverParams &aResolutionParameters |
A descriptor specifying any additional implementation characteristics to be fulfilled. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
static IMPORT_C TAny *CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset, const TEComResolverParams &aResolutionParameters);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aInterfaceUid |
A UID specifying the required interface implementation. |
TInt32 aKeyOffset |
An offset to the 32 bit identifer returned by the ECom framework to identify this instance to the framework. |
const TEComResolverParams &aResolutionParameters |
A descriptor specifying any additional implementation characteristics to be fulfilled. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
static IMPORT_C TAny *CreateImplementationL(TUid aInterfaceUid, TUid &aDtorIDKey, TAny *aConstructionParameters, const TEComResolverParams &aResolutionParameters);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aInterfaceUid |
A UID specifying the required interface implementation. |
TUid &aDtorIDKey |
A 32 bit identifer returned by the ECom framework to identify this instance to the framework. |
TAny *aConstructionParameters |
The parameter structure to pass to the object creation method. |
const TEComResolverParams &aResolutionParameters |
A descriptor specifying any additional implementation characteristics to be fulfilled. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
static IMPORT_C TAny *CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset, TAny *aConstructionParameters, const TEComResolverParams &aResolutionParameters);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aInterfaceUid |
A UID specifying the required interface implementation. |
TInt32 aKeyOffset |
An offset to the 32 bit identifer returned by the ECom framework to identify this instance to the framework. |
TAny *aConstructionParameters |
The parameter structure to pass to the object creation method. |
const TEComResolverParams &aResolutionParameters |
A descriptor specifying any additional implementation characteristics to be fulfilled. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
static IMPORT_C TAny *CreateImplementationL(TUid aInterfaceUid, TUid &aDtorIDKey, const TEComResolverParams &aResolutionParameters, TUid aResolverUid);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aInterfaceUid |
A UID specifying the required interface implementation. |
TUid &aDtorIDKey |
A 32 bit identifer returned by the ECom framework to identify this instance to the framework. |
const TEComResolverParams &aResolutionParameters |
A descriptor specifying any additional implementation characteristics to be fulfilled. |
TUid aResolverUid |
The Uid of a CResolver with client defined behaviour. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
static IMPORT_C TAny *CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset, const TEComResolverParams &aResolutionParameters, TUid aResolverUid);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aInterfaceUid |
A UID specifying the required interface implementation. |
TInt32 aKeyOffset |
An offset to the 32 bit identifer returned by the ECom framework to identify this instance to the framework. |
const TEComResolverParams &aResolutionParameters |
A descriptor specifying any additional implementation characteristics to be fulfilled. |
TUid aResolverUid |
The Uid of a CResolver with client defined behaviour. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
static IMPORT_C TAny *CreateImplementationL(TUid aInterfaceUid, TUid &aDtorIDKey, TAny *aConstructionParameters, const TEComResolverParams &aResolutionParameters, TUid aResolverUid);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aInterfaceUid |
A UID specifying the required interface implementation. |
TUid &aDtorIDKey |
A 32 bit identifer returned by the ECom framework to identify this instance to the framework. |
TAny *aConstructionParameters |
The parameter structure to pass to the object creation method. |
const TEComResolverParams &aResolutionParameters |
A descriptor specifying any additional implementation characteristics to be fulfilled. |
TUid aResolverUid |
The Uid of a CResolver with client defined behaviour. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
static IMPORT_C TAny *CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset, TAny *aConstructionParameters, const TEComResolverParams &aResolutionParameters, TUid aResolverUid);
Description
Instantiates an interface implementation to satisfy the specified interface.
Post-Condition
The requested interface implementation is identified, and the instantiation method pointer is returned.
Parameters
TUid aInterfaceUid |
A UID specifying the required interface implementation. |
TInt32 aKeyOffset |
An offset to the 32 bit identifer returned by the ECom framework to identify this instance to the framework. |
TAny *aConstructionParameters |
The parameter structure to pass to the object creation method. |
const TEComResolverParams &aResolutionParameters |
A descriptor specifying any additional implementation characteristics to be fulfilled. |
TUid aResolverUid |
The Uid of a CResolver with client defined behaviour. |
|
Return value
TAny * |
TAny* A pointer to the instantiated interface implementation. |
|
Leave codes
KErrNoMemory |
|
KErrNotConnected |
|
KErrArgument |
|
KErrPermissionDenied. |
This leave error can happen under the following conditions: 1. There is a capability mismatch between the process creating the implementation and the DLL containing the implementation 2. The plugin DLL installed on the media card was not properly installed, either the system hash value of this plugin is missing or it is inconsistent with that calculated for the plugin DLL at load time. |
|
DestroyedImplementation()
static IMPORT_C void DestroyedImplementation(TUid aDtorIDKey);
Description
Signals the destruction of an interface implementation to ECOM. LoadManager is responsible for destroying the implementation
Post-Condition
The destruction of the Interface Implementation referred to by aDtorIDKey
Parameters
TUid aDtorIDKey |
A key specifying a previously created implementation. |
|
static IMPORT_C void FinalClose();
Description
This method is used in processes that have utilised the ECOM framework, it does nothing if the ECOM framework has not been initialised. Its main purpose is to release memory and close handles held on unused plug-in implementations and their associated DLLs. If is found (through reference counting) that the ECOM framework is no longer in use in the calling thread the session to the ECOM's server is also closed.
This method is called by direct users of the ECOM framework wherever possible (e.g. library, server or test code). It is safe to call it at any time outside of plug-in code as the user's scenario dictates. This maybe during a test case or just before process termination.
Note: It must never be called from within a plug-in implementations class destructor, especially following a DestroyImplementation() as there is a risk that the plug-in's supporting DLL may immediately be unloaded by the Kernel due to the closure of RLibrary handles. It can result in a KERN-EXEC if the destructor call stack is still inside the DLL that is unloaded.
Note: Processes that utilise the ECOM framework that do not use this call are at risk of a UHEAP_MARKEND generated panic in debug builds.
![[Index]](../../../../../../_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../../../_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../../../_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../../../_stock/btn_next_wt.gif){kind=small}
![[Top]](../../../../../../_stock/arrow_up_2.gif){kind=icon}
![[Previous]](../../../../../../_stock/btn_prev.gif){kind=small}
![[Top]](../../../../../../_stock/btn_top.gif)
![[Next]](../../../../../../_stock/btn_next.gif){kind=small}