RMessagePtr2 Class Reference

#include <e32cmn.h>

class RMessagePtr2
Protected Attributes
TInt iHandle
Public Member Functions
RMessagePtr2()
IMPORT_C TIntClient(RThread &, TOwnerType)
IMPORT_C TBoolClientIsRealtime()
voidClientL(RThread &, TOwnerType)
IMPORT_C TUintClientProcessFlags()
IMPORT_C const TRequestStatus *ClientStatus()
IMPORT_C voidComplete(TInt)
IMPORT_C voidComplete(RHandleBase)
IMPORT_C TIntGetDesLength(TInt)
IMPORT_C TIntGetDesLengthL(TInt)
IMPORT_C TIntGetDesMaxLength(TInt)
IMPORT_C TIntGetDesMaxLengthL(TInt)
TInt Handle()
TBool HasCapability(TCapability, const char *)
TBool HasCapability(TCapability, TCapability, const char *)
voidHasCapabilityL(TCapability, const char *)
voidHasCapabilityL(TCapability, TCapability, const char *)
TUid Identity()
TBool IsNull()
IMPORT_C voidKill(TInt)
IMPORT_C voidPanic(const TDesC &, TInt)
IMPORT_C TIntRead(TInt, TDes8 &, TInt)
IMPORT_C TIntRead(TInt, TDes16 &, TInt)
IMPORT_C voidReadL(TInt, TDes8 &, TInt)
IMPORT_C voidReadL(TInt, TDes16 &, TInt)
IMPORT_C TSecureIdSecureId()
IMPORT_C TIntSetProcessPriority(TProcessPriority)
voidSetProcessPriorityL(TProcessPriority)
IMPORT_C voidTerminate(TInt)
IMPORT_C TVendorIdVendorId()
IMPORT_C TIntWrite(TInt, const TDesC8 &, TInt)
IMPORT_C TIntWrite(TInt, const TDesC16 &, TInt)
IMPORT_C voidWriteL(TInt, const TDesC8 &, TInt)
IMPORT_C voidWriteL(TInt, const TDesC16 &, TInt)

Detailed 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.

See also: RMessage2

Member Attribute Documentation

iHandle

TInt iHandle[protected]

Constructor & Destructor Documentation

RMessagePtr2 ( )

RMessagePtr2()[inline]

Default constructor

Member Function Documentation

Client ( RThread &, TOwnerType )

IMPORT_C TIntClient(RThread &aClient,
TOwnerTypeaOwnerType = EOwnerProcess
)const

Opens a handle on the client thread.

Parameters
aClientOn successful return, the handle to the client thread.
aOwnerTypeAn enumeration whose enumerators define the ownership of the handle. If not explicitly specified, EOwnerProcess is taken as default.
Return Value
KErrNone.

ClientIsRealtime ( )

IMPORT_C TBoolClientIsRealtime()const

ClientL ( RThread &, TOwnerType )

voidClientL(RThread &aClient,
TOwnerTypeaOwnerType = EOwnerProcess
)const [inline]

Opens a handle on the client thread.

Parameters
aClientOn successful return, the handle to the client thread.
aOwnerTypeAn enumeration whose enumerators define the ownership of the handle. If not explicitly specified, EOwnerProcess is taken as default.

ClientProcessFlags ( )

IMPORT_C TUintClientProcessFlags()const

ClientStatus ( )

IMPORT_C const TRequestStatus *ClientStatus()const

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
The clients TRequestStatus (returns NULL if the request is not asynchronous)

Complete ( TInt )

IMPORT_C voidComplete(TIntaReason)const

Frees this message.

Parameters
aReasonThe completion code.

Complete ( RHandleBase )

IMPORT_C voidComplete(RHandleBaseaHandle)const

Duplicates the specified handle in the client thread, and returns this handle as a message completion code

Parameters
aHandleThe handle to be duplicated.

GetDesLength ( TInt )

