Receives a data message from a mailbox created to pass data. This function fails if used with an object mailbox.

The ReceiveRtData call requests a message from a mailbox. Always specify a buffer of at least 128 bytes in the ReceiveRtData system call. You must allocate a receive buffer in your address space.

When a thread makes this call:

• If there is no message available at the mailbox, the thread goes into the thread queue. The thread goes to sleep for the specified time limit or until a message arrives, whichever comes first.
• If a message arrives during the time limit, the data is copied from the send buffer to the waiting thread's receive buffer. It does not go into the RT kernel-provided message queue.
• If no message arrives during the time limit, the thread awakens with an E_TIME status code.

WORD ReceiveRtData(
    RTHANDLE hMailbox,      // handle for data mailbox 
    LPVOID lpData,          // pointer to data buffer
    DWORD dwMilliseconds    // time period to wait for data
);

Parameters

hMailbox

Handle for a data mailbox.

lpData

Address of an area to receive the message data. The area must hold a minimum of 128 bytes of data.

dwMilliseconds

The number of milliseconds the calling thread waits:

NO_WAIT	The thread does not wait.
WAIT_FOREVER	The thread waits for its request to be fully satisfied.
1-655349	Calling thread goes to sleep for this many milliseconds, after which it awakes. Note: The kernel converts milliseconds to high-level ticks.

Remarks

Always use a buffer which is at least 128 bytes long, the maximum message size of SendRtData. If the calling thread is not willing to wait, or if the thread's waiting period elapses without a data message arriving, the thread is awakened with an E_TIME exceptional condition.

When you create a mailbox with CreateRtMailbox, you specify whether the mailbox will pass object handles or data. ReceiveRtData works only with mailboxes that have been created to pass data.

Return Values

The number of bytes received in the message.

Success.

0 (zero)

Failure. To determine the status, call GetLastRtError.
Note: This return code can also indicate that a zero-byte message has been received. In this case the last error value is not set.

Status

E_OK 0x0000

No exceptional conditions occurred.

E_TIME 0x0001

No message was available during the waiting period specified in dwMilliseconds.

E_EXIST 0x0006

You used an invalid value for hMailbox.

E_TYPE 0x8002

hMailbox does not contain an RT handle for a mailbox.

E_BAD_ADDR 0x800F

lpData is invalid.

E_NOT_ALLOCATED 0x00F2

lpData contains the addresss of memory which has been freed.

E_PARAM 0x8004

dwMilliseconds is invalid.

E_INVALID_ADDRESS 0x00E2

The address provided for the remote object is not a valid address.

Requirements

See Also

Mailbox system calls, CreateRtMailbox, SendRtData, high-level ticks