Class RMessage

RMessage

Support

Supported from 5.0

Description

An object which encapsulates a client request.

It is used on the server-side to communicate a client request to a server-side client session.

It contains the opcode specifying the client’s request and the message argument array - an array of four 32 bit parameters.

Depending on the client request, as identified by the opcode, the message argument array may contain pointers into the client-side address space, allowing data to be transferred from and to the client. The transfer of data is implemented using inter-thread communication.

Defined in RMessage:
Client(), Complete(), Function(), Int0(), Int1(), Int2(), Int3(), Kill(), MessagePtr(), Panic(), Ptr0(), Ptr1(), Ptr2(), Ptr3(), RMessage(), ReadL(), WriteL(), operator=()

See also:

• RThread

RMessage();

Description

Creates a default server-side message.

RMessage(const RMessage& aMessage);

Description

Copy constructor.

Parameters

const RMessage& aMessage The server-side message to be copied.

RMessage& operator=(const RMessage& aMessage);

Description

Assignment constructor.

Parameters

const RMessage& aMessage The server-side message to be assigned.

Return value

RMessage& A reference to this message

TInt Function() const;

Description

Returns the opcode specifying the client’s request.

Return value

TInt The opcode.

TInt Int0() const;

Description

Returns the first element in the message argument array as an integer.

Return value

TInt The first array element interpreted as an integer.

TInt Int1() const;

Description

Returns the second element in the message argument array as an integer.

Return value

TInt The second array element interpreted as an integer.

TInt Int2() const;

Description

Returns the third element in the message argument array as an integer.

Return value

TInt The third array element interpreted as an integer.

TInt Int3() const;

Description

Returns the fourth element in the message argument array as an integer.

Return value

TInt The fourth array element interpreted as an integer.

const TAny* Ptr0() const;

Description

Returns the first element in the message argument array as a pointer.

Return value

TAny* The first array element interpreted as a pointer.

const TAny* Ptr1() const;

Description

Returns the second element in the message argument array as a pointer.

Return value

TAny* The second array element interpreted as a pointer.

const TAny* Ptr2() const;

Description

Returns the third element in the message argument array as a pointer.

Return value

TAny* The third array element interpreted as a pointer.

const TAny* Ptr3() const;

Description

Returns the fourth element in the message argument array as a pointer.

Return value

TAny* The fourth array element interpreted as a pointer.

void Complete(TInt aReason) const;

Description

Signals completion of the client request.

Parameters

TInt aReason An integer or 32 bit value to be returned to the client. The meaning of this depends on the needs of the message. The system wide error codes, including KErrNone, may also be used.

void ReadL(const TAny* aPtr,TDes8& aDes) const;

Description

Copies data from the client thread’s address space into an 8 bit descriptor in the server address space.

The source data must be a valid descriptor.

Data is copied from the start of the source descriptor data area. The length of data copied is the length of the source descriptor.

The length of data copied is limited to the maximum length of the target descriptor.

Parameters

const TAny* aPtr A pointer to a valid address within the client thread’s address space. The data at this pointer must be a descriptor, i.e. a TDesC8 type. TDes8& aDes An 8 bit descriptor in the server address space. This is the target of the copy operation.

Leave codes

The function leaves with one of the system-wide error codes, if: the pointer in the client thread ’ s address space is not valid within that address space. the pointer in the client thread ’ s address space does not point to a valid descriptor.

void ReadL(const TAny* aPtr,TDes8& aDes,TInt anOffset) const;

Description

Copies data from the client thread’s address space into an 8 bit descriptor in the server address space.

The source data must be a valid descriptor.

Data is copied from the specified offset position within the source descriptor data area. The length of data copied is the length of source descriptor data minus the offset value. If the offset value is greater than the length of the source descriptor, then no data is copied.

The length of data copied is limited to the maximum length of the target descriptor.

Parameters

const TAny* aPtr A pointer to a valid address within the client thread’s address space. The data at this pointer must be a descriptor, i.e. a TDesC8 type. TDes8& aDes An 8 bit descriptor in the server address space. This is the target of the copy operation. TInt anOffset The offset from the start of the source descriptor data area from where copying is to begin. This value must be greater than or equal to zero.

Leave codes

The function leaves with one of the system-wide error codes, if: the offset value is negative the pointer in the client thread ’ s address space is not valid within that address space. the pointer in the client thread ’ s address space does not point to a valid descriptor.

void ReadL(const TAny* aPtr,TDes16& aDes) const;

Description

Copies data from the client thread’s address space into a 16 bit descriptor in the server address space.

The source data must be a valid descriptor.

Data is copied from the start of the source descriptor data area. The length of data copied is the length of the source descriptor.

The length of data copied is limited to the maximum length of the target descriptor.

Parameters

const TAny* aPtr A pointer to a valid address within the client thread’s address space. The data at this pointer must be a descriptor, i.e. a TDesC16 type. TDes16& aDes A 16 bit descriptor in the server address space. This is the target of the copy operation.

Leave codes

The function leaves with one of the system-wide error codes, if: the pointer in the client thread ’ s address space is not valid within that address space. the pointer in the client thread ’ s address space does not point to a valid descriptor.

void ReadL(const TAny* aPtr,TDes16& aDes,TInt anOffset) const;

Description

Copies data from the client thread’s address space into a 16 bit descriptor in the server address space.

The source data must be a valid descriptor.

Data is copied from the specified offset position within the source descriptor data area. The length of data copied is the length of source descriptor data minus the offset value. If the offset value is greater than the length of the source descriptor, then no data is copied.

The length of data copied is limited to the maximum length of the target descriptor.

Parameters

