fbcom.bi portable serial control API
Queries and controls a serial port already opened with OPEN COM.
#include once "fbcom.bi"
using FB
result = ComGetStatus( file_number, status )
result = ComSetLines( file_number, mask, values )
result = ComSetBreak( file_number, enabled )
result = ComPurge( file_number, queues )
OPEN COM owns the serial byte stream and its file number. fbcom.bi adds portable modem status, queue information, break control, purge, and RTS/DTR control without exposing a native operating-system handle.
Every field in ComStatus has a fixed unsigned 32-bit representation. The fields are capabilities, lines, errors, rx_queued, and tx_queued. A capability bit is set only when the current operating system and device driver support the associated value or operation. Unsupported fields remain zero, so programs must test the capability mask before interpreting them.
The input and output line flags are COM_LINE_CTS, COM_LINE_DSR, COM_LINE_DCD, COM_LINE_RI, COM_LINE_RTS, and COM_LINE_DTR. ComSetLines changes only the RTS and DTR bits selected by its mask. A selected bit present in values is driven high.
ComSetBreak asserts or clears the transmitter break condition. ComPurge accepts COM_PURGE_RX, COM_PURGE_TX, or both. The error flags report break, framing, parity, overrun, and receive overflow when COM_CAP_ERRORS is available.
All four functions return zero on success and a nonzero runtime error on failure. A closed file, a file that is not an OPEN COM stream, or an operation missing from the capability mask is an error.
Syntax
#include once "fbcom.bi"
using FB
result = ComGetStatus( file_number, status )
result = ComSetLines( file_number, mask, values )
result = ComSetBreak( file_number, enabled )
result = ComPurge( file_number, queues )
Description
OPEN COM owns the serial byte stream and its file number. fbcom.bi adds portable modem status, queue information, break control, purge, and RTS/DTR control without exposing a native operating-system handle.
Every field in ComStatus has a fixed unsigned 32-bit representation. The fields are capabilities, lines, errors, rx_queued, and tx_queued. A capability bit is set only when the current operating system and device driver support the associated value or operation. Unsupported fields remain zero, so programs must test the capability mask before interpreting them.
The input and output line flags are COM_LINE_CTS, COM_LINE_DSR, COM_LINE_DCD, COM_LINE_RI, COM_LINE_RTS, and COM_LINE_DTR. ComSetLines changes only the RTS and DTR bits selected by its mask. A selected bit present in values is driven high.
ComSetBreak asserts or clears the transmitter break condition. ComPurge accepts COM_PURGE_RX, COM_PURGE_TX, or both. The error flags report break, framing, parity, overrun, and receive overflow when COM_CAP_ERRORS is available.
All four functions return zero on success and a nonzero runtime error on failure. A closed file, a file that is not an OPEN COM stream, or an operation missing from the capability mask is an error.
Example
#include Once "fbcom.bi"
Using FB
Dim As Integer port = FreeFile
Open Com "COM1:115200,N,8,1" For Binary As #port
If Err <> 0 Then End 1
Dim As ComStatus status
If ComGetStatus( port, status ) = 0 Then
Print "RX queued:"; status.rx_queued
Print "TX queued:"; status.tx_queued
End If
Close #port
Using FB
Dim As Integer port = FreeFile
Open Com "COM1:115200,N,8,1" For Binary As #port
If Err <> 0 Then End 1
Dim As ComStatus status
If ComGetStatus( port, status ) = 0 Then
Print "RX queued:"; status.rx_queued
Print "TX queued:"; status.tx_queued
End If
Close #port
Platform Differences
- The API is implemented by the supported DOS, Windows/Windows CE, Unix-family, AROS, RISC OS, and NuttX serial backends.
- Capabilities vary by operating system, serial adapter, device driver, and emulator. Portable code must not assume that modem lines or queue lengths are available.
See also