Class RMsgQueueBase

class RMsgQueueBase : public RHandleBase;

Description

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

Derivation

• RHandleBase - A handle to an object.

• RMsgQueueBase - ...

Members

Defined in 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.

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

See also:

• RMsgQueueA handle to a message queue.

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

Description

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.

Parameters

Return value

Panic codes

See also:

• RMsgQueueBase::KMaxLength

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

Description

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 RMsgQueueBase::OpenGlobal(const TDesC &,TOwnerType).

Parameters

Return value

Panic codes

See also:

• RMsgQueueBase::KMaxLength
• RMsgQueueBase::OpenGlobal(const TDesC &,TOwnerType)Opens a global message queue.

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

Description

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 RMsgQueueBase::OpenGlobal(const TDesC &,TOwnerType) again.

Parameters

Return value

See also:

• RMsgQueueBase::OpenGlobal(const TDesC &,TOwnerType)Opens a global message queue.

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

Description

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

Return value

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

Description

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

Parameters

Return value

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

Description

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 RMsgQueueBase::Receive(TAny *,TInt) or RMsgQueueBase::ReceiveBlocking(TAny *,TInt).

Parameters

Return value

Panic codes

See also:

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

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

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 RMsgQueueBase::SendBlocking(const TAny *,TInt).

Parameters

Panic codes

See also:

• RMsgQueueBase::NotifySpaceAvailable(TRequestStatus &)Requests notification when space becomes available in the queue.

IMPORT_C TInt Receive(TAny *aPtr, TInt aLength);

Description

Retrieves the first message in the queue.

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

Parameters

Return value

Panic codes

IMPORT_C void ReceiveBlocking(TAny *aPtr, TInt aLength);

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 RMsgQueueBase::ReceiveBlocking(TAny *,TInt).

Parameters

Panic codes

See also:

• RMsgQueueBase::NotifyDataAvailable(TRequestStatus &)Requests notification when there is at least one message in the queue.

IMPORT_C void NotifySpaceAvailable(TRequestStatus &aStatus);

Description

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.

Parameters

Panic codes

IMPORT_C void CancelSpaceAvailable();

Description

Cancels an outstanding space available notification request.

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

Panic codes

See also:

• RMsgQueueBase::NotifySpaceAvailable(TRequestStatus &)Requests notification when space becomes available in the queue.

IMPORT_C void NotifyDataAvailable(TRequestStatus &aStatus);

Description

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.

Parameters

Panic codes

IMPORT_C void CancelDataAvailable();

Description

Cancels an outstanding data available notification request.

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

Panic codes

See also:

• RMsgQueueBase::NotifyDataAvailable(TRequestStatus &)Requests notification when there is at least one message in the queue.

IMPORT_C TInt MessageSize();

Description

Gets the size of message slots in the queue.

Return value

n/a

Description

The limit for the size of an individual message.