const TAny* aPtr A pointer to a valid address within the client thread’s address space. The data at this pointer must be a descriptor, i.e. a TDesC16 type. TDes16& aDes A 16 bit descriptor in the server address space. This is the target of the copy operation. TInt anOffset The offset from the start of the source descriptor data area from where copying is to begin. This value must be greater than or equal to zero.

Leave codes

The function leaves with one of the system-wide error codes, if: the offset value is negative the pointer in the client thread ’ s address space is not valid within that address space. the pointer in the client thread ’ s address space does not point to a valid descriptor.

void WriteL(const TAny* aPtr,const TDesC8& aDes) const;

Description

Copies data from an 8 bit descriptor in the server address space to the client thread’s address space.

The target location must be a valid modifiable descriptor.

Data is copied from the source descriptor to the data area of the target descriptor; the length of data copied is the length of the source descriptor.

The target descriptor in the client address space must be big enough to contain the data otherwise the function leaves; i.e. the target descriptor maximum length cannot be less than the length of the source descriptor.

Parameters

const TAny* aPtr A pointer to a valid address within the client thread’s address space. The data type at this location must be a modifiable descriptor, i.e. a TDes8 type. TDesC8& aDes An 8 bit descriptor in the server address space. This is the source of the copy operation.

Leave codes

The function leaves with one of the system-wide error codes, if: the pointer in the client thread ’ s address space is not valid within that address space. the pointer in the client thread ’ s address space does not point to a valid modifiable descriptor.

void WriteL(const TAny* aPtr,const TDesC8& aDes,TInt anOffset) const;

Description

Copies data from an 8 bit descriptor in the server address space to the client thread’s address space.

The target location must be a valid modifiable descriptor.

Data is copied from the source descriptor to the specified offset position within the target descriptor data area. The length of data copied is the length of the source descriptor. The length of the target descriptor is set to the length of the source descriptor plus the value of the offset.

The target descriptor in the client address space must be big enough to contain the data otherwise the function leaves; i.e. the target descriptor maximum length cannot be less than the sum of the source descriptor length plus the value of the offset.

Parameters

const TAny* aPtr A pointer to a valid address within the client thread’s address space. The data type at this location must be a modifiable descriptor, i.e. a TDes8 type. const TDesC8& aDes An 8 bit descriptor in the server address space. This is the source of the copy operation. TInt anOffset The offset from the start of the target descriptor data area where copying is to begin. This value must be greater than or equal to zero.

Leave codes

The function leaves with one of the system-wide error codes, if: the offset value is negative the pointer in the client thread ’ s address space is not valid within that address space. the pointer in the client thread ’ s address space does not point to a valid modifiable descriptor. there is insufficient space in the target descriptor in the client thread ’ s address space.

void WriteL(const TAny* aPtr,const TDesC16& aDes) const;

Description

Copies data from a 16 bit descriptor in the server address space to the client thread’s address space.

The target location must be a valid modifiable descriptor.

Data is copied from the source descriptor to the data area of the target descriptor; the length of data copied is the length of the source descriptor.

The target descriptor in the client address space must be big enough to contain the data otherwise the function leaves; i.e. the target descriptor maximum length cannot be less than the length of the source descriptor.

Parameters

const TAny* aPtr A pointer to a valid address within the client thread’s address space. The data type at this location must be a modifiable descriptor, i.e. a TDes16 type. TDesC16& aDes A 16 bit descriptor in the server address space. This is the source of the copy operation.

Leave codes

The function leaves with one of the system-wide error codes, if: the pointer in the client thread ’ s address space is not valid within that address space. the pointer in the client thread ’ s address space does not point to a valid modifiable descriptor.

void WriteL(const TAny* aPtr,const TDesC16& aDes,TInt anOffset) const;

Description

Copies data from a 16 bit descriptor in the server address space to the client thread’s address space.

The target location must be a valid modifiable descriptor.

Data is copied from the source descriptor to the specified offset position within the target descriptor data area. The length of data copied is the length of the source descriptor. The length of the target descriptor is set to the length of the source descriptor plus the value of the offset.

The target descriptor in the client address space must be big enough to contain the data otherwise the function leaves; i.e. the target descriptor maximum length cannot be less than the sum of the source descriptor length plus the value of the offset.

Parameters

const TAny* aPtr A pointer to a valid address within the client thread’s address space. The data type at this location must be a modifiable descriptor, i.e. a TDes16 type. const TDesC16& aDes A 16 bit descriptor in the server address space. This is the source of the copy operation. TInt anOffset The offset from the start of the target descriptor data area where copying is to begin. This value must be greater than or equal to zero.

Leave codes

The function leaves with one of the system-wide error codes, if: the offset value is negative the pointer in the client thread ’ s address space is not valid within that address space. the pointer in the client thread ’ s address space does not point to a valid modifiable descriptor. there is insufficient space in the target descriptor in the client thread ’ s address space.

const RThread& Client() const;

Description

Returns the client thread associated with this session.

Return value

RThread& The client thread.

const RMessagePtr MessagePtr() const;

Description

Returns this RMessage object cast as a RMessagePtr type.

Return value

RMessagePtr This object cast as a RMessagePtr type.

void Panic(const TDesC& aCategory,TInt aReason) const;

Description

Panics the client thread associated with this session and completes the client request.

Parameters

const TDesC& aCategory Text specifying the panic category name. TInt aReason The panic number.

See also:

• RThread::Panic()

void Kill(TInt aReason) const;

Description

Ends the client thread associated with this session and completes the client request.

Parameters

TInt aReason The reason associated with the ending of the client thread.

See also:

• RThread::Kill()