From 3982a368700e1530f8f78e3a778dd50ab5c6592e Mon Sep 17 00:00:00 2001
From: Katze719 <pauldorn1234@gmail.com>
Date: Tue, 17 Mar 2026 18:49:19 +0100
Subject: [PATCH] feat: add serialMonitorPorts interface header

Adds hot-plug monitoring API for serial port connect/disconnect events.
Uses a background thread with a callback-based notification model.
---
 .../cpp_core/interface/serial_monitor_ports.h | 44 +++++++++++++++++++
 include/cpp_core/serial.h                     |  3 ++
 include/cpp_core/status_codes.h               |  1 +
 include/cpp_core/status_codes.hpp             |  2 +
 4 files changed, 50 insertions(+)
 create mode 100644 include/cpp_core/interface/serial_monitor_ports.h

diff --git a/include/cpp_core/interface/serial_monitor_ports.h b/include/cpp_core/interface/serial_monitor_ports.h
new file mode 100644
index 0000000..ed5f64a
--- /dev/null
+++ b/include/cpp_core/interface/serial_monitor_ports.h
@@ -0,0 +1,44 @@
+#pragma once
+#include "../error_callback.h"
+#include "../module_api.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @brief Start monitoring for serial-port hot-plug events.
+     *
+     * Registers a callback that is invoked whenever a serial port appears or
+     * disappears on the system (e.g. a USB-to-serial adapter is plugged in or
+     * removed). The monitoring runs on a background thread managed by the
+     * library.
+     *
+     * Only **one** monitor can be active at a time. Calling this function again
+     * replaces the previous callback. Pass `nullptr` as @p callback_fn to stop
+     * monitoring and release the background thread.
+     *
+     * @code{.c}
+     * void onChange(int event, const char *port) {
+     *     if (event == 1) printf("connected: %s\n", port);
+     *     else            printf("disconnected: %s\n", port);
+     * }
+     * serialMonitorPorts(onChange);
+     * // ... later ...
+     * serialMonitorPorts(nullptr);  // stop
+     * @endcode
+     *
+     * @param callback_fn Callback receiving:
+     *        - @p event 1 = port appeared (connected), 0 = port disappeared (disconnected).
+     *        - @p port  Null-terminated device identifier (e.g. "COM3", "/dev/ttyUSB0").
+     *                   Valid only for the duration of the callback.
+     * @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 serialMonitorPorts(void (*callback_fn)(int event, const char *port),
+                                       ErrorCallbackT error_callback = nullptr) -> int;
+
+#ifdef __cplusplus
+}
+#endif
diff --git a/include/cpp_core/serial.h b/include/cpp_core/serial.h
index 9401a7a..8aad9b7 100644
--- a/include/cpp_core/serial.h
+++ b/include/cpp_core/serial.h
@@ -25,3 +25,6 @@
 #include "interface/serial_set_read_callback.h"
 #include "interface/serial_set_write_callback.h"
 #include "interface/serial_write.h"
+
+// Port discovery
+#include "interface/serial_monitor_ports.h"
diff --git a/include/cpp_core/status_codes.h b/include/cpp_core/status_codes.h
index 46c5bc3..3dc3af7 100644
--- a/include/cpp_core/status_codes.h
+++ b/include/cpp_core/status_codes.h
@@ -18,5 +18,6 @@ enum class StatusCodes
     kClearBufferOutError = -11,
     kAbortReadError = -12,
     kAbortWriteError = -13,
+    kMonitorError = -14,
 };
 } // namespace cpp_core
diff --git a/include/cpp_core/status_codes.hpp b/include/cpp_core/status_codes.hpp
index 569b769..cd2c441 100644
--- a/include/cpp_core/status_codes.hpp
+++ b/include/cpp_core/status_codes.hpp
@@ -41,6 +41,8 @@ namespace cpp_core
         return "AbortReadError";
     case StatusCodes::kAbortWriteError:
         return "AbortWriteError";
+    case StatusCodes::kMonitorError:
+        return "MonitorError";
     }
     return "Unknown";
 }