INtime SDK Help
SendRtHandle
INtime SDK v7.1 > About INtime > INtime Kernel > Mailboxes > SendRtHandle

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:

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

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

See Also

Mailbox system calls, CreateRtMailbox, ReceiveRtHandle