A handle to a message sent by the client to the server. More...

#include <e32cmn.h>

Inheritance diagram for RMessagePtr2:

Public Member Functions
	RMessagePtr2 ()
	Default constructor.

TBool	IsNull () const
	Tests whether this message handle is empty.

TInt	Handle () const
	Gets the message handle value.

IMPORT_C void	Complete (TInt aReason) const
	Frees this message.

IMPORT_C void	Complete (RHandleBase aHandle) const
	Duplicates the specified handle in the client thread, and returns this handle as a message completion code.

IMPORT_C TInt	GetDesLength (TInt aParam) const
	Gets the length of a descriptor argument in the client's process.

IMPORT_C TInt	GetDesLengthL (TInt aParam) const
	Gets the length of a descriptor argument in the client's process, leaving on failure.

IMPORT_C TInt	GetDesMaxLength (TInt aParam) const
	Gets the maximum length of a descriptor argument in the client's process.

IMPORT_C TInt	GetDesMaxLengthL (TInt aParam) const
	Gets the maximum length of a descriptor argument in the client's process, leaving on failure.

IMPORT_C void	ReadL (TInt aParam, TDes8 &aDes, TInt aOffset=0) const
	Reads data from the specified offset within the 8-bit descriptor argument, into the specified target descriptor, and leaving on failure.

IMPORT_C void	ReadL (TInt aParam, TDes16 &aDes, TInt aOffset=0) const
	Reads data from the specified offset within the 16-bit descriptor argument, into the specified target descriptor, and leaving on failure.

IMPORT_C void	WriteL (TInt aParam, const TDesC8 &aDes, TInt aOffset=0) const
	Writes data from the specified source descriptor to the specified offset within the 8-bit descriptor argument, and leaving on failure.

IMPORT_C void	WriteL (TInt aParam, const TDesC16 &aDes, TInt aOffset=0) const
	Writes data from the specified source descriptor to the specified offset within the 16-bit descriptor argument, and leaving on failure.

IMPORT_C TInt	Read (TInt aParam, TDes8 &aDes, TInt aOffset=0) const
	Reads data from the specified offset within the 8-bit descriptor argument, into the specified target descriptor.

IMPORT_C TInt	Read (TInt aParam, TDes16 &aDes, TInt aOffset=0) const
	Reads data from the specified offset within the 16-bit descriptor argument, into the specified target descriptor.

IMPORT_C TInt	Write (TInt aParam, const TDesC8 &aDes, TInt aOffset=0) const
	Writes data from the specified source descriptor to the specified offset within the 8-bit descriptor argument.

IMPORT_C TInt	Write (TInt aParam, const TDesC16 &aDes, TInt aOffset=0) const
	Writes data from the specified source descriptor to the specified offset within the 16-bit descriptor argument.

IMPORT_C void	Panic (const TDesC &aCategory, TInt aReason) const
	Panics the client.

IMPORT_C void	Kill (TInt aReason) const
	Kills the client.

IMPORT_C void	Terminate (TInt aReason) const
	Terminates the client.

IMPORT_C TInt	SetProcessPriority (TProcessPriority aPriority) const
	Sets the priority of the client's process.

void	SetProcessPriorityL (TProcessPriority aPriority) const
	Sets the priority of the client's process.

IMPORT_C TInt	Client (RThread &aClient, TOwnerType aOwnerType=EOwnerProcess) const
	Opens a handle on the client thread.

void	ClientL (RThread &aClient, TOwnerType aOwnerType=EOwnerProcess) const
	Opens a handle on the client thread.

IMPORT_C TUint	ClientProcessFlags () const

IMPORT_C const TRequestStatus *	ClientStatus () const
	Returns the pointer to the clients TRequestStatus associated with the message.

IMPORT_C TBool	ClientIsRealtime () const

IMPORT_C TSecureId	SecureId () const

IMPORT_C TVendorId	VendorId () const

TBool	HasCapability (TCapability aCapability, const char *aDiagnostic=0) const

void	HasCapabilityL (TCapability aCapability, const char *aDiagnosticMessage=0) const

TBool	HasCapability (TCapability aCapability1, TCapability aCapability2, const char *aDiagnostic=0) const

