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 ntxReleaseRtBuffer. 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 ntxReceiveRtMessage(
    NTXHANDLE hPort,
    DWORD dwMilliseconds,
    LPRECEIVEINFO *pReceiveInfo
);

Parameters

hPort

The port that will receive the message.

dwMilliseconds

The number of milliseconds the call will wait for a message to arrive, or INFINITE to wait forever.

pReceiveInfo

A RECEIVEINFO structure, initially passed in with the length field set, which will be filled in when the message arrives.

Return Values

A pointer to a buffer containing the data part of the message, or NULL if no data port exists. If this message is not a response message, the memory must be returned to Windows with ntxReleaseRtBuffer.

Success.

A BAD_POINTER value.

Failure. To determine the status, call ntxGetLastRtError.

Status

E_OK 0x0000

No exceptional conditions occurred.

E_TIME

The number of milliseconds defined in dwMilliseconds elapsed before a message was received.

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.

E_LOCATION

The RT client on which the port was created is now invalid.

E_NTX_INTERNAL_ERROR

The DLL could not contact the RT kernel to complete the request.

Requirements

See Also

Port system calls, ntxReleaseRtBuffer, RECEIVEINFO