INtime SDK Help
ReceiveRtData
INtime SDK v6 > About INtime > INtime Kernel > Mailboxes > ReceiveRtData

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:

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

Versions Defined in Include Link to
INtime 3.0 intime/rt/include/rtbase.h rt.h rt.lib

See Also

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