MGSL_RECEIVE_REQUEST Structure

This structure is used with the MgslReceive API call to retrieve a single HDLC frame or one or more bytes of asynchronous receive data. The structure is used to define the relative positions of the Status, DataLength, and DataBuffer fields. The application should allocate memory for the receive request that is large enough to hold the largest expected frame size. For example, if the largest expected frame size is 1000 bytes then a block of memory 1008 bytes should be allocated for the receive request.

On entry to an MgslReceive call, the DataLength member should be set to the size of the DataBuffer portion of the receive request structure. This allows the API to determine if there is sufficient space in the buffer for a received frame. When a receive request completes the DataLength member is set to the number of bytes contained in the DataBuffer member.

NOTE:

The maximum frame size that can be returned to the application is 65,535 bytes and at the driver level, this will include any CRC bytes received along with the frame. Thus, when using CCITT CRC32, the maximum number of bytes that can be transferred to the users MGSL_RECEIVE_REQUEST DataBuffer is 65,531 bytes (65,535 bytes - 4 bytes for a CRC32).

typedef struct _MGSL_RECEIVE_REQUEST
{
   ULONG Status;        /* returned request status */
   ULONG DataLength;    /* returned data length */
   char DataBuffer[1];    /* variable length data buffer */
} MGSL_RECEIVE_REQUEST, *PMGSL_RECEIVE_REQUEST;

The Status member is set by the API when a receive request is completed which is indicated by the event of the overlapped structure being signaled. Until the request is complete, the Status member value is undefined. The Status member can be set to the following values:

RxStatus_OK	Valid receive data returned, data returned in DataBuffer
RxStatus_CrcError	A frame with a CRC error was received, no data returned unless the HDLC_CRC_RETURN_CRCERR_FRAME bit flag is specified in the MgslSetParams() request.
RxStatus_FifoOverrun	A receive FIFO overrun occurred, no data returned
RxStatus_ShortFrame	An HDLC frame less than 32 bits received, no data returned
RxStatus_Abort	An HDLC abort was received, no data returned
RxStatus_BufferOverrun	An API buffer overrun occurred, no data returned
RxStatus_Cancel	The receive request was canceled or receiver was disabled, no data returned.
RxStatus_BufferToSmall	Caller supplied buffer is too small to hold the next available received frame. The size of the frame is returned in the DataLength member of the receive request structure, but no data is returned. The frame remains in the API buffer until MgslReceive is called with a buffer large enough to contain the frame.

If RxStatus_OK is set on completion of a receive request then the receive data is stored in the DataBuffer member of the structure and DataLength is set to the size of returned data in bytes.

Contents