Add modem control and configuration interfaces

include/cpp_core/interface/serial_get_baudrate.h

@@ -0,0 +1,26 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Query the current baud rate of an open serial port.
+     *
+     * Reads back the baud rate that the OS driver is currently using. Useful for
+     * verifying that serialOpen() or serialSetBaudrate() applied the requested
+     * value.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return Current baud rate in bit/s (>= 300) or a negative error code from ::cpp_core::StatusCodes.
+     */
+    MODULE_API auto serialGetBaudrate(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_get_cts.h

@@ -0,0 +1,26 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Read the current state of the Clear To Send (CTS) input line.
+     *
+     * CTS is asserted by the remote device to indicate it is ready to receive
+     * data. Polling this line is useful when manual flow-control logic is
+     * required instead of (or in addition to) automatic RTS/CTS flow control.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 1 if asserted (HIGH), 0 if de-asserted (LOW), or a negative error code from ::cpp_core::StatusCodes.
+     */
+    MODULE_API auto serialGetCts(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_get_data_bits.h

@@ -0,0 +1,22 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Query the current number of data bits of an open serial port.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return Current data bits (5-8) or a negative error code from ::cpp_core::StatusCodes.
+     */
+    MODULE_API auto serialGetDataBits(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_get_dcd.h

@@ -0,0 +1,26 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Read the current state of the Data Carrier Detect (DCD) input line.
+     *
+     * DCD is asserted by a modem when a carrier signal has been detected on the
+     * telephone line. For direct serial links it can serve as a general-purpose
+     * "connection alive" indicator.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 1 if asserted (HIGH), 0 if de-asserted (LOW), or a negative error code from ::cpp_core::StatusCodes.
+     */
+    MODULE_API auto serialGetDcd(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_get_dsr.h

@@ -0,0 +1,25 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Read the current state of the Data Set Ready (DSR) input line.
+     *
+     * DSR is asserted by the remote device to indicate it is powered on and
+     * ready to communicate. It is the counterpart to DTR.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 1 if asserted (HIGH), 0 if de-asserted (LOW), or a negative error code from ::cpp_core::StatusCodes.
+     */
+    MODULE_API auto serialGetDsr(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_get_flow_control.h

@@ -0,0 +1,22 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Query the current flow-control mode of an open serial port.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 0 = none, 1 = RTS/CTS, 2 = XON/XOFF, or a negative error code from ::cpp_core::StatusCodes.
+     */
+    MODULE_API auto serialGetFlowControl(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_get_parity.h

@@ -0,0 +1,22 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Query the current parity setting of an open serial port.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 0 = none, 1 = even, 2 = odd, or a negative error code from ::cpp_core::StatusCodes.
+     */
+    MODULE_API auto serialGetParity(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_get_ri.h

@@ -0,0 +1,25 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Read the current state of the Ring Indicator (RI) input line.
+     *
+     * RI is asserted by a modem to signal an incoming call. On non-modem
+     * hardware it can be repurposed as a general-purpose input signal.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 1 if asserted (HIGH), 0 if de-asserted (LOW), or a negative error code from ::cpp_core::StatusCodes.
+     */
+    MODULE_API auto serialGetRi(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_get_stop_bits.h

@@ -0,0 +1,22 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Query the current stop-bit setting of an open serial port.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 0 = 1 stop bit, 2 = 2 stop bits, or a negative error code from ::cpp_core::StatusCodes.
+     */
+    MODULE_API auto serialGetStopBits(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_send_break.h

@@ -0,0 +1,33 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Send a break condition on the serial line.
+     *
+     * A break is a sustained logic-LOW that lasts longer than a normal
+     * character frame. Many protocols rely on it:
+     *
+     * - **DMX512**: A break of >= 88 us marks the start of a new frame.
+     * - **LIN bus**: The master starts each frame with a 13-bit break.
+     * - **MODBUS RTU**: Some implementations use break for frame sync.
+     *
+     * The @p duration_ms parameter is a *minimum* - the actual break may be
+     * slightly longer due to OS scheduling.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param duration_ms Break duration in milliseconds (> 0).
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 0 on success or a negative error code from ::cpp_core::StatusCodes on error.
+     */
+    MODULE_API auto serialSendBreak(int64_t handle, int duration_ms, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_set_baudrate.h

@@ -0,0 +1,31 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Change the baud rate of an already-open serial port.
+     *
+     * The new rate takes effect immediately without closing and re-opening the
+     * port. All other line settings (data bits, parity, stop bits, flow control)
+     * remain unchanged.
+     *
+     * Typical use-case: a bootloader handshake starts at a safe 9600 baud and
+     * then both sides switch to a higher speed for the actual data transfer.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param baudrate New baud rate in bit/s (>= 300).
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 0 on success or a negative error code from ::cpp_core::StatusCodes on error.
+     */
+    MODULE_API auto serialSetBaudrate(int64_t handle, int baudrate,
+                                      ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_set_data_bits.h

@@ -0,0 +1,26 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Change the number of data bits on an already-open serial port.
+     *
+     * Takes effect immediately. All other line settings remain unchanged.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param data_bits Number of data bits (5-8).
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 0 on success or a negative error code from ::cpp_core::StatusCodes on error.
+     */
+    MODULE_API auto serialSetDataBits(int64_t handle, int data_bits,
+                                      ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_set_dtr.h

@@ -0,0 +1,28 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Set or clear the Data Terminal Ready (DTR) modem control line.
+     *
+     * DTR is commonly used for:
+     * - Signalling readiness to the remote device.
+     * - Triggering a board reset on Arduino-compatible hardware.
+     * - Half-duplex direction control on RS-485 adapters.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param state Non-zero to assert (HIGH), zero to de-assert (LOW).
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 0 on success or a negative error code from ::cpp_core::StatusCodes on error.
+     */
+    MODULE_API auto serialSetDtr(int64_t handle, int state, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/serial_set_flow_control.h

@@ -0,0 +1,38 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+#include <cstdint>
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Configure the flow-control mode for an open serial port.
+     *
+     * Flow control prevents buffer overruns when one side is slower than the
+     * other. Three modes are supported:
+     *
+     * | @p mode | Meaning                                       |
+     * |---------|-----------------------------------------------|
+     * | 0       | None - no flow control (default after open).  |
+     * | 1       | Hardware (RTS/CTS) - the UART automatically   |
+     * |         | de-asserts RTS when the RX buffer is full and |
+     * |         | pauses TX when CTS is de-asserted.            |
+     * | 2       | Software (XON/XOFF) - in-band control chars   |
+     * |         | `0x11` (XON) and `0x13` (XOFF) are sent to    |
+     * |         | pause/resume the remote transmitter.          |
+     *
+     * Changing the mode on an already-open port takes effect immediately.
+     *
+     * @param handle Port handle obtained from serialOpen().
+     * @param mode Flow-control mode: 0 = none, 1 = RTS/CTS, 2 = XON/XOFF.
+     * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
+     * @return 0 on success or a negative error code from ::cpp_core::StatusCodes on error.
+     */
+    MODULE_API auto serialSetFlowControl(int64_t handle, int mode, ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif