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 handles at an object mailbox. It must be used to derive an application specific object 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:

CIObjectMbx m_Mbx;

CIObjectMbxThread::Constructor

See CIThread::Constructor.

CIObjectMbxThread::Destructor

See CIThread::Destructor.

CIObjectMbxThread::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 CIObjectMbxThread::Create(
    char * pszName, 
    char * pszMbx,
    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 object mailbox object; it must be supplied.

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 object mailbox 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 object 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.

CIObjectMbxThread::DoForever

See CIThread::DoForever. CIObjectMbxThread::DoForever is called by the framework and should never be called explicitly. CIObjectMbxThread::DoForever waits for a handle at the object mailbox (no timeout), creates an object for the handle (and optionally also one for the reply object handle), calls the OnReceive member (only after successful receive, see below) deletes the created objects and returns a boolean status (TRUE for success, FALSE for failure). When overruling this call, do not include a call to the default call.

CIObjectMbxThread::ExitInstance

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

CIObjectMbxThread::OnReceive

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

Syntax

BOOLEAN CIObjectMbxThread::OnReceive(
    CIObject * pObject,
    CIObject * pReply
);

Parameters

pObject

Points to the object received from the object mailbox.

pReply

NULL if no reply is expected, or else points to the reply object. Note that the received object and the reply object (if present) are temporary objects; they are deleted on exit from OnReceive. The result must be TRUE to let the thread continue, FALSE to terminate the thread.