RtNalReceive
RtNalReceive receives an Ethernet packet and copies packet data to the packet retrieved by the RTN_FN_GETPACKET callback at the application data buffer retrieved by the RTN_FN_DECODEPACKET callback.
Syntax
BOOL RtNalReceive( RTNAL_QUEUE_HANDLE queueHandle );
Parameters
queueHandle
Queue handle returned by RtNalAcquireQueue.
Return Value
Returns TRUE if the Ethernet packet was received and its packet data was copied to the buffer provided by the application. Otherwise it returns FALSE. Call GetLastError to obtain an error code. The possible error codes are listed below:
| Error Code | Meaning |
|---|---|
| ERROR_NOT_SUPPORTED | This is a not a receive queue, or the application has not supplied RTN_FN_GETPACKET or RTN_FN_DECODE_PACKET callback in RtNalConfigureQueue |
| ERROR_NOT_READY | RtNalConfigureQueue has not completed successfully. |
| ERROR_NO_DATA | There is no packet received by the driver. This error code is set by the device driver. |
| ERROR_DISCARDED | The receive packet callback returned TRUE. This error code is set by the device driver. |
| ERROR_INVALID_PARAMETER | queueHandle is a NULL pointer |
| ERROR_INVALID_USER_BUFFER | RTN_FN_GETPACKET returned NULL or a pointer filled in by RTN_FN_DECODE_PACKET callback is NULL, or the user packet is too small. This error code is set by the device driver. |
| ERROR_IO_DEVICE | A receive error has occurred. This error code is set by the device driver. |
| ERROR_INVALID_HANDLE | queueHandle is invalid. This might be occur if the queue was released in another thread or on process exit, as if by RtssKill. |
Remarks
For a list of supported functions for specific drivers, see Matrix of Supported Real-Time NAL Functions by NIC Driver.
This function uses the RtndReceive driver function.
This function requires:
- RTN_FN_GETPACKET callback to be supplied in RtNalConfigureQueue function.
- RTN_FN_DECODEPACKET callback to be supplied in RtNalConfigureQueue function.
The RtndReceive driver function copies received packet data to the application packet buffer.
If the application has configured the queue to use the RTN_FN_PKT_CALLBACK receive packet callback, the callback is executed before the RTN_FN_GETPACKET function callback. If the callback returns TRUE, RtNalReceive returns FALSE without requesting an application packet buffer or copying data.
Currently, the RTN_FN_PKT_CALLBACK receive packet callback is not supported in the RtNalE1000 driver.
RtNalGetReceivePacketCount can be used to determine the number of times to call RtNalReceive. Alternatively, a NAL application can call RtNalReceive until it returns FALSE with error code ERROR_NO_DATA.
This function is not re-entrant and requires a single threaded access.
The receive buffer should be at least the maximum packet size (the size returned with the device information in RtNalAcquireQueue) + 4.
Requirements
| Minimum Supported Version | RTX64 4.0 |
| Header | rtnapi.h, RtNalApi.h |
| Library | RtNal.lib |
See Also:
