![[Index]](../../../../a_stock/images/btn_index.gif)
![[Previous]](../../../../a_stock/images/btn_prev_top.gif)
![[Next]](../../../../a_stock/images/btn_next_top.gif)
|
|
|
|
|
|
||
class REComSession : public RSessionBase;
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 provides an un-initialise function where it releases memory and handles of unused
plug-ins, see the REComSession::FinalClose() function. It also ensures that all necessary clean-up is performed in the event of a Leave by any of the REComSession::ListImplementationsL(TUid,RImplInfoPtrArray &) or REComSession::CreateImplementationL(TUid,TUid &) methods.
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 REComSession::OpenL() method to obtain a pointer or a reference to the single reference counted session in use. REComSession::Close() must be called when finished with.
Special care must be taken when using aDtorIDKey. It is a 32-bit instance key that is returned from a call to one of the REComSession::CreateImplementationL(TUid,TUid &) methods. This instance key must only be used with REComSession::DestroyedImplementation(TUid) to identify the implementation instance for destruction, or REComSession::GetImplementationUidL(TUid) to retrieve the Implementation Uid of the instance it refers to. No meaning must be attached to this instance key by ECOM
clients and it must not be used for any other purpose.
RHandleBase - A handle to an object.
RSessionBase -
Client-side handle to a session with a server.
REComSession - The REComSession singleton class provides an API to identify (resolution), insta...
Defined in REComSession:
CancelNotifyOnChange(TRequestStatus &)De-registers for notification messages. Close()Closes the open handle on the ECOM framework. Reference count is decremented and...CreateImplementationL(TUid,TInt32)Instantiates an interface implementation to satisfy the specified interface. CreateImplementationL(TUid,TInt32,TAny *)Instantiates an interface implementation to satisfy the specified interface. CreateImplementationL(TUid,TInt32,TAny *,const TEComResolverParams &)Instantiates an interface implementation to satisfy the specified interface.CreateImplementationL(TUid,TInt32,TAny *,const TEComResolverParams &,TUid)Instantiates an interface implementation to satisfy the specified interface.CreateImplementationL(TUid,TInt32,const TEComResolverParams &)Instantiates an interface implementation to satisfy the specified interface.CreateImplementationL(TUid,TInt32,const TEComResolverParams &,TUid)Instantiates an interface implementation to satisfy the specified interface.CreateImplementationL(TUid,TUid &)Instantiates an interface implementation to satisfy the specified interface. CreateImplementationL(TUid,TUid &,TAny *)Instantiates an interface implementation to satisfy the specified interface. CreateImplementationL(TUid,TUid &,TAny *,const TEComResolverParams &)Instantiates an interface implementation to satisfy the specified interface.CreateImplementationL(TUid,TUid &,TAny *,const TEComResolverParams &,TUid)Instantiates an interface implementation to satisfy the specified interface.CreateImplementationL(TUid,TUid &,const TEComResolverParams &)Instantiates an interface implementation to satisfy the specified interface.CreateImplementationL(TUid,TUid &,const TEComResolverParams &,TUid)Instantiates an interface implementation to satisfy the specified interface.DestroyedImplementation(TUid)Signals the destruction of an interface implementation to ECOM. LoadManager is r...FinalClose()This method is used in processes that have utilised the ECOM framework, it does ...GetImplementationUidL(TUid)Gets the corresponding implementation uid for a destructor id key. This is typic...ListImplementationsL(TUid,RImplInfoPtrArray &)Retrieves a list of all the implementations which satisfy the specified interfac...ListImplementationsL(TUid,const TEComResolverParams &,RImplInfoPtrArray &)Retrieves a list of all the implementations which satisfy the specified interfac...ListImplementationsL(TUid,const TEComResolverParams &,TUid,RImplInfoPtrArray &)Retrieves a list of all the implementations which satisfy the specified interfac...NotifyOnChange(TRequestStatus &)Registers for notification messages when the underlying ECOM registration data c...OpenL()This method returns a reference to the singleton client/server session object ma...REComSession()Inherited from RHandleBase:
Attributes()constBTraceId()constReturns a unique object identifier for use with BTrace
Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...FullName()constGets the full name of the handle.FullName(TDes &)constGets the full name of the handle.Handle()constRetrieves the handle-number of the object associated with this handle.HandleInfo(THandleInfo *)Gets information about the handle.Name()constGets the name of the handle.Open(const TFindHandleBase &,TOwnerType)Opens a handle to a kernel side object found using a find-handle object.RHandleBase(TInt)Copy constructor.SetHandle(TInt)Sets the handle-number of this handle to the specified value.SetHandleNC(TInt)Sets the handle-number of this handle to the specified value, and marks it as no...iHandleInherited from RSessionBase:
CreateSession(RServer2,const TVersion &)Creates a session with a server, specifying no message slots.CreateSession(RServer2,const TVersion &,TInt)Creates a session with a server.CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)Creates a session with a server.CreateSession(const TDesC &,const TVersion &)Creates a session with a server, specifying no message slots.CreateSession(const TDesC &,const TVersion &,TInt)Creates a session with a server.CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)Creates a session with a server.CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)EAutoAttachEExplicitAttachOpen(RMessagePtr2,TInt,TOwnerType)Opens a handle to a session using a handle number sent by a client to a server.Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)Opens a handle to a session using a handle number sent by a client to a server, ...Open(TInt,TOwnerType)Opens a handle to a session using a handle number passed as an environment data ...Open(TInt,const TSecurityPolicy &,TOwnerType)Opens a handle to a session using a handle number passed as an environment data ...Send(TInt)constIssues a blind request to the server with the specified function number, but wit...Send(TInt,const TIpcArgs &)constIssues a blind request to the server with the specified function number, and arg...SendReceive(TInt)constIssues a synchronous request to the server with the specified function number, b...SendReceive(TInt,TRequestStatus &)constIssues an asynchronous request to the server with the specified function number,...SendReceive(TInt,const TIpcArgs &)constIssues a synchronous request to the server with the specified function number an...SendReceive(TInt,const TIpcArgs &,TRequestStatus &)constIssues an asynchronous request to the server with the specified function number ...SetReturnedHandle(TInt)Sets the handle-number of this handle to the specified value.SetReturnedHandle(TInt,RHandleBase &)SetReturnedHandle(TInt,const TSecurityPolicy &)Sets the handle-number of this session handle to the specified value after valid...ShareAuto()Creates a session that can be shared by other threads in the current process.ShareProtected()Creates a session handle that can be be passed via IPC to another process as wel...TAttachModeIndicates whether or not threads in the process are automatically attached to th...REComSession::FinalClose()This method is used in processes that have utilised the ECOM framework, it does ...|
|
IMPORT_C static REComSession& OpenL();
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 RSessionBase::Open(RMessagePtr2,TInt,TOwnerType)/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 RSessionBase::Open(RMessagePtr2,TInt,TOwnerType) must have an equivalent REComSession::Close().
REComSession is connected and ready to issue ECOM requests.
|
|
IMPORT_C void Close();
REComSession must have been opened.
Closes the open handle on the ECOM framework. Reference count is decremented and the ECOM client/server session is closed.
REComSession reference count is decremented, server session closed
IMPORT_C void NotifyOnChange(TRequestStatus &aStatus);
REComSession must have been opened.
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.
The caller is registered for receipt of notifications if the server's registry data changes.
|
IMPORT_C void CancelNotifyOnChange(TRequestStatus &aStatus);
REComSession must have been opened.
De-registers for notification messages.
The caller's registeration for reciept of notifications of registry data changes has been cancelled.
|
IMPORT_C static void ListImplementationsL(TUid aInterfaceUid, RImplInfoPtrArray &aImplInfoArray);
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.
REComSession has not changed, and aImplInfoArray contains the list of Implementation information for the interface.
|
|
IMPORT_C static void ListImplementationsL(TUid aInterfaceUid, const TEComResolverParams &aResolutionParameters, RImplInfoPtrArray
&aImplInfoArray);
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.
REComSession has not changed, and aImplInfoArray contains the list of Implementation information for the interface.
|
|
![[Top]](../../../../a_stock/images/arrow_up_2.gif){kind=icon}
TEComResolverParamsUsed to pass values to a Resolver to aid in the filtering of Interface Implement...IMPORT_C static void ListImplementationsL(TUid aInterfaceUid, const TEComResolverParams &aResolutionParameters, TUid aResolverUid,
RImplInfoPtrArray &aImplInfoArray);
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.
REComSession has not changed, and aImplInfoArray contains the list of Implementation information for the interface.
|
|
TEComResolverParamsUsed to pass values to a Resolver to aid in the filtering of Interface Implement...IMPORT_C static TAny* CreateImplementationL(TUid aImplementationUid, TUid &aDtorIDKey);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
IMPORT_C static TAny* CreateImplementationL(TUid aImplementationUid, TInt32 aKeyOffset);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
IMPORT_C static TAny* CreateImplementationL(TUid aImplementationUid, TUid &aDtorIDKey, TAny *aConstructionParameters);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
IMPORT_C static TAny* CreateImplementationL(TUid aImplementationUid, TInt32 aKeyOffset, TAny *aConstructionParameters);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
IMPORT_C static TAny* CreateImplementationL(TUid aInterfaceUid, TUid &aDtorIDKey, const TEComResolverParams &aResolutionParameters);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
TEComResolverParamsUsed to pass values to a Resolver to aid in the filtering of Interface Implement...IMPORT_C static TAny* CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset, const TEComResolverParams &aResolutionParameters);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
TEComResolverParamsUsed to pass values to a Resolver to aid in the filtering of Interface Implement...IMPORT_C static TAny* CreateImplementationL(TUid aInterfaceUid, TUid &aDtorIDKey, TAny *aConstructionParameters, const TEComResolverParams
&aResolutionParameters);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
TEComResolverParamsUsed to pass values to a Resolver to aid in the filtering of Interface Implement...IMPORT_C static TAny* CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset, TAny *aConstructionParameters, const TEComResolverParams
&aResolutionParameters);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
TEComResolverParamsUsed to pass values to a Resolver to aid in the filtering of Interface Implement...IMPORT_C static TAny* CreateImplementationL(TUid aInterfaceUid, TUid &aDtorIDKey, const TEComResolverParams &aResolutionParameters,
TUid aResolverUid);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
TEComResolverParamsUsed to pass values to a Resolver to aid in the filtering of Interface Implement...IMPORT_C static TAny* CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset, const TEComResolverParams &aResolutionParameters,
TUid aResolverUid);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
TEComResolverParamsUsed to pass values to a Resolver to aid in the filtering of Interface Implement...IMPORT_C static TAny* CreateImplementationL(TUid aInterfaceUid, TUid &aDtorIDKey, TAny *aConstructionParameters, const TEComResolverParams
&aResolutionParameters, TUid aResolverUid);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
TEComResolverParamsUsed to pass values to a Resolver to aid in the filtering of Interface Implement...IMPORT_C static TAny* CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset, TAny *aConstructionParameters, const TEComResolverParams
&aResolutionParameters, TUid aResolverUid);
Instantiates an interface implementation to satisfy the specified interface.
The requested interface implementation is identified, and the instantiation method pointer is returned.
|
|
|
TEComResolverParamsUsed to pass values to a Resolver to aid in the filtering of Interface Implement...IMPORT_C static TUid GetImplementationUidL(TUid aDtorIDKey);
Gets the corresponding implementation uid for a destructor id key. This is typically used after a call to one of the REComSession::CreateImplementationL(TUid,TUid &) methods that returns the aDtorIDKey value as an output arg or by an offset (aKeyOffset).
REComSession has not changed
|
|
|
IMPORT_C static void DestroyedImplementation(TUid aDtorIDKey);
Signals the destruction of an interface implementation to ECOM. LoadManager is responsible for destroying the implementation
The destruction of the Interface Implementation referred to by aDtorIDKey
|
IMPORT_C static void FinalClose();
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.
|
Copyright © 2005-2008 Symbian Software Ltd. |
|
![[Previous]](../../../../a_stock/images/btn_prev.gif)
![[Top]](../../../../a_stock/images/btn_top.gif)
![[Next]](../../../../a_stock/images/btn_next.gif)