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

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

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

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

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

See Also

Mailbox system calls, GetRtHandleType, high-level ticks