Passes a data message via a mailbox created to pass data messages. Up to 128 bytes of data may be sent.

SendRtData copies up to 128 bytes of data from the sender to the receiver. The 128 bytes of data may be sent from or received in any legitimate memory area such as the application's data or stack area, or dynamically created memory.

The copied data may be any collection of bytes. One possibility is a pointer (or handle) to yet another memory area accessible to both the sender and receiver. Thus, you can send a reference (pointer) to a much larger set of data. If a pointer is sent, the receiver must be in the same process as the sender.

Zero length may be specified in the call. In this case the next waiting thread is woken up with a return value of 0, which is also used to indicate an error. In this case no error status set.

The original data area becomes available for re-use after SendRtData returns.

You cannot request acknowledgment from the receiving thread when you use SendRtData.

If there is a thread waiting at the mailbox when the message arrives, the message is copied directly to the thread's receive buffer. Otherwise the message is copied into the INtime kernel-provided message queue.

BOOLEAN SendRtData(
    RTHANDLE hMailbox,
    LPVOID lpData,
    WORD cbBytesSent
);

Parameters

hMailbox

Handle for a data mailbox. This call will fail if used with an object mailbox.

lpData

Pointer to data buffer.

cbBytesSent

Actual number of bytes to transfer. This must be less than or equal to 128.

Remarks

If there are threads in the thread queue at the mailbox, the thread at the head of the queue is awakened and is given the data. Otherwise, the message data is placed at the tail of the mailbox's message queue.

Return Values

TRUE

Success

FALSE

To determine the status, call GetLastRtError

Status

E_OK 0x0000

No exceptional conditions occurred.

E_MEM 0x0002

The message queue is full and the calling thread's process does not contain enough memory to extend the queue.

E_EXIST 0x0006

The mailbox RT handle is not a RT handle for an existing object.

E_SLOT 0x000C

The data message queue is full and the system does not have enough GDT slots to extend it.

E_TYPE 0x8002

hMailbox does not contain an RT handle for a mailbox.

E_PARAM 0x8004

cbBytesSent parameter contains a value larger than 128.

E_BAD_ADDR 0x800F

lpData is invalid.

E_INVALID_ADDRESS 0x00E2

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

Requirements

See Also

Mailbox system calls, ReceiveRtData