IMPORT_C TIntGetDesLength(TIntaParam)const

Gets the length of a descriptor argument in the client's process.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
Return Value
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.

GetDesLengthL ( TInt )

IMPORT_C TIntGetDesLengthL(TIntaParam)const

Gets the length of a descriptor argument in the client's process, leaving on failure.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
Return Value
The length of the descriptor.
Leave Codes
KErrArgumentif aParam has a value outside the valid range.
KErrBadDescriptor,if the message argument is not a descriptor type.

GetDesMaxLength ( TInt )

IMPORT_C TIntGetDesMaxLength(TIntaParam)const

Gets the maximum length of a descriptor argument in the client's process.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
Return Value
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 )

IMPORT_C TIntGetDesMaxLengthL(TIntaParam)const

Gets the maximum length of a descriptor argument in the client's process, leaving on failure.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
Return Value
The length of the descriptor.
Leave Codes
KErrArgumentif aParam has a value outside the valid range.
KErrBadDescriptor,if the message argument is not a descriptor type.

Handle ( )

TInt Handle()const [inline]

Gets the message handle value.

Return Value
The message handle value.

HasCapability ( TCapability, const char * )

TBool HasCapability(TCapabilityaCapability,
const char *aDiagnostic = 0
)const [inline]

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
aCapabilityThe capability to test.
aDiagnosticA 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
ETrue if process which sent this message has the capability, EFalse otherwise.

HasCapability ( TCapability, TCapability, const char * )

TBool HasCapability(TCapabilityaCapability1,
TCapabilityaCapability2,
const char *aDiagnostic = 0
)const [inline]

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
aCapability1The first capability to test.
aCapability2The second capability to test.
aDiagnosticA 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
ETrue if the process which sent this message has both the capabilities, EFalse otherwise.

HasCapabilityL ( TCapability, const char * )

voidHasCapabilityL(TCapabilityaCapability,
const char *aDiagnosticMessage = 0
)const [inline]

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
aCapabilityThe capability to test.
aDiagnosticMessageA 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.

HasCapabilityL ( TCapability, TCapability, const char * )

voidHasCapabilityL(TCapabilityaCapability1,
TCapabilityaCapability2,
const char *aDiagnosticMessage = 0
)const [inline]

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
aCapability1The first capability to test.
aCapability2The second capability to test.
aDiagnosticMessageA 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.

Identity ( )

TUid Identity()const [inline]

DeprecatedUse SecureId()

IsNull ( )

TBool IsNull()const [inline]

Tests whether this message handle is empty.

Return Value
True, if this message handle is empty, false, otherwise.

Kill ( TInt )

IMPORT_C voidKill(TIntaReason)const

Kills the client.

Note that this method also completes the message. A subsequent call to Complete(TInt aReason) would cause a server panic.

Parameters
aReasonThe reason code associated with killing the client.

Panic ( const TDesC &, TInt )

IMPORT_C voidPanic(const TDesC &aCategory,
TIntaReason
)const

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
aCategoryThe panic category.
aReasonThe panic code.

Read ( TInt, TDes8 &, TInt )

IMPORT_C TIntRead(TIntaParam,
TDes8 &aDes,
TIntaOffset = 0
)const

Reads data from the specified offset within the 8-bit descriptor argument, into the specified target descriptor.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDesThe target descriptor into which the client data is to be written.
aOffsetThe offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.
Return Value
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 )

IMPORT_C TIntRead(TIntaParam,
TDes16 &aDes,
TIntaOffset = 0
)const

Reads data from the specified offset within the 16-bit descriptor argument, into the specified target descriptor.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDesThe target descriptor into which the client data is to be written.
aOffsetThe offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.
Return Value
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.

ReadL ( TInt, TDes8 &, TInt )

IMPORT_C voidReadL(TIntaParam,
TDes8 &aDes,
TIntaOffset = 0
)const