void	HasCapabilityL (TCapability aCapability1, TCapability aCapability2, const char *aDiagnosticMessage=0) const

TUid	Identity () const

Protected Attributes
TInt	iHandle

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

API status: Published to all clients. Released API.

Definition at line 3205 of file e32cmn.h.

Constructor & Destructor Documentation

◆ RMessagePtr2()

RMessagePtr2::RMessagePtr2 ( )

inline

Default constructor.

(generated from Symbian Developer Library)

Member Function Documentation

◆ Client()

IMPORT_C TInt RMessagePtr2::Client	(	RThread &	aClient,
		TOwnerType	aOwnerType = `EOwnerProcess`
	)		const

Opens a handle on the client thread.

Parameters

aClient	On successful return, the handle to the client thread.
aOwnerType	An enumeration whose enumerators define the ownership of the handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ ClientIsRealtime()

IMPORT_C TBool RMessagePtr2::ClientIsRealtime ( ) const

◆ ClientL()

void RMessagePtr2::ClientL	(	RThread &	aClient,
		TOwnerType	aOwnerType = `EOwnerProcess`
	)		const

inline

Opens a handle on the client thread.

Parameters

aClient	On successful return, the handle to the client thread.
aOwnerType	An enumeration whose enumerators define the ownership of the handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ ClientProcessFlags()

IMPORT_C TUint RMessagePtr2::ClientProcessFlags ( ) const

◆ ClientStatus()

IMPORT_C const TRequestStatus * RMessagePtr2::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.

(generated from Symbian Developer Library)

◆ Complete() [1/2]

IMPORT_C void RMessagePtr2::Complete ( RHandleBase aHandle ) const

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

Parameters

aHandle The handle to be duplicated.

(generated from Symbian Developer Library)

◆ Complete() [2/2]

IMPORT_C void RMessagePtr2::Complete ( TInt aReason ) const

Frees this message.

Parameters

aReason The completion code.

(generated from Symbian Developer Library)

◆ GetDesLength()

IMPORT_C TInt RMessagePtr2::GetDesLength ( TInt aParam ) const

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

Parameters

aParam The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.

(generated from Symbian Developer Library)

◆ GetDesLengthL()

IMPORT_C TInt RMessagePtr2::GetDesLengthL ( TInt aParam ) const

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

Parameters

aParam The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.

Leave condition: KErrArgument if aParam has a value outside the valid range.

Leave condition: KErrBadDescriptor, if the message argument is not a descriptor type.

(generated from Symbian Developer Library)

◆ GetDesMaxLength()

IMPORT_C TInt RMessagePtr2::GetDesMaxLength ( TInt aParam ) const

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

Parameters

aParam The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.

(generated from Symbian Developer Library)

◆ GetDesMaxLengthL()

IMPORT_C TInt RMessagePtr2::GetDesMaxLengthL ( TInt aParam ) const

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

Parameters

aParam The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.

Leave condition: KErrArgument if aParam has a value outside the valid range.

Leave condition: KErrBadDescriptor, if the message argument is not a descriptor type.

(generated from Symbian Developer Library)

◆ Handle()

TInt RMessagePtr2::Handle ( ) const

inline

Gets the message handle value.

(generated from Symbian Developer Library)

◆ HasCapability() [1/2]

