#include <e32cmn.h>
Link against:
euser.lib
class RMessagePtr2;
Description
A handle to a message sent by the client to the server.
A server's interaction with its clients is channelled through an RMessagePtr2 object, which acts as a handle to a message
sent by the client. The details of the original message are kept by the kernel allowing it enforce correct usage of the member
functions of this class.
Members
Defined in RMessagePtr2:
Client(RThread &,TOwnerType)constOpens a handle on the client thread.ClientL(RThread &,TOwnerType)constOpens a handle on the client thread.ClientProcessFlags()constClientStatus()constReturns the pointer to the clients TRequestStatus associated with the message.Complete(RHandleBase)constDuplicates the specified handle in the client thread, and returns this handle as...Complete(TInt)constFrees this message.GetDesLength(TInt)constGets the length of a descriptor argument in the client's process.GetDesLengthL(TInt)constGets the length of a descriptor argument in the client's process, leaving on fai...GetDesMaxLength(TInt)constGets the maximum length of a descriptor argument in the client's process.GetDesMaxLengthL(TInt)constGets the maximum length of a descriptor argument in the client's process, leavin...Handle()constGets the message handle value.HasCapability(TCapability,TCapability,const char *)constCheck if the process which sent this message has both of the given capabilities.HasCapability(TCapability,const char *)constCheck if the process which sent this message has a given capability.HasCapabilityL(TCapability,TCapability,const char *)constCheck if the process which sent this message has both of the given capabilities.HasCapabilityL(TCapability,const char *)constCheck if the process which sent this message has a given capability.Identity()constIsNull()constTests whether this message handle is empty.Kill(TInt)constKills the client.Panic(const TDesC &,TInt)constPanics the client.RMessagePtr2()Default constructor Read(TInt,TDes16 &,TInt)constReads data from the specified offset within the 16-bit descriptor argument, into...Read(TInt,TDes8 &,TInt)constReads data from the specified offset within the 8-bit descriptor argument, into ...ReadL(TInt,TDes16 &,TInt)constReads data from the specified offset within the 16-bit descriptor argument, into...ReadL(TInt,TDes8 &,TInt)constReads data from the specified offset within the 8-bit descriptor argument, into ...SecureId()constReturn the Secure ID of the process which sent this message.SetProcessPriority(TProcessPriority)constSets the priority of the client's process.SetProcessPriorityL(TProcessPriority)constSets the priority of the client's process.Terminate(TInt)constTerminates the client.VendorId()constReturn the Vendor ID of the process which sent this message.Write(TInt,const TDesC16 &,TInt)constWrites data from the specified source descriptor to the specified offset within ...Write(TInt,const TDesC8 &,TInt)constWrites data from the specified source descriptor to the specified offset within ...WriteL(TInt,const TDesC16 &,TInt)constWrites data from the specified source descriptor to the specified offset within ...WriteL(TInt,const TDesC8 &,TInt)constWrites data from the specified source descriptor to the specified offset within ...iHandle
Construction and destruction
inline RMessagePtr2();
Description
Default constructor
inline TBool IsNull() const;
Description
Tests whether this message handle is empty.
Return value
TBool
|
True, if this message handle is empty, false, otherwise.
|
|
inline TInt Handle() const;
Description
Gets the message handle value.
Return value
TInt
|
The message handle value.
|
|
IMPORT_C void Complete(TInt aReason) const;
Description
Frees this message.
Parameters
TInt aReason |
The completion code.
|
|
Complete(RHandleBase)const
IMPORT_C void Complete(RHandleBase aHandle) const;
Description
Duplicates the specified handle in the client thread, and returns this handle as a message completion code
Parameters
IMPORT_C TInt GetDesLength(TInt aParam) const;
Description
Gets the length of a descriptor argument in the client's process.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
|
Return value
TInt
|
The length of the descriptor, if successful. KErrArgument, if aParam has a value outside the valid range. KErrBadDescriptor,
if the message argument is not a descriptor type.
|
|
IMPORT_C TInt GetDesLengthL(TInt aParam) const;
Description
Gets the length of a descriptor argument in the client's process, leaving on failure.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
|
Return value
TInt
|
The length of the descriptor.
|
|
Leave codes
KErrArgument |
if aParam has a value outside the valid range.
|
KErrBadDescriptor, |
if the message argument is not a descriptor type.
|
|
GetDesMaxLength(TInt)const
IMPORT_C TInt GetDesMaxLength(TInt aParam) const;
Description
Gets the maximum length of a descriptor argument in the client's process.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
|
Return value
TInt
|
The maximum length of the descriptor, if successful. KErrArgument, if aParam has a value outside the valid range. KErrBadDescriptor,
if the message argument is not a descriptor type.
|
|
GetDesMaxLengthL(TInt)const
IMPORT_C TInt GetDesMaxLengthL(TInt aParam) const;
Description
Gets the maximum length of a descriptor argument in the client's process, leaving on failure.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
|
Return value
TInt
|
The length of the descriptor.
|
|
Leave codes
KErrArgument |
if aParam has a value outside the valid range.
|
KErrBadDescriptor, |
if the message argument is not a descriptor type.
|
|
ReadL(TInt,TDes8 &,TInt)const
IMPORT_C void ReadL(TInt aParam, TDes8 &aDes, TInt aOffset=0) const;
Description
Reads data from the specified offset within the 8-bit descriptor argument, into the specified target descriptor, and leaving
on failure.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
TDes8 &aDes |
The target descriptor into which the client data is to be written.
|
TInt aOffset |
The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.
|
|
Leave codes
KErrArgument |
if aParam has a value outside the valid range, or if aOffset is negative.
|
KErrBadDescriptor, |
if the message argument is not an 8-bit descriptor.
|
|
ReadL(TInt,TDes16 &,TInt)const
IMPORT_C void ReadL(TInt aParam, TDes16 &aDes, TInt aOffset=0) const;
Description
Reads data from the specified offset within the 16-bit descriptor argument, into the specified target descriptor, and leaving
on failure.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
TDes16 &aDes |
The target descriptor into which the client data is to be written.
|
TInt aOffset |
The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.
|
|
Leave codes
KErrArgument |
if aParam has a value outside the valid range, or if aOffset is negative.
|
KErrBadDescriptor, |
if the message argument is not a 16-bit descriptor.
|
|
WriteL(TInt,const TDesC8 &,TInt)const
IMPORT_C void WriteL(TInt aParam, const TDesC8 &aDes, TInt aOffset=0) const;
Description
Writes data from the specified source descriptor to the specified offset within the 8-bit descriptor argument, and leaving
on failure.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
const TDesC8 &aDes |
The source descriptor containing the data to be written.
|
TInt aOffset |
The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.
|
|
Leave codes
KErrArgument |
if aParam has a value outside the valid range, or if aOffset is negative.
|
KErrBadDescriptor, |
if the message argument is not an 8-bit descriptor.
|
|
WriteL(TInt,const TDesC16 &,TInt)const
IMPORT_C void WriteL(TInt aParam, const TDesC16 &aDes, TInt aOffset=0) const;
Description
Writes data from the specified source descriptor to the specified offset within the 16-bit descriptor argument, and leaving
on failure.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
const TDesC16 &aDes |
The source descriptor containing the data to be written.
|
TInt aOffset |
The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.
|
|
Leave codes
KErrArgument |
if aParam has a value outside the valid range, or if aOffset is negative.
|
KErrBadDescriptor, |
if the message argument is not a 16-bit descriptor.
|
|
Read(TInt,TDes8 &,TInt)const
IMPORT_C TInt Read(TInt aParam, TDes8 &aDes, TInt aOffset=0) const;
Description
Reads data from the specified offset within the 8-bit descriptor argument, into the specified target descriptor.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
TDes8 &aDes |
The target descriptor into which the client data is to be written.
|
TInt aOffset |
The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.
|
|
Return value
TInt
|
KErrNone, if successful; KErrArgument if aParam has a value outside the valid range, or if aOffset is negative. KErrBadDescriptor,
if the message argument is not an 8-bit descriptor.
|
|
Read(TInt,TDes16 &,TInt)const
IMPORT_C TInt Read(TInt aParam, TDes16 &aDes, TInt aOffset=0) const;
Description
Reads data from the specified offset within the 16-bit descriptor argument, into the specified target descriptor.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
TDes16 &aDes |
The target descriptor into which the client data is to be written.
|
TInt aOffset |
The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.
|
|
Return value
TInt
|
KErrNone, if successful; KErrArgument if aParam has a value outside the valid range, or if aOffset is negative. KErrBadDescriptor,
if the message argument is not a 16-bit descriptor.
|
|
Write(TInt,const TDesC8 &,TInt)const
IMPORT_C TInt Write(TInt aParam, const TDesC8 &aDes, TInt aOffset=0) const;
Description
Writes data from the specified source descriptor to the specified offset within the 8-bit descriptor argument.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
const TDesC8 &aDes |
The source descriptor containing the data to be written.
|
TInt aOffset |
The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.
|
|
Return value
TInt
|
KErrNone, if successful; KErrArgument if aParam has a value outside the valid range, or if aOffset is negative. KErrBadDescriptor,
if the message argument is not an 8-bit descriptor; KErrOverflow, if the target descriptor is too small to containt the data.
|
|
Write(TInt,const TDesC16 &,TInt)const
IMPORT_C TInt Write(TInt aParam, const TDesC16 &aDes, TInt aOffset=0) const;
Description
Writes data from the specified source descriptor to the specified offset within the 16-bit descriptor argument.
Parameters
TInt aParam |
The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
|
const TDesC16 &aDes |
The source descriptor containing the data to be written.
|
TInt aOffset |
The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.
|
|
Return value
TInt
|
KErrNone, if successful; KErrArgument if aParam has a value outside the valid range, or if aOffset is negative. KErrBadDescriptor,
if the message argument is not an 16-bit descriptor; KErrOverflow, if the target descriptor is too small to containt the data.
|
|
Panic(const TDesC &,TInt)const
IMPORT_C void Panic(const TDesC &aCategory, TInt aReason) const;
Description
Panics the client.
The length of the category name should be no greater than 16; any name with a length greater than 16 is truncated to 16.
Note that this method also completes the message. A subsequent call to Complete(TInt aReason) would cause a server panic.
Parameters
const TDesC16 &aCategory |
The panic category.
|
TInt aReason |
The panic code.
|
|
IMPORT_C void Kill(TInt aReason) const;
Description
Kills the client.
Note that this method also completes the message. A subsequent call to Complete(TInt aReason) would cause a server panic.
Parameters
TInt aReason |
The reason code associated with killing the client.
|
|
IMPORT_C void Terminate(TInt aReason) const;
Description
Terminates the client.
Note that this method also completes the message. A subsequent call to Complete(TInt aReason) would cause a server panic.
Parameters
TInt aReason |
The reason code associated with terminating the client.
|
|
SetProcessPriority(TProcessPriority)const
IMPORT_C TInt SetProcessPriority(TProcessPriority aPriority) const;
Description
Sets the priority of the client's process.
Parameters
Return value
TInt
|
KErrNone, if successful, otherwise one of the other system-wide error codes.
|
|
SetProcessPriorityL(TProcessPriority)const
inline void SetProcessPriorityL(TProcessPriority aPriority) const;
Description
Sets the priority of the client's process.
Parameters
Client(RThread &,TOwnerType)const
IMPORT_C TInt Client(RThread &aClient, TOwnerType aOwnerType=EOwnerProcess) const;
Description
Opens a handle on the client thread.
Parameters
RThread &aClient |
On successful return, the handle to the client thread.
|
TOwnerType aOwnerType |
An enumeration whose enumerators define the ownership of the handle. If not explicitly specified, EOwnerProcess is taken as
default.
|
|
Return value
ClientL(RThread &,TOwnerType)const
inline void ClientL(RThread &aClient, TOwnerType aOwnerType=EOwnerProcess) const;
Description
Opens a handle on the client thread.
Parameters
RThread &aClient |
On successful return, the handle to the client thread.
|
TOwnerType aOwnerType |
An enumeration whose enumerators define the ownership of the handle. If not explicitly specified, EOwnerProcess is taken as
default.
|
|
ClientProcessFlags()const
IMPORT_C TUint ClientProcessFlags() const;
Description
Return value
IMPORT_C const TRequestStatus* ClientStatus() const;
Description
Returns the pointer to the clients TRequestStatus associated with the message.
The return value is intended to be used as a unique identifier (for example, to uniquely identify an asynchronous message
when cancelling the request). The memory must never be accessed directly or completed.
Return value
IMPORT_C TSecureId SecureId() const;
Description
Return the Secure ID of the process which sent this message.
If an intended use of this method is to check that the Secure ID is a given value, then the use of a TSecurityPolicy object should be considered. E.g. Instead of something like:
RMessagePtr2& message;
TInt error = message.SecureId()==KRequiredSecureId ? KErrNone : KErrPermissionDenied;
this could be used;
RMessagePtr2& message;
static _LIT_SECURITY_POLICY_S0(mySidPolicy, KRequiredSecureId);
TInt error = mySidPolicy().CheckPolicy(message);
This has the benefit that the TSecurityPolicy::CheckPolicy(RProcess,const char *)const methods are configured by the system wide Platform Security configuration. I.e. are capable of emitting diagnostic messages
when a check fails and/or the check can be forced to always pass.
Return value
See also:
IMPORT_C TVendorId VendorId() const;
Description
Return the Vendor ID of the process which sent this message.
If an intended use of this method is to check that the Vendor ID is a given value, then the use of a TSecurityPolicy object should be considered. E.g. Instead of something like:
RMessagePtr2& message;
TInt error = message.VendorId()==KRequiredVendorId ? KErrNone : KErrPermissionDenied;
this could be used;
RMessagePtr2& message;
static _LIT_SECURITY_POLICY_V0(myVidPolicy, KRequiredVendorId);
TInt error = myVidPolicy().CheckPolicy(message);
This has the benefit that the TSecurityPolicy::CheckPolicy(RProcess,const char *)const methods are configured by the system wide Platform Security configuration. I.e. are capable of emitting diagnostic messages
when a check fails and/or the check can be forced to always pass.
Return value
See also:
HasCapability(TCapability,const char *)const
inline TBool HasCapability(TCapability aCapability, const char *aDiagnostic=0) const;
Description
Check if the process which sent this message has a given capability.
When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics
is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return ETrue even though
the check failed.
Parameters
TCapability aCapability |
The capability to test.
|
const char *aDiagnostic |
A string that will be emitted along with any diagnostic message that may be issued if the test finds the capability is not
present. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from
the system.
|
|
Return value
TBool
|
ETrue if process which sent this message has the capability, EFalse otherwise.
|
|
HasCapabilityL(TCapability,const char *)const
inline void HasCapabilityL(TCapability aCapability, const char *aDiagnosticMessage=0) const;
Description
Check if the process which sent this message has a given capability.
When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics
is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will not leave even though the
check failed.
Parameters
TCapability aCapability |
The capability to test.
|
const char *aDiagnosticMessage |
A string that will be emitted along with any diagnostic message that may be issued if the test finds the capability is not
present. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from
the system.
|
|
Leave codes
KErrPermissionDenied, |
if the process does not have the capability.
|
|
HasCapability(TCapability,TCapability,const char *)const
inline TBool HasCapability(TCapability aCapability1, TCapability aCapability2, const char *aDiagnostic=0) const;
Description
Check if the process which sent this message has both of the given capabilities.
When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics
is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return ETrue even though
the check failed.
Parameters
TCapability aCapability1 |
The first capability to test.
|
TCapability aCapability2 |
The second capability to test.
|
const char *aDiagnostic |
A string that will be emitted along with any diagnostic message that may be issued if the test finds a capability is not present.
This string should be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.
|
|
Return value
TBool
|
ETrue if the process which sent this message has both the capabilities, EFalse otherwise.
|
|
HasCapabilityL(TCapability,TCapability,const char *)const
inline void HasCapabilityL(TCapability aCapability1, TCapability aCapability2, const char *aDiagnosticMessage=0) const;
Description
Check if the process which sent this message has both of the given capabilities.
When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics
is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will not leave even though the
check failed.
Parameters
TCapability aCapability1 |
The first capability to test.
|
TCapability aCapability2 |
The second capability to test.
|
const char *aDiagnosticMessage |
A string that will be emitted along with any diagnostic message that may be issued if the test finds a capability is not present.
This string should be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.
|
|
Leave codes
KErrPermissionDenied, |
if the process does not have the capabilities.
|
|
| Interface status: |
deprecated |
Use SecureId() |
inline TUid Identity() const;
Description
Return value
protected: TInt iHandle;
Description
![[Index]](../../../../a_stock/images/btn_index.gif)
![[Previous]](../../../../a_stock/images/btn_prev_top.gif)
![[Next]](../../../../a_stock/images/btn_next_top.gif)
![[Top]](../../../../a_stock/images/arrow_up_2.gif){kind=icon}
![[Previous]](../../../../a_stock/images/btn_prev.gif)
![[Top]](../../../../a_stock/images/btn_top.gif)
![[Next]](../../../../a_stock/images/btn_next.gif)