INtime SDK Help
ReceiveRtMessage
INtime SDK v6 > About INtime > INtime Kernel > Ports > ReceiveRtMessage

From INtime 6.0 the INtime Service and Port objects have been deprecated.

New projects should not be started using these features, and existing projects will not work with XM mode. You will receive a compiler warning by default if you use these calls.

Receives a message at a port. If the message contains a data portion, a pointer to the buffer used to store the data portion is returned. If a heap object was attached to the port, when the buffer is no longer required, the application should return it to the heap using the ReleaseRtBuffer. If there is not enough buffer space, the message is rejected by the receiving host.

Use this call to receive messages from a service. Typically, this call is used by server applications which process all messages from a given port.

You must identify the receiving port (using its handle). You must specify how long the task will wait for the message at the port. The calling task goes to sleep waiting for a message at a port. If no message arrives before the specified time limit expires, the task awakens with an E_TIME condition code.

You must also supply a pointer to a structure that this call fills with information about the message received. This structure contains information such as the type of message, certain status information, the transaction ID, the handle of the forwarding port (if the receiving port is a sink port), the originating address and port ID of the message, and the control message. The type field indicates whether the message was a simple, request, response or status message.

LPVOID ReceiveRtMessage(
    RTHANDLE hPort,                 // a port handle
    DWORD dwMilliseconds,           // time limit to wait for a message to arrive
    LPRECEIVEINFO lpReceiveInfo     // a pointer to a receive information structure
);

Parameters

hPort
A handle for the port that is to receive the message
dwMilliseconds
The time period for which 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 high-level ticks.

lpReceiveInfo
A pointer to a RECEIVEINFO structure where the thread receives information about the message received.

Return Values

A pointer to the data part of the message just received. If there was no data part, then a NULL value is returned.
Success.
A BAD_POINTER value.
Failure. To determine the status, call GetLastRtError.

Status

E_OK 0x0000
No exceptional conditions occurred.
E_TIME 0x0001
The operation timed out before completion.
E_EXIST 0x0006
The port is already being deleted.
E_STATE 0x0008
The port is a sink port with no ports forwarded to it.
E_TYPE 0x8002
The handle supplied is not for a port object.
E_NUC_BAD_BUF 0x80E2
The receive info pointer was invalid.

Requirements

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

See Also

Port system calls, ReleaseRtBuffer, RECEIVEINFO