ProSoft Technology MVI69-ADM - Manual (Page 257)

MVI-ADM ♦ 'C' Programmable Serial Port Library Functions
'C' Programmable Application Development Module Developer's Guide
ProSoft Technology, Inc. Page 257 of 342
February 20, 2013
MVIsp_Gets
Syntax
int MVIsp_Gets(int comport, BYTE *str, BYTE term, int *len, DWORD timeout);
Parameters
comport port from which data is to be received
str pointer to array of bytes to receive data
term termination character of data
len number of bytes to receive / bytes received
timeout amount of time to wait to receive character
Description
This function receives an array of bytes from a serial port. comport must be
previously opened with MVIsp_Open.
str points to an array of bytes that will receive the data.
len points to the number of bytes to receive.
MVIsp_Gets retrieves bytes from the reception queue until either a byte is equal
to the termination character or the number of bytes pointed to by len are
retrieved. If a byte is retrieved that equals the termination character, the byte is
copied into the array str and the function returns.
All data received from a port is queued after reception from the serial port.
Therefore, some delay may occur between the time a character is received
across the serial line and the time the character is returned by MVIsp_Gets. This
function attempts to retrieve characters from the reception queue, and return
values correspond accordingly.
timeout specifies the amount of time in milliseconds to wait. If timeout is
TIMEOUT_ASAP, the function will return immediately if the queue is empty. If
timeout is TIMEOUT_FOREVER, the function will not return until an array of
bytes is retrieved from the reception queue successfully.
If the timeout elapses before the termination character or len bytes are received,
MVI_ERR_TIMEOUT is returned.
When MVIsp_Gets returns, it writes to the int pointed to by len the number of
bytes retrieved. len is written for successfully retrieved bytes as well as timeouts.
If the function returns because a termination character was retrieved, len
includes the termination character in the length.
Note: If handshaking is enabled and the reception queue is full, this API may pause transmissions
from the external device, and timeouts may then occur.
Return Value
MVI_SUCCESS bytes were retrieved successfully
MVI_ERR_NOACCESS comport has not been opened