INtime SDK Help
CIMessageQueue
  

The CIMessageQueue class encapsulates the RT message queue mailbox object; it allows sending and receiving RT messages. The CIMessageQueue class is typically used as it is.

Class members

Constructor

Destructor

Create

Send

Receive

CIMessageQueue::Constructor

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

CIMessageQueue::Destructor

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

CIMessageQueue::Create

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

Syntax

DWORD CIMessageQueue::Create(
    char * pszName, 
    DWORD dwSize,
    DWORD dwMsgThreshold
);

Parameters

pszName
Specifies a name that, if not empty, is used to catalog the RT object.
dwSize
The size of the message queue, which is the total amount of memory available to store the messages.
dwMsgThreshold
The threshold size for short messages. Any message longer than this will be transmitted by reference.

Status

E_OK
No exceptional conditions occurred.
E_MEM
Creating a message queue 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.

CIMessageQueue::Send

With this call an RT message is sent to the message queue.

Syntax

DWORD CIMessageQueue::Send(
    PVOID pv, 
    DWORD dwLen,
    DWORD dwTimeout
;

Parameters

pv
Points to a buffer.
wLen
Specifies the number of bytes to be sent.
dwTimeout
Number of microseconds to wait until message is transmitted (in case of long messages).

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.

CIMessageQueue::Receive

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

Syntax

DWORD CIMessageQueue::Receive(
    PVOID pv,
    DWORD dwMax,
    DWORD dwTimeout
);

Parameters

pv
Points to a buffer.
dwMax
The size of the buffer.
dwTimeout
Defines how long the thread will wait and may be omitted (meaning WAIT_FOREVER).

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
pv is NULL or the size of the buffer is too small for current waiting message.
See Also

Mailboxes