The CIMessageQueue class encapsulates the RT message queue mailbox object; it allows sending and receiving RT messages. The CIMessageQueue class is typically used as it is.

Class members

Constructor

Destructor

Create

Send

Receive

CIMessageQueue::Constructor

The constructor has no arguments. It creates an unattached object.

CIMessageQueue::Destructor

If the object is attached, the destructor detaches it; then it destroys the object.

CIMessageQueue::Create

If the object is already attached, it is first detached. Then this call creates an RT message queue object and attaches it to the object.

Syntax

DWORD CIMessageQueue::Create(
    char * pszName, 
    DWORD dwSize,
    DWORD dwMsgThreshold

);

Parameters

pszName

Specifies a name that, if not empty, is used to catalog the RT object.

dwSize

The size of the message queue, which is the total amount of memory available to store the messages.

dwMsgThreshold

The threashold size for short messages. Any message longer than this will be transmitted by reference.

Status

E_OK

No exceptional conditions occurred.

E_MEM

Creating a message queue requires more memory than the current process owns.

E_LIMIT

The current process reached its RT object limit, or the object directory is full.

E_SLOT

You cannot create more RT objects because the GDT is full.

E_CONTEXT

The object directory already contains the name being cataloged.

E_PARAM

The name is too long or is improperly formatted.

CIMessageQueue::Send

With this call an RT message is sent to the message queue.

Syntax

DWORD CIMessageQueue::Send(
    PVOID pv, 
    DWORD dwLen,
    DWORD dwTimeout
;

Parameters

pv

Points to a buffer.

wLen

Specifies the number of bytes to be sent.

dwTimeout

Number of microseconds to wait until message is transmitted (in case of long messages).

Status

E_OK

No exceptional conditions occurred.

E_MEM

The message queue is full and the current process does not contain enough memory to extend the queue.

E_EXIST

The object itself, or the object to be sent, or the reply object is not attached.

E_PARAM

The reply object has a bad type.

CIMessageQueue::Receive

This call puts the thread in a sleep state until a message arrives, or until a timeout occurs.

Syntax

DWORD CIMessageQueue::Receive(
    PVOID pv,
    DWORD dwMax,
    DWORD dwTimeout
);

Parameters

pv

Points to a buffer.

dwMax

The size of the buffer.

dwTimeout

Defines how long the thread will wait and may be omitted (meaning WAIT_FOREVER).

Status

E_OK

No exceptional conditions occurred.

E_TIME

No handle was available during the waiting period.

E_EXIST

The object is not attached.

E_PARAM

pv is NULL or the size of the buffer is too small for current waiting message.