Rtnl2ReceiveFromLogicalRxQueue receives one frame from a specified Logical Receive Queue.
Syntax
BOOL Rtnl2ReceiveFromLogicalRxQueue(
[in] RTNL2_HLOGICAL_RX_QUEUE LogicalRxQueue,
[in, out] RTNL2_RECEIVE_DESC *pReceiveDesc,
[in] ULONG DescStructSize
);Parameters
[in] LogicalRxQueue
A handle to the Logical Receive Queue.
[in, out] pReceiveDesc
The address of the RTNL2_RECEIVE_DESC structure (allocated by the caller) describing the requested receive operation.
[in] DescStructSize
The size of the RTNL2_RECEIVE_DESC structure.
Return Value
If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. Call GetLastError to obtain an error code.
Possible error codes:
| Error code | Meaning |
|---|---|
|
ERROR_NOT_READY |
The calling process has not called Rtnl2Init. |
|
ERROR_INVALID_PARAMETER |
One of the following conditions occurred:
|
|
ERROR_NO_DATA |
There are no more buffers to extract from the Logical Receive Queue. |
|
RTNL2_ERROR_LOGICAL_RX_QUEUE_IS_DESTROYING |
Another thread of the calling process is executing Rtnl2DestroyLogicalRxQueue at the same time. |
|
RT_ERROR_INCOMPATIBLE_REQUEST |
The RTNL2_RECEIVE_DESC structure pointed by parameter pReceiveDesc contains fields that this version of the NL2 can’t interpret. |
|
RTNL2_ERROR_NO_MORE_COMMUNICATION |
Unable to communicate with the NL2 process. This might be because the NL2 process is not running anymore, or because an application process thread was terminated during a previous call to an NL2 API function. |
Remarks
The caller MUST zero-out the structure pointed to by parameter pTReceiveDesc before populating it and MUST set parameter DescStructSize to sizeof(RTNL2_RECEIVE_DESC) to ensure backward and forward compatibility.
The RTNL2_RECEIVE_DESC structure pointed by parameter pReceiveDesc must be allocated by the caller. The NL2 does not keep track of it. Once the function returns, the caller can either reuse that structure for another receive operation or free it. The RTNL2_RECEIVE_DESC structure is an in-and-out parameter. Part of the structure is populated by the caller (fields pFrameData and BufferLength) and another part of it is populated by the NL2 (fields FrameLength and OriginalFrameLength).
Rtnl2ReceiveFromLogicalRxQueue extracts the next local buffer from the list of received Logical Rx Queue buffers, copies the content of the local buffer into the supplied application buffer, and moves the local buffer to the set of available local buffers for this Logical Rx Queue.
If the list of received Logical Rx Queue buffers is empty, then the function does NOT wait until a new frame is received. Instead, it immediately fails and sets the last error to ERROR_NO_DATA.
The application is expected to call Rtnl2ReceiveFromLogicalRxQueue in a loop as fast as possible after it is signaled by the Receive event and until Rtnl2ReceiveFromLogicalRxQueue returns ERROR_NO_DATA.
If the buffer allocated by the application to hold the received frame is smaller than the actual received frame, the NL2 truncates the received frame and reports the original length of the frame (before it was truncated) in RTNL2_RX_FRAME.OriginalFrameLength.
Characteristics
| Real-time | ||
|
Deterministic |
No |
|
| Local memory usage | ||
|
Process |
External MSpace usage |
Internal MSpace usage |
|
System |
No |
No |
|
NL2 process |
No |
No |
|
Calling process |
No |
No |
| Contiguous memory usage | ||
|
Usage |
No |
|
Requirements
| Minimum supported version | Header | Library |
|---|---|---|
|
eRTOS 1.0 SDK |
Rtnl2Api.h |
Rtnl2Api.lib |
See Also:
