Sends an RT object handle to a mailbox created to pass RT objects, and enables a thread to request acknowledgment from the receiving thread.

When you send a message:

• If a thread is waiting, it receives the message immediately. If the receiving thread has been asleep, it moves either from asleep to ready or from asleep-suspended to suspended.
• If no thread is waiting, the message is placed at the tail of the message queue. Message queues are processed as FIFO, so the message remains in the queue until it moves to the head of the queue and is given to a thread.

BOOLEAN SendRtHandle(
    RTHANDLE hMailbox,    // handle for object Mailbox
    RTHANDLE hObject,     // handle for any RT object
    RTHANDLE hResponse    // handle for response mailbox or semaphore
);

Parameters

hMailbox

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

hObject

Handle for any valid RT object. If the object is a reference then hMailbox must also be a reference, and they both have to reside on the same node.

hResponse

Handle for a mailbox or a high-level semaphore at which the sending thread waits to receive a response from the receiving thread. If the handle is NULL_RTHANDLE then no response is expected. Note that hResponse, if non-null, must be a handle for a local object, and not a reference.

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 RT handle. Otherwise, the RT handle is placed at the tail of the object queue of the mailbox.

The sending thread has the option of specifying a mailbox or semaphore at which to wait for a response from the receiving thread.

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_CONTEXT 0x0005

hResponse is a reference to an object and not a local object.

E_EXIST 0x0006

You used an invalid value for hMailbox, hObject, or hResponse.

E_TYPE 0x8002

One of these conditions exist:

• hMailbox must be an object mailbox
• hResponse must be a mailbox, semaphore, or NULL.

E_INVALID_ADDRESS 0x00E2

One of these:

• a reference object has an invalid location, or
• the parameters hMailbox and hObject are both references, but they reside at different locations.

Requirements

See Also

Mailbox system calls, CreateRtMailbox, ReceiveRtHandle