ProSoft Technology MVI69-ADM - Manual (Page 252)

Serial Port Library Functions MVI-ADM ♦ 'C' Programmable
Developer's Guide 'C' Programmable Application Development Module
Page 252 of 342 ProSoft Technology, Inc.
February 20, 2013
MVIsp_Getch
Syntax
int MVIsp_Getch(int comport, BYTE *ch, DWORD timeout);
Parameters
comport port from which data is to be received
ch pointer to BYTE to receive character
timeout amount of time to wait to receive character
Description
This function receives a single character from a serial port. comport must be
previously opened with MVIsp_Open.
ch points to a BYTE that will receive the character.
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_Getch.
This function attempts to retrieve a character 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 a character is
retrieved from the reception queue successfully.
If the reception queue is not empty, the oldest character is retrieved from the
queue and MVIsp_Getch returns MVI_SUCCESS. If the queue is empty,
MVIsp_Getch tries to retrieve a character from the queue until the timeout
elapses. If the timeout elapses before a character can be retrieved,
MVI_ERR_TIMEOUT is returned.
Return Value
MVI_SUCCESS a char was retrieved successfully
MVI_ERR_NOACCESS comport has not been opened
MVI_ERR_BADPARAM invalid pointer
MVI_ERR_TIMEOUT timeout elapsed before character retrieved
Example
BYTE ch;
if (MVIsp_Getch(COM1, &ch, 1000L) == MVI_SUCCESS)
putch((char)ch);
See Also
MVIsp_PutCh (page 251)
MVIsp_Gets (page 257)