The CIObjectMbx class encapsulates the RT object mailbox object; it allows sending and receiving RT object handles, which can be attached to objects. The CIObjectMbx class is typically used as it is.

Class members

Constructor

Destructor

Create

Send

Receive

CIObjectMbx::Constructor

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

CIObjectMbx::Destructor

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

CIObjectMbx::Create

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

Syntax

DWORD CIObjectMbx::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 handle will be queued in priority order (TRUE) or FIFO (FALSE); if omitted, FALSE is used.

Status

E_OK

No exceptional conditions occurred.

E_MEM

Creating a mailbox 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.

CIObjectMbx::Send

With this call an RT object handle is sent to the object mailbox.

Syntax

DWORD CIObjectMbx::Send(
    CIObject * pObject, 
    CIOBJECT * pReply
);

Parameters

pObject

Defines the object whose handle must be sent.

pReply

Points to a (data or object) mailbox or semaphore object, where a reply is expected; it may be NULL or omitted, in which case no reply is expected. 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 itself, or the object to be sent, or the reply object is not attached.

E_PARAM

The reply object has a bad type.

CIObjectMbx::Receive

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

Syntax

CIObject * CIObjectMbx::Receive(
    CIObject ** pReply,
    DWORD dwTimeout
);

Parameters

pReply

Points to a variable that receives a pointer to an object attached to the RT object where a reply should be sent, or NULL when no reply is expected. If pReply is NULL, there should not be a reply; if pReply is omitted NULL is assumed.

dwTimeout

Defines how long the thread will wait and may be omitted (meaning WAIT_FOREVER). The result is a pointer to an object, or NULL if an error occurred (use GetLastError to obtain the actual error code). The result object (and the reply object, if applicable) should be deleted after use.

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

pReply is NULL, but a reply was requested.

E_MEM

There is not enough memory to create the received object or the reply object.