Class RMsgQueue

class RMsgQueue : public RMsgQueueBase;

Description

A handle to a message queue.

The templated class provides the behaviour for managing an asynchronous queue of messages, where the template parameter defines the message type.

The class adds a type-checking interface to the basic message queue functionality provided by RMsgQueueBase.

Derivation

• RHandleBase - A handle to an object.

• RMsgQueueBase - ...

• RMsgQueue - A handle to a message queue.

Members

Defined in RMsgQueue:

• CreateGlobal(const TDesC &,TInt,TOwnerType)Creates a global message queue, and opens a handle to that message queue.
• CreateLocal(TInt,TOwnerType)Creates a message queue that is private to the current process, and opens a hand...
• Receive(T &)Retrieves the first message in the queue.
• ReceiveBlocking(T &)Retrieves the first message in the queue, and waits if the queue is empty.
• Send(const T &)Sends a message through this queue.
• SendBlocking(const T &)Sends a message through this queue, and waits for space to become available if t...

Inherited from RHandleBase:

• Attributes()const
• BTraceId()constReturns a unique object identifier for use with BTrace
• Close()Closes the handle.
• Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...
• FullName()constGets the full name of the handle.
• FullName(TDes &)constGets the full name of the handle.
• Handle()constRetrieves the handle-number of the object associated with this handle.
• HandleInfo(THandleInfo *)Gets information about the handle.
• Name()constGets the name of the handle.
• Open(const TFindHandleBase &,TOwnerType)Opens a handle to a kernel side object found using a find-handle object.
• RHandleBase(TInt)Copy constructor.
• SetHandle(TInt)Sets the handle-number of this handle to the specified value.
• SetHandleNC(TInt)Sets the handle-number of this handle to the specified value, and marks it as no...
• SetReturnedHandle(TInt)Sets the handle-number of this handle to the specified value.
• iHandle

Inherited from RMsgQueueBase:

• CancelDataAvailable()Cancels an outstanding data available notification request.
• CancelSpaceAvailable()Cancels an outstanding space available notification request.
• CreateGlobal(const TDesC &,TInt,TInt,TOwnerType)Creates a global message queue, and opens a handle to that message queue.
• CreateLocal(TInt,TInt,TOwnerType)Creates a message queue that is private to the current process, and opens a hand...
• KMaxLength
• MessageSize()Gets the size of message slots in the queue.
• NotifyDataAvailable(TRequestStatus &)Requests notification when there is at least one message in the queue.
• NotifySpaceAvailable(TRequestStatus &)Requests notification when space becomes available in the queue.
• Open(RMessagePtr2,TInt,TOwnerType)Opens a global message queue using a handle passed in a server message.
• Open(TInt,TOwnerType)Opens a message queue using the handle passed in during process creation.
• OpenGlobal(const TDesC &,TOwnerType)Opens a global message queue.
• Receive(TAny *,TInt)Retrieves the first message in the queue.
• ReceiveBlocking(TAny *,TInt)Retrieves the first message in the queue, and waits if the queue is empty.
• Send(const TAny *,TInt)Sends a message through this queue.
• SendBlocking(const TAny *,TInt)Sends a message through this queue, and waits for space to become available if t...
• anonymousThe limit for the size of an individual message.

inline TInt CreateLocal(TInt aSize, TOwnerType aType=EOwnerProcess);

Description

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

The size of each message in the queue is the size of the template parameter type. This must conform to the restrictions imposed on the aMsgLength parameter passed to the base class function RMsgQueueBase::CreateLocal(TInt,TInt,TOwnerType).

Parameters

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

Return value

TInt KErrNone if the queue is created sucessfully, otherwise one of the other system wide error codes.

Panic codes

KERN-EXEC 49 if aSize is less than or equal to zero. KERN-EXEC 48 if the size of the template parameter type is not a multiple of 4 bytes, is less than 4, or is greater than KMaxLength.

See also:

• RMsgQueueBase::CreateLocal(TInt,TInt,TOwnerType)Creates a message queue that is private to the current process, and opens a hand...
• RMsgQueueBase::KMaxLength

inline TInt CreateGlobal(const TDesC &aName, TInt aSize, TOwnerType aType=EOwnerProcess);

Description

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

If the name is non-empty, the message queue is visible to all processes. If the name is empty it cannot be opened or searched for by name, but a handle to it can be passed to another process as a process parameter or via IPC.

The size of each message in the queue is the size of the template parameter type. This must conform to the restrictions imposed on the aMsgLength parameter passed to the base class function RMsgQueueBase::CreateGlobal(const TDesC &,TInt,TInt,TOwnerType).

Parameters

const TDesC16 &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. TOwnerType aType The type of handle to be created. EOwnerProcess is the default value, if not explicitly specified.

Return value

TInt KErrNone if the queue is created sucessfully, otherwise one of the other system wide error codes.

Panic codes

KERN-EXEC 49 if aSize is less than or equal to zero. KERN-EXEC 48 if the size of the template parameter type is not a multiple of 4 bytes, is less than 4, or is greater than KMaxLength.

See also:

• RMsgQueueBase::CreateGlobal(const TDesC &,TInt,TInt,TOwnerType)Creates a global message queue, and opens a handle to that message queue.
• RMsgQueueBase::KMaxLength

inline TInt Send(const T &aMsg);

Description

Sends a message through this queue.

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

The function is implemented through a call to RMsgQueueBase::Send(const TAny *,TInt).

Parameters

const T &aMsg The message data to be sent.

Return value

TInt KErrNone, if successful; KErrOverflow, if queue is full,

See also:

• RMsgQueueBase::Send(const TAny *,TInt)Sends a message through this queue.

inline void SendBlocking(const T &aMsg);

Description

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

The function uses RMsgQueueBase::NotifySpaceAvailable(TRequestStatus &) to provide the blocking operation. Note that it is not possible to cancel a call to RMsgQueue::SendBlocking(const T &).

The function is implemented through a call to RMsgQueueBase::SendBlocking(const TAny *,TInt).

Parameters

const T &aMsg The message data to be sent.

See also:

• RMsgQueueBase::SendBlocking(const TAny *,TInt)Sends a message through this queue, and waits for space to become available if t...

inline TInt Receive(T &aMsg);

Description

Retrieves the first message in the queue.

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

The function is implemented through a call to RMsgQueueBase::Receive(TAny *,TInt).

Parameters

T &aMsg The object into which the message is retrieved.

Return value

TInt KErrNone, ifsuccessful; KErrUnderflow, if the queue is empty.

See also:

• RMsgQueueBase::Receive(TAny *,TInt)Retrieves the first message in the queue.

inline void ReceiveBlocking(T &aMsg);

Description

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

The function uses RMsgQueueBase::NotifyDataAvailable(TRequestStatus &) to provide the blocking operation. Note it is not possible to cancel a call to RMsgQueue::ReceiveBlocking(T &).

The function is implemented through a call to RMsgQueueBase::ReceiveBlocking(TAny *,TInt).

Parameters

T &aMsg The object into which the message is retrieved.

See also:

• RMsgQueueBase::ReceiveBlocking(TAny *,TInt)Retrieves the first message in the queue, and waits if the queue is empty.