»
Developer Library »
API Reference »
C++ API reference »
ECom Plug-in Architecture »
REComSession
Location:
ecom.h
Link against: ecom.lib
REComSession
Support
Supported from 7.0
Description
Controls the process of identification
(resolution), instantiation, and destruction of requested
interface implementations.
REComSession is a session to the ECom server. Note the following special characteristics:
Derivation
REComSession | Controls the process of identification (resolution), instantiation, and destruction of requested interface implementations |
RHandleBase | A handle to an object |
RSessionBase | Client-side handle to a session with a server |
|
Defined in REComSession:
CancelNotifyOnChange(), Close(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), CreateImplementationL(), DestroyedImplementation(), ListImplementationsL(), ListImplementationsL(), ListImplementationsL(), NotifyOnChange(), OpenL(), REComSession()
Inherited from RHandleBase:
Duplicate(),
Handle(),
SetHandle()
Inherited from RSessionBase:
Attach(),
CreateSession(),
EAutoAttach,
EExplicitAttach,
Send(),
SendReceive(),
SetRetry(),
Share(),
TAttachMode
Construction
REComSession();
Description
Default constructor.
static REComSession& OpenL();
Description
Open a session to the ECom server.
Open sessions are reference counted. A session should be Close()ed when its use is complete.
Return value
Leave codes
|
System-wide error code if connection fails |
|
void Close();
Description
Closes an open session.
void NotifyOnChange(TRequestStatus& aStatus);
Description
Requests to be notified when interface implementation registration
data changes.
On receiving such a notification, a client can refresh its list of interface implementations.
Parameters
TRequestStatus& aStatus |
The request status. On request completion, contains KErrNone, if successful; otherwise, one of the other system wide error codes. |
|
void CancelNotifyOnChange(TRequestStatus& aStatus);
Description
Cancels a change notification request.
Note that this is a synchronous function.
Parameters
TRequestStatus& aStatus |
Notification request to cancel. KErrCancel on successful cancellation. |
|
static void ListImplementationsL(TUid aInterfaceUid, RImplInfoPtrArray& aImplInfoArray);
Description
Gets an array of all the implementations of the specified interface.
Parameters
TUid aInterfaceUid |
UID of the interface |
RImplInfoPtrArray& aImplInfoArray |
A reference to a client-owned array, which on return is filled
with interface implementation data. Any existing data in the array is destroyed. |
|
static void ListImplementationsL(TUid aInterfaceUid, const TEComResolverParams& aResolutionParameters, RImplInfoPtrArray& aImplInfoArray);
Description
Gets an array of all the implementations of the specified interface that satisfy the specified parameters.
Parameters
TUid aInterfaceUid |
UID of the interface |
const TEComResolverParams& aResolutionParameters |
Parameters that the implementations must satisfy |
RImplInfoPtrArray& aImplInfoArray |
A reference to a client-owned array, which on return is filled
with interface implementation data. Any existing data in the array is destroyed. |
|
static void ListImplementationsL(TUid aInterfaceUid,const TEComResolverParams& aResolutionParameters, TUid aResolverUid,RImplInfoPtrArray& aImplInfoArray);
Description
Gets an array of all the implementations of the specified interface that satisfy the specified parameters, specifying a resolver to use.
Parameters
TUid aInterfaceUid |
UID of the interface |
const TEComResolverParams& aResolutionParameters |
Parameters that the implementations must satisfy |
const TUid aResolverUid |
UID of the resolver to use |
RImplInfoPtrArray& aImplInfoArray |
A reference to a client-owned array, which on return is filled
with interface implementation data. Any existing data in the array is destroyed. |
|
See also:
Create implementation instance
static TAny* CreateImplementationL(TUid aImplementationUid, TUid& aDtorIDKey);
Description
Instantiates the specified interface implementation, passing an instance ID.
Parameters
TUid aImplementationUid |
UID of the interface implementation to instantiate |
TUid& aDtorIDKey |
On return, an identifier of this instance. This value should be passed to DestroyedImplementation() when the use of the instance is complete. |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
static TAny* CreateImplementationL(TUid aImplementationUid, TInt32 aKeyOffset);
Description
Instantiates the specified interface implementation, passing the offset of an instance ID.
Parameters
TUid aImplementationUid |
UID of the interface implementation to instantiate |
TInt32 aKeyOffset |
The offset of a TUid member of the interface, in which to store the ID for the instance. You can get this value using the _FOFF macro. The framework then initialises that member to the ID. The ID should be passed to DestroyedImplementation() when the use of the instance is complete. |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
See also:
static TAny* CreateImplementationL(TUid aImplementationUid, TUid& aDtorIDKey, TAny* aConstructionParameters);
Description
Instantiates the specified interface implementation, passing an instance ID, and instance construction data.
Parameters
TUid aImplementationUid |
UID of the interface implementation to instantiate |
TUid& aDtorIDKey |
On return, an identifier of this instance. This value should be passed to DestroyedImplementation() when the use of the instance is complete. |
TAny* aConstructionParameters |
Data to be passed to the instance. If the implementation's creation function has a TAny* parameter, the data is passed to it. Note that the parameter is not const, so the instance can modify the data. |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
static TAny* CreateImplementationL(TUid aImplementationUid, TInt32 aKeyOffset, TAny* aConstructionParameters);
Description
Instantiates the specified interface implementation, passing the offset of an instance ID and instance construction data.
Parameters
TUid aImplementationUid |
UID of the interface implementation to instantiate |
TInt32 aKeyOffset |
The offset of a TUid member of the interface, in which to store the ID for the instance. You can get this value using the _FOFF macro. The framework then initialises that member to the ID. The ID should be passed to DestroyedImplementation() when the use of the instance is complete. |
TAny* aConstructionParameters |
Data to be passed to the instance. If the implementation's creation function has a TAny* parameter, the data is passed to it. Note that the parameter is not const, so the instance can modify the data. |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
See also:
static TAny* CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset, const TEComResolverParams& aResolutionParameters);
Description
Instantiates an implementation for the specified interface, passing the offset of an instance ID, and resolution criteria.
Parameters
TUid aInterfaceUid |
UID of the interface to get an implementation for |
TInt32 aKeyOffset |
The offset of a TUid member of the interface, in which to store the ID for the instance. You can get this value using the _FOFF macro. The framework then initialises that member to the ID. The ID should be passed to DestroyedImplementation() when the use of the instance is complete. |
const TEComResolverParams& aResolutionParameters |
Additional criteria which must be satisfied by the implementation |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
See also:
static TAny* CreateImplementationL(TUid aInterfaceUid, TUid& aDtorIDKey, const TEComResolverParams& aResolutionParameters);
Description
Instantiates an implementation for the specified interface, passing an instance ID, and resolution criteria.
Parameters
TUid aInterfaceUid |
UID of the interface to get an implementation for |
TUid& aDtorIDKey |
On return, an identifier of this instance. This value should be passed to DestroyedImplementation() when the use of the instance is complete. |
const TEComResolverParams& aResolutionParameters |
Additional criteria which must be satisfied by the implementation |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
static TAny* CreateImplementationL(TUid aInterfaceUid, TUid& aDtorIDKey, TAny* aConstructionParameters, const TEComResolverParams& aResolutionParameters);
Description
Instantiates an implementation for the specified interface, passing an instance ID, instance construction data, and resolution criteria.
Parameters
TUid aInterfaceUid |
UID of the interface to get an implementation for |
TUid& aDtorIDKey |
On return, an identifier of this instance. This value should be passed to DestroyedImplementation() when the use of the instance is complete. |
TAny* aConstructionParameters |
Data to be passed to the instance. If the implementation's creation function has a TAny* parameter, the data is passed to it. Note that the parameter is not const, so the instance can modify the data. |
const TEComResolverParams& aResolutionParameters |
Additional criteria which must be satisfied by the implementation |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
static TAny* CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset,const TEComResolverParams& aResolutionParameters, TUid aResolverUid);
Description
Instantiates an implementation for the specified interface, passing an offset to the instance ID, resolution criteria, and ID of the resolver to use.
Parameters
TUid aInterfaceUid |
UID of the interface to get an implementation for |
TInt32 aKeyOffset |
The offset of a TUid member of the interface, in which to store the ID for the instance. You can get this value using the _FOFF macro. The framework then initialises that member to the ID. The ID should be passed to DestroyedImplementation() when the use of the instance is complete. |
const TEComResolverParams& aResolutionParameters |
Additional criteria which must be satisfied by the implementation |
const TUid aResolverUid |
UID of the resolver to use |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
See also:
static TAny* CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset, TAny* aConstructionParameters, const TEComResolverParams& aResolutionParameters);
Description
Instantiates an implementation for the specified interface, passing an offset to the instance ID, instance construction data, and resolution criteria.
Parameters
TUid aInterfaceUid |
UID of the interface to get an implementation for |
TInt32 aKeyOffset |
The offset of a TUid member of the interface, in which to store the ID for the instance. You can get this value using the _FOFF macro. The framework then initialises that member to the ID. The ID should be passed to DestroyedImplementation() when the use of the instance is complete. |
TAny* aConstructionParameters |
Data to be passed to the instance. If the implementation's creation function has a TAny* parameter, the data is passed to it. Note that the parameter is not const, so the instance can modify the data. |
const TEComResolverParams& aResolutionParameters |
Additional criteria which must be satisfied by the implementation |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
See also:
static TAny* CreateImplementationL(TUid aInterfaceUid, TUid& aDtorIDKey, const TEComResolverParams& aResolutionParameters,TUid aResolverUid);
Description
Instantiates an implementation for the specified interface, passing an instance ID, resolution criteria, and the ID of the resolver to use.
Parameters
TUid aInterfaceUid |
UID of the interface to get an implementation for |
TUid& aDtorIDKey |
On return, an identifier of this instance. This value should be passed to DestroyedImplementation() when the use of the instance is complete. |
const TEComResolverParams& aResolutionParameters |
Additional criteria which must be satisfied by the implementation |
const TUid aResolverUid |
UID of the resolver to use |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
static TAny* CreateImplementationL(TUid aInterfaceUid, TUid& aDtorIDKey, TAny* aConstructionParameters,const TEComResolverParams& aResolutionParameters, TUid aResolverUid);
Description
Instantiates an implementation for the specified interface, passing an instance ID, instance construction data, resolution criteria, and ID of the resolver to use.
Parameters
TUid aInterfaceUid |
UID of the interface to get an implementation for |
TUid& aDtorIDKey |
On return, an identifier of this instance. This value should be passed to DestroyedImplementation() when the use of the instance is complete. |
TAny* aConstructionParameters |
Data to be passed to the instance. If the implementation's creation function has a TAny* parameter, the data is passed to it. Note that the parameter is not const, so the instance can modify the data. |
const TEComResolverParams& aResolutionParameters |
Additional criteria which must be satisfied by the implementation |
TUid aResolverUid |
UID of the resolver to use |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
static TAny* CreateImplementationL(TUid aInterfaceUid, TInt32 aKeyOffset, TAny* aConstructionParameters,const TEComResolverParams& aResolutionParameters,TUid aResolverUid);
Description
Instantiates an implementation for the specified interface, passing an offset to the instance ID, instance construction data, resolution criteria, and ID of the resolver to use.
Parameters
TUid aInterfaceUid |
UID of the interface to get an implementation for |
TInt32 aKeyOffset |
The offset of a TUid member of the interface, in which to store the ID for the instance. You can get this value using the _FOFF macro. The framework then initialises that member to the ID. The ID should be passed to DestroyedImplementation() when the use of the instance is complete. |
TAny* aConstructionParameters |
Data to be passed to the instance. If the implementation's creation function has a TAny* parameter, the data is passed to it. Note that the parameter is not const, so the instance can modify the data. |
const TEComResolverParams& aResolutionParameters |
Additional criteria which must be satisfied by the implementation |
const TUid aResolverUid |
UID of the resolver to use |
|
Return value
TAny* |
Pointer to the newly created implementation object. This should be cast to the correct interface type. |
|
Leave codes
KErrNotFound |
No suitable implementation is present |
|
Leaves can also come from the implementation's creation function |
|
See also:
Implementation instance destruction
DestroyedImplementation()
static void DestroyedImplementation(TUid aDtorIDKey);
Description
Signals the destruction of an implementation instance to the ECom framework.
You should call this function after deleting the instance.
Parameters
TUid aDtorIDKey |
An ID specifying the instance to destroy |
|
![[Index]](../../../../_stock/btn_index.gif){kind=small}
![[Glossary]](../../../../_stock/btn_glossary.gif){kind=small}
![[Previous]](../../../../_stock/btn_prev.gif){kind=small}
![[Next]](../../../../_stock/btn_next.gif){kind=small}
![[Top]](../../../../_stock/arrow_up_2.gif){kind=icon}
![[Top]](../../../../_stock/arrow_up.gif){kind=icon}