INtime SDK Help
ReceiveRtDataMessage
INtime SDK v7 > About INtime > INtime Kernel > Message Queues > ReceiveRtDataMessage

Receives a data message from a queue object.

BOOLEAN ReceiveRtDataMessage(
RTHANDLE hQueue,
LPVOID msgBuffer,
DWORD msgBufferSize,
DWORD msWait,
DWORD *pMsgSize);

Parameters

hQueue
A handle for a valid queue object.
msgBuffer
A pointer to a contiguous buffer where the message is to be received.
msgBufferSize
Size in bytes of the message buffer.
msWait
The number of milliseconds for which the calling thread should wait for a message. The value is converted to high-level ticks by the kernel.
pMsgSize
A pointer to a DWORD location where the number of bytes actually received is returned.

Additional information

If a short message is available on the queue the data is received into the buffer specified by the msgBuffer parameter. If the buffer specified is not large enough to receive the next available message the call fails with status E_LIMIT and the call may be retried with a larger buffer. The required buffer size will be returned through the pMsgSize parameter.

If a long message has been sent to the queue, the call will return FALSE with a special status of E_NO_LOCAL_BUFFER (returned through GetLastRtError). The message buffer will contain a structure of type MSG_DESCRIPTOR which is used to identify the long message. The caller must then call GetRtLongDataMessage to retrieve the data.

Returns

Returns TRUE on success. Returns FALSE on failure. Call GetLastRtError() to find the failure status. Possible status values include:
E_EXIST The hQueue parameter does not refer to an existing object
E_LIMIT The buffer specified is not large enough to receive the next message in the queue.
E_TYPE The hQueue parameter does not refer to a valid queue object.
E_NO_LOCAL_BUFFER A long message has been sent. The value pointed to by the msgSize parameter contains the number of bytes in the long message. The caller must now call GetRtLongDataMessage to receive the data.
E_TIME The call timed out before a message was received.
E_BAD_ADDR The msgBuffer parameter is not valid.
E_PARAM The msWait parameter is not valid. It must be between 0 and 655349, or WAIT_FOREVER

Requirements

Versions Defined in Include Link to
INtime 5.0 intime/rt/include/rtbase.h rt.h rt.lib
See Also