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

See Also

Port system calls, ReleaseRtBuffer, RECEIVEINFO