Receives an RT object handle from an object mailbox. When a thread is waiting to receive a message:

• If there is a message in the queue when a thread arrives at a mailbox, the thread receives the message immediately.
• If there is no message in the queue, the thread may or may not wait in a thread queue.
  • If the ReceiveRtHandle call indicates that the thread can wait, it is placed in the thread queue and goes to sleep. Use this approach to use mailboxes to synchronize threads as well as pass messages. A sleeping thread wakes when a message arrives or when a specified time limit expires.
  • The thread receives an E_TIME status code if the designated wait period elapses before the thread gets a message.
  • If ReceiveRtHandle specifies that the thread cannot wait, the thread remains ready and immediately receives an E_TIME status code.

If you use ReceiveRtHandle, check to see if an acknowledgment has been requested.

RTHANDLE ReceiveRtHandle(
    RTHANDLE hMailbox,         // handle for object mailbox
    DWORD dwMilliseconds,     // number of milliseconds to wait
    LPRTHANDLE lphResponse    // pointer to response object
);

Parameters

hMailbox

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

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

lphResponse

Pointer to an area to receive a handle for a mailbox or a high-level semaphore for responding to the sending thread. If this value is NULL then no response object is returned.

Remarks

If the object queue at the mailbox is not empty, the calling thread immediately gets the RT handle at the head of the queue and remains ready. Otherwise, the calling thread goes into the thread queue of the mailbox and goes to sleep, unless the thread is not willing to wait. In the latter case, or if the thread's waiting period elapses without an RT handle arriving, the thread is awakened with an E_TIME status code.

It is possible that the RT handle returned by ReceiveRtHandle is an RT handle for an object that has already been deleted. To verify that the RT handle is valid, the receiving thread can invoke the GetRtHandleType system call. However, threads can avoid this situation by adhering to proper programming practices. One such practice is for the sending thread to request a response from the receiving thread and not delete the object until it gets a response. When the receiving thread finishes with the object, it sends a response, the nature of which must be determined by the writers of the two threads, to the response mailbox. When the sending thread gets this response, it can then delete the original object, if it so desires.

Return Values

A handle for an object passed in the mailbox.

Success

BAD_RTHANDLE

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 RT handle was available during the waiting period specified in wMilliseconds.

E_EXIST 0x0006

You used an invalid value for hMailbox.

E_PARAM 0x8004

dwMilliseconds contains an invalid value.

E_TYPE 0x8002

hMailbox is not a handle for an object mailbox.

E_INVALID_ADDRESS 0x00E2

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

Requirements

See Also

Mailbox system calls, GetRtHandleType, high-level ticks