Collapse all Symbian^3 Product Developer Library

RMsgQueueBase Class Reference

class RMsgQueueBase : public RHandleBase

Provides implementation for managing an asynchronous message queue, and is a base class for the RMsgQueue templated class.

RMsgQueue

Inherits from

RMsgQueueBase
- RHandleBase

Public Member Functions
IMPORT_C void	CancelDataAvailable()
IMPORT_C void	CancelSpaceAvailable()
IMPORT_C TInt	CreateGlobal(const TDesC &, TInt, TInt, TOwnerType)
IMPORT_C TInt	CreateLocal(TInt, TInt, TOwnerType)
IMPORT_C TInt	MessageSize()
IMPORT_C void	NotifyDataAvailable(TRequestStatus &)
IMPORT_C void	NotifySpaceAvailable(TRequestStatus &)
IMPORT_C TInt	Open(RMessagePtr2, TInt, TOwnerType)
IMPORT_C TInt	Open(TInt, TOwnerType)
IMPORT_C TInt	OpenGlobal(const TDesC &, TOwnerType)
IMPORT_C TInt	Receive(TAny *, TInt)
IMPORT_C void	ReceiveBlocking(TAny *, TInt)
IMPORT_C TInt	Send(const TAny *, TInt)
IMPORT_C void	SendBlocking(const TAny *, TInt)

Inherited Functions
	RHandleBase::Attributes()const
	RHandleBase::BTraceId()const
	RHandleBase::Close()
	RHandleBase::DoExtendedClose()
	RHandleBase::Duplicate(const RThread &,TOwnerType)
	RHandleBase::FullName()const
	RHandleBase::FullName(TDes &)const
	RHandleBase::Handle()const
	RHandleBase::HandleInfo(THandleInfo *)
	RHandleBase::Name()const
	RHandleBase::NotifyDestruction(TRequestStatus &)
	RHandleBase::Open(const TFindHandleBase &,TOwnerType)
	RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
	RHandleBase::RHandleBase()
	RHandleBase::RHandleBase(TInt)
	RHandleBase::SetHandle(TInt)
	RHandleBase::SetHandleNC(TInt)
	RHandleBase::SetReturnedHandle(TInt)
	RHandleBase::SetReturnedHandle(TInt,RHandleBase &)

Inherited Enumerations
	RHandleBase:TAttributes

Inherited Attributes
	RHandleBase::iHandle

Member Functions Documentation

CancelDataAvailable()

IMPORT_C void

CancelDataAvailable

(

)

Cancels an outstanding data available notification request.

If the request is not already complete, then it now completes with KErrCancel.

panic: KERN-EXEC 50 if attempting to cancel an outstanding request made by a thread in a different process.

RMsgQueueBase::NotifyDataAvailable

CancelSpaceAvailable()

IMPORT_C void

CancelSpaceAvailable

(

)

Cancels an outstanding space available notification request.

If the request is not already complete, then it now completes with KErrCancel.

panic: KERN-EXEC 50 if attempting to cancel an outstanding request made by a thread in a different process.

RMsgQueueBase::NotifySpaceAvailable

CreateGlobal(const TDesC &, TInt, TInt, TOwnerType)

IMPORT_C TInt	CreateGlobal	(	const TDesC &	aName,
			TInt	aSize,
			TInt	aMsgLength,
			TOwnerType	aType = EOwnerProcess
		)

Creates a global message queue, and opens a handle to that message queue.

The kernel side object representing the message queue is given the name contained in the specified descriptor, which makes it global, i.e. it is visible to all processes. This means that any thread in any process can search for the message queue, and open a handle to it. If the specified name is empty the kernel side object representing the message queue is unnamed and so cannot be opened by name or searched for. It can however be passed to another process as a process parameter or via IPC.

By default, any thread in the process can use this handle to access the message queue. However, specifying EOwnerThread as the fourth parameter to this function, means that only the creating thread can use this handle to access the message queue; any other thread in this process that wants to access the message queue must either duplicate this handle or use OpenGlobal().

panic: KERN-EXEC 49 if aSize is less than or equal to zero.

panic: KERN-EXEC 48 if aMsgLength is not a multiple of 4 bytes, is less than 4, or is greater than KMaxLength.

KMaxLength RMsgQueueBase::OpenGlobal

Parameters

const TDesC & aName	The name to be assigned to the message queue
TInt aSize	The number of message 'slots' in the queue. This must be a positive value, i.e. greater than zero.
TInt aMsgLength	The size of each message for the queue, this cannot exceed KMaxLength.
TOwnerType aType = EOwnerProcess	The type of handle to be created. EOwnerProcess is the default value, if not explicitly specified.

CreateLocal(TInt, TInt, TOwnerType)

IMPORT_C TInt	CreateLocal	(	TInt	aSize,
			TInt	aMsgLength,
			TOwnerType	aType = EOwnerProcess
		)

Creates a message queue that is private to the current process, and opens a handle to that message queue.

The Kernel side object representing the message queue is unnamed. This means that it is not possible to search for the message queue, and this makes it local to the current process.

By default, any thread in the process can use this handle to access the message queue. However, specifying EOwnerThread as the third parameter to this function means that only the creating thread can use the handle to access the message queue; any other thread in this process that wants to access the message queue must duplicate this handle.

panic: KERN-EXEC 49 if aSize is less than or equal to zero.

panic: KERN-EXEC 48 if aMsgLength is not a multiple of 4 bytes, is less than 4, or is greater than KMaxLength.

KMaxLength

Parameters