TBool RMessagePtr2::HasCapability	(	TCapability	aCapability,
		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.

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

API status: Published to all clients. Released API.

Parameters

aCapability	The capability to test.
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.

(generated from Symbian Developer Library)

◆ HasCapability() [2/2]

TBool RMessagePtr2::HasCapability	(	TCapability	aCapability1,
		TCapability	aCapability2,
		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.

@param aCapability1 The first capability to test.
@param aCapability2 The second capability to test.
@param 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 ETrue if the process which sent this message has both the capabilities, EFalse otherwise.

API status: Published to all clients. Released API.

Parameters

aCapability1	The first capability to test.
aCapability2	The second capability to test.
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.

(generated from Symbian Developer Library)

◆ HasCapabilityL() [1/2]

void RMessagePtr2::HasCapabilityL	(	TCapability	aCapability,
		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.

@param aCapability The capability to test.
@param 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 condition: KErrPermissionDenied, if the process does not have the capability.

API status: Published to all clients. Released API.

Parameters

aCapability	The capability to test.
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.

(generated from Symbian Developer Library)

◆ HasCapabilityL() [2/2]

void RMessagePtr2::HasCapabilityL	(	TCapability	aCapability1,
		TCapability	aCapability2,
		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.

@param aCapability1 The first capability to test.
@param aCapability2 The second capability to test.
@param 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 condition: KErrPermissionDenied, if the process does not have the capabilities.

API status: Published to all clients. Released API.

Parameters

aCapability1	The first capability to test.
aCapability2	The second capability to test.
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.

(generated from Symbian Developer Library)

◆ Identity()

TUid RMessagePtr2::Identity ( ) const

inline

Deprecated:: Use SecureId()

Definition at line 3436 of file e32cmn.h.

◆ IsNull()

TBool RMessagePtr2::IsNull ( ) const

inline

Tests whether this message handle is empty.

(generated from Symbian Developer Library)

◆ Kill()

IMPORT_C void RMessagePtr2::Kill ( TInt aReason ) 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

aReason The reason code associated with killing the client.

(generated from Symbian Developer Library)

◆ Panic()

IMPORT_C void RMessagePtr2::Panic	(	const TDesC &	aCategory,
		TInt	aReason
	)		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

aCategory	The panic category.
aReason	The panic code.

(generated from Symbian Developer Library)

◆ Read() [1/2]

IMPORT_C TInt RMessagePtr2::Read	(	TInt	aParam,
		TDes16 &	aDes,
		TInt	aOffset = `0`
	)		const

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

Parameters

aParam	The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDes	The target descriptor into which the client data is to be written.
aOffset	The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.

(generated from Symbian Developer Library)

◆ Read() [2/2]

IMPORT_C TInt RMessagePtr2::Read	(	TInt	aParam,
		TDes8 &	aDes,
		TInt	aOffset = `0`
	)		const

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

Parameters

aParam	The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDes	The target descriptor into which the client data is to be written.
aOffset	The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.

(generated from Symbian Developer Library)

◆ ReadL() [1/2]

IMPORT_C void RMessagePtr2::ReadL	(	TInt	aParam,
		TDes16 &	aDes,
		TInt	aOffset = `0`
	)		const

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

Parameters

aParam	The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDes	The target descriptor into which the client data is to be written.
aOffset	The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.

Leave condition: KErrArgument if aParam has a value outside the valid range, or if aOffset is negative.

Leave condition: KErrBadDescriptor, if the message argument is not a 16-bit descriptor.

(generated from Symbian Developer Library)

◆ ReadL() [2/2]

IMPORT_C void RMessagePtr2::ReadL	(	TInt	aParam,
		TDes8 &	aDes,
		TInt	aOffset = `0`
	)		const

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

Parameters

aParam	The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDes	The target descriptor into which the client data is to be written.
aOffset	The offset from the start of the client's descriptor data. If not explicitly specified, the offset defaults to zero.

Leave condition: KErrArgument if aParam has a value outside the valid range, or if aOffset is negative.

Leave condition: KErrBadDescriptor, if the message argument is not an 8-bit descriptor.

(generated from Symbian Developer Library)

◆ SecureId()

IMPORT_C TSecureId RMessagePtr2::SecureId ( ) 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:

@code
RMessagePtr2 & message;
TInt error =
    message.SecureId() == KRequiredSecureId ? KErrNone : KErrPermissionDenied;
@endcode

this could be used;

@code
RMessagePtr2 & message;
static _LIT_SECURITY_POLICY_S0(mySidPolicy, KRequiredSecureId);
TBool pass = mySidPolicy().CheckPolicy(message);
@endcode

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 TSecurityPolicy::CheckPolicy(RMessagePtr2 aMsgPtr, const char* aDiagnostic) const
@see _LIT_SECURITY_POLICY_S0

@return The Secure ID.

API status: Published to all clients. Released API.

◆ SetProcessPriority()

IMPORT_C TInt RMessagePtr2::SetProcessPriority ( TProcessPriority aPriority ) const

Sets the priority of the client's process.

Parameters

aPriority The priority value.

(generated from Symbian Developer Library)

◆ SetProcessPriorityL()

void RMessagePtr2::SetProcessPriorityL ( TProcessPriority aPriority ) const

inline

Sets the priority of the client's process.

Parameters

aPriority The priority value.

(generated from Symbian Developer Library)

◆ Terminate()

IMPORT_C void RMessagePtr2::Terminate ( TInt aReason ) 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

aReason The reason code associated with terminating the client.

(generated from Symbian Developer Library)

◆ VendorId()

IMPORT_C TVendorId RMessagePtr2::VendorId ( ) 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:

@code
RMessagePtr2 & message;
TInt error =
    message.VendorId() == KRequiredVendorId ? KErrNone : KErrPermissionDenied;
@endcode

this could be used;

@code
RMessagePtr2 & message;
static _LIT_SECURITY_POLICY_V0(myVidPolicy, KRequiredVendorId);
TBool pass = myVidPolicy().CheckPolicy(message);
@endcode

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 TSecurityPolicy::CheckPolicy(RMessagePtr2 aMsgPtr, const char* aDiagnostic) const
@see _LIT_SECURITY_POLICY_V0

@return The Vendor ID.

API status: Published to all clients. Released API.

◆ Write() [1/2]

IMPORT_C TInt RMessagePtr2::Write	(	TInt	aParam,
		const TDesC16 &	aDes,
		TInt	aOffset = `0`
	)		const

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

Parameters

aParam	The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDes	The source descriptor containing the data to be written.
aOffset	The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.

(generated from Symbian Developer Library)

◆ Write() [2/2]

IMPORT_C TInt RMessagePtr2::Write	(	TInt	aParam,
		const TDesC8 &	aDes,
		TInt	aOffset = `0`
	)		const

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

Parameters

aParam	The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDes	The source descriptor containing the data to be written.
aOffset	The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.

(generated from Symbian Developer Library)

◆ WriteL() [1/2]

IMPORT_C void RMessagePtr2::WriteL	(	TInt	aParam,
		const TDesC16 &	aDes,
		TInt	aOffset = `0`
	)		const

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

Parameters

aParam	The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDes	The source descriptor containing the data to be written.
aOffset	The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.

Leave condition: KErrArgument if aParam has a value outside the valid range, or if aOffset is negative.

Leave condition: KErrBadDescriptor, if the message argument is not a 16-bit descriptor.

(generated from Symbian Developer Library)

◆ WriteL() [2/2]

IMPORT_C void RMessagePtr2::WriteL	(	TInt	aParam,
		const TDesC8 &	aDes,
		TInt	aOffset = `0`
	)		const

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

Parameters

aParam	The index value identifying the argument. This is a value in the range 0 to (KMaxMessageArguments-1) inclusive.
aDes	The source descriptor containing the data to be written.
aOffset	The offset from the start of the client's descriptor. If not explicitly specified, the offset defaults to zero.

Leave condition: KErrArgument if aParam has a value outside the valid range, or if aOffset is negative.

Leave condition: KErrBadDescriptor, if the message argument is not an 8-bit descriptor.

(generated from Symbian Developer Library)

Member Data Documentation

◆ iHandle

TInt RMessagePtr2::iHandle

protected

Definition at line 3447 of file e32cmn.h.

The documentation for this class was generated from the following files:

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RMessagePtr2()

Member Function Documentation

◆ Client()

◆ ClientIsRealtime()

◆ ClientL()

◆ ClientProcessFlags()

◆ ClientStatus()

◆ Complete() [1/2]

◆ Complete() [2/2]

◆ GetDesLength()

◆ GetDesLengthL()

◆ GetDesMaxLength()

◆ GetDesMaxLengthL()

◆ Handle()

◆ HasCapability() [1/2]

◆ HasCapability() [2/2]

◆ HasCapabilityL() [1/2]

◆ HasCapabilityL() [2/2]

◆ Identity()

◆ IsNull()

◆ Kill()

◆ Panic()

◆ Read() [1/2]

◆ Read() [2/2]

◆ ReadL() [1/2]

◆ ReadL() [2/2]

◆ SecureId()

◆ SetProcessPriority()

◆ SetProcessPriorityL()

◆ Terminate()

◆ VendorId()

◆ Write() [1/2]

◆ Write() [2/2]

◆ WriteL() [1/2]

◆ WriteL() [2/2]

Member Data Documentation

◆ iHandle