»
Symbian OS v9.3 »
Symbian OS reference »
C++ component reference »
Base E32_EKA2 »
RMsgQueueBase
Location:
e32msgqueue.h
Link against: euser.lib
class RMsgQueueBase : public RHandleBase;
Description
Provides implementation for managing an asynchronous message queue, and is a base class for the RMsgQueue
templated class.
Derivation
RMsgQueueBase
- Provides implementation for managing an asynchronous message queue, and is a base class for the
RMsgQueue templated class
Members
Defined in RMsgQueueBase
:
CancelDataAvailable()
, CancelSpaceAvailable()
, CreateGlobal()
, CreateLocal()
, KMaxLength
, MessageSize()
, NotifyDataAvailable()
, NotifySpaceAvailable()
, Open()
, Open()
, OpenGlobal()
, Receive()
, ReceiveBlocking()
, Send()
, SendBlocking()
, anonymous
Inherited from RHandleBase
:
Attributes()
,
Close()
,
Duplicate()
,
FullName()
,
Handle()
,
HandleInfo()
,
Name()
,
SetHandle()
,
SetHandleNC()
,
SetReturnedHandle()
,
iHandle
See also:
Member functions
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
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 |
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 aMsgLength is not a multiple of 4 bytes, is less than 4, or is greater than KMaxLength.
|
|
See also:
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 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 |
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 aMsgLength is not a multiple of 4 bytes, is less than 4, or is greater than KMaxLength.
|
|
See also:
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 OpenGlobal()
again.
Parameters
const TDesC &aName |
The name of the message queue.
|
TOwnerType aType |
The type of handle to be created. EOwnerProcess is the default value, if not explicitly specified.
|
|
Return value
TInt
|
KErrNone if queue opened sucessfully, otherwise one of the other system wide error codes.
|
|
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
RMessagePtr2 aMessage |
The server message.
|
TInt aParam |
The number of the message parameter which holds the handle.
|
TOwnerType aType |
The type of handle to be created. EOwnerProcess is the default value, if not explicitly specified.
|
|
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
TInt aArgumentIndex |
The number on the parameter which holds the handle.
|
TOwnerType aType |
The type of handle to be created. EOwnerProcess is the default value, if not explicitly specified.
|
|
Return value
TInt
|
KErrNone, ifsuccessful; KErrArgument, if aArgumentIndex doesn't contain a message queue handle; KErrNotFound, if aArgumentIndex
is empty.
|
|
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 Receive()
or 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.
|
|
Return value
TInt
|
KErrNone, if successful; KErrOverflow, if queue is full,
|
|
Panic codes
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.
|
|
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 NotifySpaceAvailable()
to provide the blocking operation. Note that it is not possible to cancel a call to SendBlocking()
.
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.
|
|
Panic codes
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.
|
|
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
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.
|
|
Return value
TInt
|
KErrNone, ifsuccessful; KErrUnderflow, if the queue is empty.
|
|
Panic codes
KERN-EXEC |
48 if aLength is not equal to the message length specified when the queue was created.
|
|
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 NotifyDataAvailable()
to provide the blocking operation. Note it is not possible to cancel a call to ReceiveBlocking()
.
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.
|
|
Panic codes
KERN-EXEC |
48 if aLength is not equal to the message length specified when the queue was created.
|
|
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
TRequestStatus &aStatus |
The request status object to be completed when space becomes available.
|
|
Panic codes
KERN-EXEC |
47 if a second request is made while the first request remains outstanding.
|
|
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
KERN-EXEC |
50 if attempting to cancel an outstanding request made by a thread in a different process.
|
|
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
TRequestStatus &aStatus |
The request status object to be completed when a message becomes available.
|
|
Panic codes
KERN-EXEC |
47 if a second request is made while the first request remains outstanding.
|
|
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
KERN-EXEC |
50 if attempting to cancel an outstanding request made by a thread in a different process.
|
|
IMPORT_C TInt MessageSize();
Description
Gets the size of message slots in the queue.
Return value
TInt
|
The size of a message slot in the queue.
|
|
n/a
Description
The limit for the size of an individual message.