TInt aSize	The number of message 'slots' in the queue. This must be a positive value, i.e. greater than zero.
TInt aMsgLength	The size of each message for the queue, this cannot exceed KMaxLength.
TOwnerType aType = EOwnerProcess	The type of handle to be created. EOwnerProcess is the default value, if not explicitly specified.

MessageSize()

IMPORT_C TInt

MessageSize

(

)

Gets the size of message slots in the queue.

NotifyDataAvailable(TRequestStatus &)

IMPORT_C void

NotifyDataAvailable

(

TRequestStatus &

aStatus

)

Requests notification when there is at least one message in the queue.

A thread can have only one data available notification request outstanding on this message queue. If a second request is made before the first request completes, then the calling thread is panicked.

panic: KERN-EXEC 47 if a second request is made while the first request remains outstanding.

Parameters

TRequestStatus & aStatus

The request status object to be completed when a message becomes available.

NotifySpaceAvailable(TRequestStatus &)

IMPORT_C void

NotifySpaceAvailable

(

TRequestStatus &

aStatus

)

Requests notification when space becomes available in the queue.

This is an asynchronous request that completes when there is at least one 'slot'available in the queue.

A thread can have only one space available notification request outstanding on this message queue. If a second request is made before the first request completes, then the calling thread is panicked.

panic: KERN-EXEC 47 if a second request is made while the first request remains outstanding.

Parameters

TRequestStatus & aStatus

The request status object to be completed when space becomes available.

Open(RMessagePtr2, TInt, TOwnerType)

IMPORT_C TInt	Open	(	RMessagePtr2	aMessage,
			TInt	aParam,
			TOwnerType	aType = EOwnerProcess
		)

Opens a global message queue using a handle passed in a server message.

By default, any thread in the process can use this handle to access the message queue. However, specifying EOwnerThread as the third parameter to this function, means that only the opening thread can use this handle to access the message queue.

Parameters

RMessagePtr2 aMessage	The server message.
TInt aParam	The number of the message parameter which holds the handle.
TOwnerType aType = EOwnerProcess	The type of handle to be created. EOwnerProcess is the default value, if not explicitly specified.

Open(TInt, TOwnerType)

IMPORT_C TInt	Open	(	TInt	aArgumentIndex,
			TOwnerType	aType = EOwnerProcess
		)

Opens a message queue using the handle passed in during process creation.

Parameters

TInt aArgumentIndex	The number on the parameter which holds the handle.
TOwnerType aType = EOwnerProcess	The type of handle to be created. EOwnerProcess is the default value, if not explicitly specified.

OpenGlobal(const TDesC &, TOwnerType)

IMPORT_C TInt	OpenGlobal	(	const TDesC &	aName,
			TOwnerType	aType = EOwnerProcess
		)

Opens a global message queue.

Global message queues are identified by name.

By default, any thread in the process can use this handle to access the message queue. However, specifying EOwnerThread as the second parameter to this function, means that only the opening thread can use this handle to access the message queue; any other thread in this process that wants to access the message queue must either duplicate this handle or use OpenGlobal() again.

RMsgQueueBase::OpenGlobal

Parameters

const TDesC & aName	The name of the message queue.
TOwnerType aType = EOwnerProcess	The type of handle to be created. EOwnerProcess is the default value, if not explicitly specified.

Receive(TAny *, TInt)

IMPORT_C TInt	Receive	(	TAny *	aPtr,
			TInt	aLength
		)

Retrieves the first message in the queue.

The function does not wait (i.e. block), if the queue is empty.

panic: KERN-EXEC 48 if aLength is not equal to the message length specified when the queue was created.

Parameters

TAny * aPtr	A pointer to a buffer to receive the message data.
TInt aLength	The length of the buffer for the message, this must match the queue's message size.

ReceiveBlocking(TAny *, TInt)

IMPORT_C void	ReceiveBlocking	(	TAny *	aPtr,
			TInt	aLength
		)

Retrieves the first message in the queue, and waits if the queue is empty.

The function uses NotifyDataAvailable() to provide the blocking operation. Note it is not possible to cancel a call to ReceiveBlocking().

panic: KERN-EXEC 48 if aLength is not equal to the message length specified when the queue was created.

RMsgQueueBase::NotifyDataAvailable

Parameters

TAny * aPtr	A pointer to a buffer to receive the message data.
TInt aLength	The length of the buffer for the message, this must match the queue's message size.

Send(const TAny *, TInt)

IMPORT_C TInt	Send	(	const TAny *	aPtr,
			TInt	aLength
		)

Sends a message through this queue.

The function does not wait (i.e. block), if the queue is full.

Note that, once on the queue, the content of the message cannot be accessed other than through a call to Receive() or ReceiveBlocking().

panic: KERN-EXEC 48 if aLength is greater than the message length specified when the queue was created, or if aLength is less than or equal to zero.

RMsgQueueBase::Receive RMsgQueueBase::ReceiveBlocking

Parameters

const TAny * aPtr	A pointer to the message data
TInt aLength	The length of the message data, this must not exceed the queue's message size.

SendBlocking(const TAny *, TInt)

IMPORT_C void	SendBlocking	(	const TAny *	aPtr,
			TInt	aLength
		)

Sends a message through this queue, and waits for space to become available if the queue is full.

The function uses NotifySpaceAvailable() to provide the blocking operation. Note that it is not possible to cancel a call to SendBlocking().

panic: KERN-EXEC 48 if aLength is greater than the message length specified when the queue was created, or if aLength is less than or equal to zero.

RMsgQueueBase::NotifySpaceAvailable

Parameters

const TAny * aPtr	A pointer to the message data.
TInt aLength	The length of the message data, this must not exceed the queue's message size.