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 low level mailbox. It must be used to derive an application specific low level mailbox thread class, or it can be used directly to control a thread object.

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:

CILLMbx * m_pMbx;

CILLMbxThread::Constructor

See CIThread::Constructor.

CILLMbxThread::Destructor

See CIThread::Destructor.

CILLMbxThread::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 CILLMbxThread::Create(
    char * pszName,
    CILLMbx * pMbx, 
    DWORD dwMsgSize,
    BYTE byPrio, 
    DWORD dwStack, 
    BOOLEAN bGo
);

Parameters

pszName

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

pMbx

Specifies the low level RT mailbox.

dwMsgSize

Should be the same as specified when creating that mailbox. The new thread allocates a buffer to hold one message.

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 result is a status indicating success or failure:

Status

E_OK

No exceptional conditions occurred.

E_MEM

The current process cannot create a thread 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 the name is too long or is improperly formatted.

E_CONTEXT

The object directory already contains the name being cataloged.

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

CILLMbxThread::DoForever

See CIThread::DoForever. CILLMbxThread::DoForever is called by the framework and should never be called explicitly. CILLMbxThread::DoForever waits for a message at the low level 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.

CILLMbxThread::ExitInstance

See CIThread::ExitInstance. CILLMbxThread::ExitInstance is called by the framework before terminating the thread; it should never be called explicitly. CILLMbxThread::ExitInstance frees the message buffer and then returns 0.

CILLMbxThread::OnReceive

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

Syntax

BOOLEAN CILLMbxThread::OnReceive(
    BYTE * pBuffer, 
    DWORD dwLen
);

Parameters

pBuffer

Points to the message received from the low level mailbox.

dwLen

Indicates the number of bytes in the message. The result must be TRUE to let the thread continue, FALSE to terminate the thread.