Home / Autodocs / serial.device
NAME
- Read
-
read input from serial port
FUNCTION
This command causes a stream of characters to be read in from the serial port buffer. The number of characters is specified in io_Length.
The Query function can be used to check how many characters are currently waiting in the serial port buffer. If more characters are requested than are currently available, the ioRequest will be queued until it can be satisfied.
The best way to handle reads is to first Query to get the number of characters currently in the buffer. Then post a read request for that number of characters (or the maximum size of your buffer).
If zero characters are in the buffer, post a request for 1 character. When at least one is ready, the device will return it. Now start over with another Query.
Before the program exits, it must be sure to AbortIO() then WaitIO() any outstanding ioRequests.
The Query function can be used to check how many characters are currently waiting in the serial port buffer. If more characters are requested than are currently available, the ioRequest will be queued until it can be satisfied.
The best way to handle reads is to first Query to get the number of characters currently in the buffer. Then post a read request for that number of characters (or the maximum size of your buffer).
If zero characters are in the buffer, post a request for 1 character. When at least one is ready, the device will return it. Now start over with another Query.
Before the program exits, it must be sure to AbortIO() then WaitIO() any outstanding ioRequests.
INPUTS
- io_Message
-
A mn_ReplyPort is required
- io_Device
-
set by OpenDevice
- io_Unit
-
set by OpenDevice
- io_Command
-
CMD_READ
- io_Flags
-
If the IOB_QUICK bit is set, read will try to complete the IO quickly
- io_Length
-
number of characters to receive.
- io_Data
-
pointer to buffer
RESULT
- Error
-
if the Read succeded, then io_Error will be null. If the Read failed, then io_Error will be non-zero. io_Error will indicate problems such as parity mismatch, break, and buffer overrun. io_Actual may always be non-zero and the buffer may contain valid data.
SEE ALSO
serial.device/SDCMD_QUERY, serial.device/SDCMD_SETPARAMS
BUGS
Having multiple outstanding read IORequests at any one time will probably fail. Starting with 43.5, this should work.
Previous to 43.5 characters could be lost if a read terminated early due to status or error conditions.
Due to hardware deficiency, the character immediately following a break may be trashed or an extra character may be recognized containing garbage.
Previous to 43.5 characters could be lost if a read terminated early due to status or error conditions.
Due to hardware deficiency, the character immediately following a break may be trashed or an extra character may be recognized containing garbage.
NOTES
Old documentation mentioned a mode where io_Length was set to -1 for 0-terminated reads.
Starting with 43.5, 0-terminated reads are supported. io_Actual will include the trailing 0 byte.
SDCMD_QUERY will report all bytes in the buffer. A CMD_READ may still abort early to report status/error conditions that occurred at a specific byte. Note that subsequent status/error conditions are ignored until the current one has been "read".
Starting with 43.5, 0-terminated reads are supported. io_Actual will include the trailing 0 byte.
SDCMD_QUERY will report all bytes in the buffer. A CMD_READ may still abort early to report status/error conditions that occurred at a specific byte. Note that subsequent status/error conditions are ignored until the current one has been "read".