Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: e32cmn.h
Link against: euser.lib

Class RMessagePtr2

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(), ClientL(), ClientProcessFlags(), ClientStatus(), Complete(), Complete(), GetDesLength(), GetDesLengthL(), GetDesMaxLength(), GetDesMaxLengthL(), Handle(), HasCapability(), HasCapability(), HasCapabilityL(), HasCapabilityL(), Identity(), IsNull(), Kill(), Panic(), RMessagePtr2(), Read(), Read(), ReadL(), ReadL(), SecureId(), SetProcessPriority(), SetProcessPriorityL(), Terminate(), VendorId(), Write(), Write(), WriteL(), WriteL(), iHandle

See also:


Construction and destruction


RMessagePtr2()

inline RMessagePtr2();

Description

Default constructor

[Top]


Member functions


IsNull()

inline TBool IsNull() const;

Description

Tests whether this message handle is empty.

Return value

TBool

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


Handle()

inline TInt Handle() const;

Description

Gets the message handle value.

Return value

TInt

The message handle value.


Complete()

IMPORT_C void Complete(TInt aReason) const;

Description

Frees this message.

Parameters

TInt aReason

The completion code.


Complete()

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

RHandleBase aHandle

The handle to be duplicated.


GetDesLength()

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.


GetDesLengthL()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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.

Parameters

const TDesC &aCategory

The panic category.

TInt aReason

The panic code.


Kill()

IMPORT_C void Kill(TInt aReason) const;

Description

Kills the client.

Parameters

TInt aReason

The reason code associated with killing the client.


Terminate()

IMPORT_C void Terminate(TInt aReason) const;

Description

Terminates the client.

Parameters

TInt aReason

The reason code associated with terminating the client.


SetProcessPriority()

IMPORT_C TInt SetProcessPriority(TProcessPriority aPriority) const;

Description

Sets the priority of the client's process.

Parameters

TProcessPriority aPriority

The priority value.

Return value

TInt

KErrNone, if successful, otherwise one of the other system-wide error codes.


SetProcessPriorityL()

inline void SetProcessPriorityL(TProcessPriority aPriority) const;

Description

Sets the priority of the client's process.

Parameters

TProcessPriority aPriority

The priority value.


Client()

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

TInt

KErrNone.


ClientL()

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()

IMPORT_C TUint ClientProcessFlags() const;

Description

Return value

TUint


ClientStatus()

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

const TRequestStatus *

The clients TRequestStatus (returns NULL if the request is not asynchronous)


SecureId()

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

TSecureId

The Secure ID.


VendorId()

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

TVendorId

The Vendor ID.


HasCapability()

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()

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()

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()

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.


Identity()

inline TUid Identity() const;

Description

Return value

TUid

[Top]


Member data


iHandle

protected: TInt iHandle;

Description