Reads data from the specified offset within the 8-bit descriptor argument, into the specified target descriptor, and leaving on failure.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDesThe target descriptor into which the client data is to be written.
aOffsetThe offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.
Leave Codes
KErrArgumentif 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 )

IMPORT_C voidReadL(TIntaParam,
TDes16 &aDes,
TIntaOffset = 0
)const

Reads data from the specified offset within the 16-bit descriptor argument, into the specified target descriptor, and leaving on failure.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDesThe target descriptor into which the client data is to be written.
aOffsetThe offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.
Leave Codes
KErrArgumentif aParam has a value outside the valid range, or if aOffset is negative.
KErrBadDescriptor,if the message argument is not a 16-bit descriptor.

SecureId ( )

IMPORT_C TSecureIdSecureId()const

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);
		TBool pass = mySidPolicy().CheckPolicy(message);

This has the benefit that the TSecurityPolicy::CheckPolicy 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.

See also: TSecurityPolicy::CheckPolicy(RMessagePtr2 aMsgPtr, const char* aDiagnostic) const _LIT_SECURITY_POLICY_S0

Return Value
The Secure ID.

SetProcessPriority ( TProcessPriority )

IMPORT_C TIntSetProcessPriority(TProcessPriorityaPriority)const

Sets the priority of the client's process.

Parameters
aPriorityThe priority value.
Return Value
KErrNone, if successful, otherwise one of the other system-wide error codes.

SetProcessPriorityL ( TProcessPriority )

voidSetProcessPriorityL(TProcessPriorityaPriority)const [inline]

Sets the priority of the client's process.

Parameters
aPriorityThe priority value.

Terminate ( TInt )

IMPORT_C voidTerminate(TIntaReason)const

Terminates the client.

Note that this method also completes the message. A subsequent call to Complete(TInt aReason) would cause a server panic.

Parameters
aReasonThe reason code associated with terminating the client.

VendorId ( )

IMPORT_C TVendorIdVendorId()const

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);
		TBool pass = myVidPolicy().CheckPolicy(message);

This has the benefit that the TSecurityPolicy::CheckPolicy 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.

See also: TSecurityPolicy::CheckPolicy(RMessagePtr2 aMsgPtr, const char* aDiagnostic) const _LIT_SECURITY_POLICY_V0

Return Value
The Vendor ID.

Write ( TInt, const TDesC8 &, TInt )

IMPORT_C TIntWrite(TIntaParam,
const TDesC8 &aDes,
TIntaOffset = 0
)const

Writes data from the specified source descriptor to the specified offset within the 8-bit descriptor argument.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDesThe source descriptor containing the data to be written.
aOffsetThe offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.
Return Value
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 )

IMPORT_C TIntWrite(TIntaParam,
const TDesC16 &aDes,
TIntaOffset = 0
)const

Writes data from the specified source descriptor to the specified offset within the 16-bit descriptor argument.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDesThe source descriptor containing the data to be written.
aOffsetThe offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.
Return Value
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.

WriteL ( TInt, const TDesC8 &, TInt )

IMPORT_C voidWriteL(TIntaParam,
const TDesC8 &aDes,
TIntaOffset = 0
)const

Writes data from the specified source descriptor to the specified offset within the 8-bit descriptor argument, and leaving on failure.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDesThe source descriptor containing the data to be written.
aOffsetThe offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.
Leave Codes
KErrArgumentif 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 )

IMPORT_C voidWriteL(TIntaParam,
const TDesC16 &aDes,
TIntaOffset = 0
)const

Writes data from the specified source descriptor to the specified offset within the 16-bit descriptor argument, and leaving on failure.

Parameters
aParamThe index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDesThe source descriptor containing the data to be written.
aOffsetThe offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.
Leave Codes
KErrArgumentif aParam has a value outside the valid range, or if aOffset is negative.
KErrBadDescriptor,if the message argument is not a 16-bit descriptor.