MgslReceive

Prototype
`ULONG MgslReceive( HANDLE hDevice, PMGSL_RECEIVE_REQUEST pRcvReq, LPOVERLAPPED pOverlapped );`
Parameters
`hDevice`	handle to open port
`pRcvReq`	pointer to MGSL_RECEIVE_REQUEST structure
`pOverlapped`	pointer to overlapped structure initialized with a WIN32 manual reset event object which will be signaled when the receive operation completes
Return Value
`ERROR_SUCCESS (0)`	a received frame or receive error has been returned in pBuffer and pStatus
`ERROR_INVALID_HANDLE`	hDevice is invalid
`ERROR_INVALID_PARAMETER`	pRcvReq or the DataLength element of the structure pointed to by pRcvReq is invalid.
`ERROR_NOT_READY`	receiver is disabled and no data is available.
`ERROR_BUSY`	a request of this type is already pending
`ERROR_IO_PENDING`	waiting for receive operation to complete with a received frame or a receive error

Get received data from the API buffers. Prior to calling MgslReceive, set the DataLength member of the receive request structure to the size of the DataBuffer member. In HDLC mode, one received frame of variable length is returned. In Async mode, the request completes after filling the entire buffer with receive data.

If data is available then ERROR_SUCCESS is returned, otherwise ERROR_IO_PENDING is returned. When data becomes available, the API fills in the receive request structure and signals the event object.

NOTE:

If MgslReceive, returns ERROR_IO_PENDING, it is important that MgslReceive not be called again, until the request completes. See the Caution note in the Asynchronous API Notification topic for more information.

The Status member of the receive request structure indicates the status of the received data. If the status is RxStatus_OK, then the data was received without error and the DataLength member is set to indicate the number of bytes copied to the DataBuffer member. Other returned status values indicate an error and no data is returned.

If RxStatus_BufferTooSmall is returned, then the caller supplied buffer is too small to contain 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.

When the receiver is disabled, any receive data remaining in the API receive buffers can be retrieved with MgslReceive. When the receiver is disabled and there is no data in the API receive buffers, then MgslReceive returns ERROR_NOT_READY.

The amount of data available in the receive buffers can be polled using MgslGetOption() with the MGSL_OPT_RX_COUNT code.

Contents