This class is only available in the RT environment. It has been derived from CIThread to ease the creation of a thread that waits for incoming messages at a message queue. It must be used to derive an application specific message queue thread class, or it can be used directly to control a thread object. See also CIThread. In contrast to the C implementation of message queues, the C++ class handles short and long messages by its own and just delivers the data in the OnReceive function.

Class members

Constructor

Destructor

Create

DoForever

ExitInstance

OnReceive

Member variables

The following member variable is only available to the members of the class and its derived classes:

CIMessageQueue m_MQu;

CIMessageQueueThread::Constructor

See CIThread::Constructor.

CIMessageQueueThread::Destructor

See CIThread::Destructor.

CIMessageQueueThread::Create

If the object is already attached, it is first detached. Then this call creates a new active RT thread object and attaches it to the object.

Syntax

DWORD CIMessageQueueThread::Create(
    char * pszName, 
    char * pszMbx,
    DWORD dwQueueSize,
    DWORD dwMsgThreshold,
    BYTE byPrio,
    DWORD dwStack, 
    BOOLEAN bGo
);

Parameters

pszName

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

pszMbx

Specifies the name for the data mailbox object; it must be supplied.

dwQueueSize

Indicates the number of bytes to be reserved for exchanging messages. The longest possible message size is limited to this amount of bytes.

dwMsgThreshold

Indicates the length of a message to be transferred as short messages, long messages are passed by reference.

byPrio

Indicates the priority for the new thread and must either be zero (this means the best possible priority in the process) or obey this rule: (max priority of process) <= byPrio < 254.

dwStack

Indicates the number of bytes to be reserved for stack space; it should be a multiple of 4 and at least 2048; if omitted, 4096 is used.

bGo

Indicates whether the thread will execute immediately (TRUE) or will be created in suspended state (FALSE); if omitted, TRUE is used. The result is a status indicating success or failure.

The new thread creates the message queue and catalogs it. The result is a status indicating success or failure:

Status

E_OK

No exceptional conditions occurred.

E_MEM

The current process cannot create a thread or mailbox as specified with the memory available.

E_LIMIT

Either the calling thread's process already reached its object or thread limit, or byPrio contains a bad value, or the object directory is full.

E_SLOT

You cannot create more RT objects because the GDT's slots are full.

E_PARAM

dwStack contains a value of less than 2048, or either name is too long or is improperly formatted.

E_CONTEXT

The object directory already contains one of the names being cataloged.

For details on the code executed by the new thread, see CIThreadCreate.

CIMessageQueueThread::DoForever

See CIThread::DoForever. CIMessageQueueThread::DoForever is called by the framework and should never be called explicitly. CIMessageQueueThread::DoForever waits for a message at the data mailbox (no timeout), calls the OnReceive member (only after successful receive) and returns a boolean status (TRUE for success, FALSE for failure). When overruling this call, do not include a call to the default call.

CIMessageQueueThread::ExitInstance

See CIThread::ExitInstance. CIMessageQueueThread::ExitInstance is called by the framework before terminating the thread and should never be called explicitly. CIMessageQueueThread::ExitInstance detaches the data mailbox object and then returns 0.

CIMessageQueueThread::OnReceive

CIMessageQueueThread::OnReceive is called by the framework when a message has been received successfully and should never be called explicitly. CIMessageQueueThread::OnReceive just returns TRUE. When overruling this call, there is no need to call the default call.

Syntax

BOOLEAN CIMessageQueueThread::OnReceive(
    BYTE * pBuffer, 
    WORD wLen);

The call gets two parameters: pBuffer points to a buffer containing the message, wLen contains the number of bytes received. The result must be TRUE to let the thread continue, FALSE to terminate the thread.