The CIDataMbx class encapsulates the RT data mailbox object; it allows sending and receiving messages of up to 128 bytes each. The CIDataMbx class is typically used as it is.

Class members

Constructor

Destructor

Create

Send

Receive

CIDataMbx::Constructor

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

CIDataMbx::Destructor

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

CIDataMbx::Create

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

Syntax

DWORD CIDataMbx::Create(
    char * pszName, 
    BOOLEAN bPrioQ
);

Parameters

pszName

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

bPrioQ

Indicates whether threads waiting for a message will be queued in priority order (TRUE) or FIFO (FALSE); if omitted, FALSE is used. The result is a status indicating success or failure.

Status

E_OK

No exceptional conditions occurred.

E_MEM

Creating a mailbox requires more memory than the 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.

CIDataMbx::Send

With this call a message with a length between 1 and 128 bytes is sent to the data mailbox.

Syntax

DWORD CIDataMbx::Send(
    PVOID pv, 
    WORD wLen
);

Parameters

pv

Points to a buffer.

wLen

Specifies the number of bytes to be sent. The result is a status indicating success or failure.

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 is not attached.

E_PARAM

wLen is zero or exceeds 128.

E_BAD_ADDR

pv is invalid.

CIDataMbx::Receive

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

Syntax

WORD CIDataMbx::Receive(
    PVOID pv, 
    WORD wMax, 
    DWORD dwTimeout
);

Parameters

pv

Points to a buffer to receive the message.

wMax

Indicates the size of the buffer in bytes; if the size is less than 128 bytes, the framework will use its own buffer and the message is copied before returning.

dwTimeout

Defines how long the thread will wait and may be omitted (meaning WAIT_FOREVER). The result is the number of bytes received, or zero if an error occurred (use GetLastError to obtain the actual error code).

Status

E_OK

No exceptional conditions occurred.

E_TIME

No message was available during the waiting period.

E_EXIST

The object is not attached.

E_PARAM

wMax is zero, or the actual message received is longer than wMax; note that in the latter case the message is lost.

E_BAD_ADDR

pv is invalid.