File serial.h¶
Go to the documentation of this file
/*
* cais - Communication Abstraction & I/O Substrate
* Projectum Lunare <https://github.com/projectum-lunare/cais>
* Copyright (C) 2026 Gustavo Veiga <gustavo.veiga@outlook.com.br>
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at https://mozilla.org/MPL/2.0/.
*/
#ifndef CAIS_SERIAL_H
#define CAIS_SERIAL_H
#include <stddef.h>
#include <cais/types.h>
#ifdef __cplusplus
extern "C" {
#endif
typedef struct serial_port cais_serial_t;
/*
* Serial flow control modes.
*/
typedef enum {
CAIS_SERIAL_FLOW_NONE = 0,
CAIS_SERIAL_FLOW_HARDWARE = 1, /* RTS/CTS */
CAIS_SERIAL_FLOW_SOFTWARE = 2 /* XON/XOFF */
} cais_serial_flow_t;
/*
* Serial parity modes.
*/
typedef enum {
CAIS_SERIAL_PARITY_NONE = 'n',
CAIS_SERIAL_PARITY_EVEN = 'e',
CAIS_SERIAL_PARITY_ODD = 'o',
CAIS_SERIAL_PARITY_MARK = 'm',
CAIS_SERIAL_PARITY_SPACE = 's'
} cais_serial_parity_t;
/*
* Serial stop bit counts.
*/
typedef enum {
CAIS_SERIAL_STOP_1 = 1,
CAIS_SERIAL_STOP_2 = 2
} cais_serial_stop_bits_t;
/*
* Serial data bit lengths.
*/
typedef enum {
CAIS_SERIAL_DATA_5 = 5,
CAIS_SERIAL_DATA_6 = 6,
CAIS_SERIAL_DATA_7 = 7,
CAIS_SERIAL_DATA_8 = 8
} cais_serial_data_bits_t;
/*
* Standard serial baud rates.
*/
typedef enum {
CAIS_SERIAL_BAUD_300 = 300,
CAIS_SERIAL_BAUD_1200 = 1200,
CAIS_SERIAL_BAUD_2400 = 2400,
CAIS_SERIAL_BAUD_4800 = 4800,
CAIS_SERIAL_BAUD_9600 = 9600,
CAIS_SERIAL_BAUD_19200 = 19200,
CAIS_SERIAL_BAUD_38400 = 38400,
CAIS_SERIAL_BAUD_57600 = 57600,
CAIS_SERIAL_BAUD_115200 = 115200
} cais_serial_baud_t;
/*
* Serial modem line states (RTS/DTR).
*/
typedef enum {
CAIS_SERIAL_LINE_IGNORE = -1,
CAIS_SERIAL_LINE_OFF = 0,
CAIS_SERIAL_LINE_ON = 1
} cais_serial_line_t;
/* Backward-compatible hardware signal line aliases */
typedef cais_line_state_t cais_serial_line_state_t;
#define CAIS_SERIAL_LINE_ERROR CAIS_LINE_ERROR
#define CAIS_SERIAL_LINE_LOW CAIS_LINE_LOW
#define CAIS_SERIAL_LINE_HIGH CAIS_LINE_HIGH
typedef struct cais_serial_opts {
int baud;
int data_bits;
char parity;
int stop_bits;
int flow_control;
int rts;
int dtr;
int timeout_ms;
} cais_serial_opts_t;
/*
* Opens a serial port for communication.
* Default flow control is CAIS_SERIAL_FLOW_NONE (0).
* Default timeout is -1 (blocking indefinitely).
* Hardware flow control (RTS/CTS) is only activated when explicitly requested.
* On failure, returns NULL and writes descriptive error text into err_buf (if non-NULL).
* Does not allocate dynamic heap memory for error strings.
*/
cais_serial_t *cais_serial_open(const char *path, const cais_serial_opts_t *opts, char *err_buf, size_t err_cap);
/*
* Writes data to the serial port.
* Returns:
* CAIS_OK : all requested bytes written, or partial bytes written before timeout.
* CAIS_AGAIN : timeout expired before any bytes could be accepted.
* CAIS_ERROR : fatal I/O or descriptor error.
* If written_bytes != NULL, stores the count of bytes successfully accepted.
*/
cais_status_t cais_serial_write(cais_serial_t *port, const char *buf, size_t len, size_t *written_bytes);
/*
* Reads data from the serial port.
* Returns:
* CAIS_OK : one or more bytes read into buf (*read_bytes populated).
* CAIS_AGAIN : timeout expired before any bytes became available.
* CAIS_ERROR : fatal I/O error or descriptor invalid.
* CAIS_UNSUPPORTED : timed read not supported on platform.
*
* If timeout_ms < 0, uses the port's configured timeout (from opts or cais_serial_set_timeout).
* If the effective timeout is < 0, blocks indefinitely until at least one byte is available.
* If the effective timeout is 0, performs a non-blocking check.
* If the effective timeout is > 0, waits up to timeout_ms milliseconds.
*/
cais_status_t cais_serial_read(cais_serial_t *port, char *buf, size_t max_len, size_t *read_bytes, int timeout_ms);
/*
* Configures the default I/O timeout in milliseconds for the serial port.
*/
cais_serial_status_t cais_serial_set_timeout(cais_serial_t *port, int timeout_ms);
/*
* Waits for the UART transmit buffer to drain completely (hardware drain).
* Returns CAIS_SERIAL_OK on success, or CAIS_SERIAL_ERROR on failure.
*/
cais_serial_status_t cais_serial_drain(cais_serial_t *port);
/*
* Controls the RTS and DTR modem lines of the UART.
* Returns CAIS_SERIAL_OK on success, CAIS_SERIAL_ERROR on I/O error,
* or CAIS_SERIAL_UNSUPPORTED if modem line control is not supported.
*/
cais_serial_status_t cais_serial_set_rts(cais_serial_t *port, cais_serial_line_t state);
cais_serial_status_t cais_serial_set_dtr(cais_serial_t *port, cais_serial_line_t state);
/*
* Queries the modem input lines (CTS, DSR, CD/DCD, RI).
* Returns CAIS_LINE_HIGH if asserted/high, CAIS_LINE_LOW if deasserted/low,
* or CAIS_LINE_ERROR on error or if unsupported.
*/
cais_line_state_t cais_serial_get_cts(cais_serial_t *port);
cais_line_state_t cais_serial_get_dsr(cais_serial_t *port);
cais_line_state_t cais_serial_get_cd(cais_serial_t *port);
cais_line_state_t cais_serial_get_ri(cais_serial_t *port);
/*
* Closes the serial port and frees allocated resources.
*/
void cais_serial_close(cais_serial_t *port);
#ifdef __cplusplus
}
#endif
#endif /* CAIS_SERIAL_H */