Add error callback support to serial interface functions

- Introduced `ErrorCallbackT` type and added error callback parameter to multiple serial interface functions, enhancing error handling capabilities.
- Updated documentation to reflect changes in return values and parameters across various headers, ensuring clarity and consistency.

This update improves the robustness of the serial API by allowing users to handle errors more effectively.

Author: Katze719

include/cpp_core.h

@@ -12,6 +12,7 @@
  * offers the most convenient entry point.
  */
 
+#include "cpp_core/error_callback.h"
 #include "cpp_core/serial.h"
 #include "cpp_core/status_codes.h"
 #include "cpp_core/version.h"

include/cpp_core/error_callback.h

@@ -0,0 +1,15 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    using ErrorCallbackT = void (*)(
+        int         error_code,
+        const char *message
+    );
+
+#ifdef __cplusplus
+} // extern "C"
+#endif

include/cpp_core/interface/serial_abort_read.h

@@ -1,4 +1,5 @@
 #pragma once
+#include "../error_callback.h"
 #include "../module_api.h"
 #include <cstdint>
 
@@ -14,8 +15,12 @@ extern "C"
      * ::cpp_core::StatusCodes::kAbortReadError.
      *
      * @param handle Port handle.
+     * @return 0 on success or a negative error code on failure.
      */
-    MODULE_API void serialAbortRead(int64_t handle);
+    MODULE_API auto serialAbortRead(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int;
 
 #ifdef __cplusplus
 }

include/cpp_core/interface/serial_abort_write.h

@@ -1,4 +1,5 @@
 #pragma once
+#include "../error_callback.h"
 #include "../module_api.h"
 #include <cstdint>
 
@@ -14,8 +15,12 @@ extern "C"
      * ::cpp_core::StatusCodes::kAbortWriteError.
      *
      * @param handle Port handle.
+     * @return 0 on success or a negative error code on failure.
      */
-    MODULE_API void serialAbortWrite(int64_t handle);
+    MODULE_API auto serialAbortWrite(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int;
 
 #ifdef __cplusplus
 }

include/cpp_core/interface/serial_clear_buffer_in.h

@@ -1,4 +1,5 @@
 #pragma once
+#include "../error_callback.h"
 #include "../module_api.h"
 #include <cstdint>
 
@@ -14,8 +15,12 @@ extern "C"
      * has not yet read.
      *
      * @param handle Port handle.
+     * @return 0 on success or a negative error code on failure.
      */
-    MODULE_API void serialClearBufferIn(int64_t handle);
+    MODULE_API auto serialClearBufferIn(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int;
 
 #ifdef __cplusplus
 }

include/cpp_core/interface/serial_clear_buffer_out.h

@@ -1,4 +1,5 @@
 #pragma once
+#include "../error_callback.h"
 #include "../module_api.h"
 #include <cstdint>
 
@@ -14,8 +15,12 @@ extern "C"
      * remaining data.
      *
      * @param handle Port handle.
+     * @return 0 on success or a negative error code on failure.
      */
-    MODULE_API void serialClearBufferOut(int64_t handle);
+    MODULE_API auto serialClearBufferOut(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int;
 
 #ifdef __cplusplus
 }

include/cpp_core/interface/serial_close.h

@@ -1,4 +1,5 @@
 #pragma once
+#include "../error_callback.h"
 #include "../module_api.h"
 #include <cstdint>
 
@@ -16,7 +17,10 @@ extern "C"
      * @param handle Handle obtained from serialOpen().
      * @return 0 on success or a negative error code on failure.
      */
-    MODULE_API auto serialClose(int64_t handle) -> int;
+    MODULE_API auto serialClose(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int;
 
 #ifdef __cplusplus
 }

include/cpp_core/interface/serial_drain.h

@@ -1,4 +1,5 @@
 #pragma once
+#include "../error_callback.h"
 #include "../module_api.h"
 #include <cstdint>
 
@@ -29,7 +30,10 @@ extern "C"
      * @param handle Port handle.
      * @return 0 on success; negative ::cpp_core::StatusCodes value on error.
      */
-    MODULE_API auto serialDrain(int64_t handle) -> int;
+    MODULE_API auto serialDrain(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int;
 
 #ifdef __cplusplus
 }

include/cpp_core/interface/serial_get_ports_info.h

@@ -1,4 +1,5 @@
 #pragma once
+#include "../error_callback.h"
 #include "../module_api.h"
 
 #ifdef __cplusplus
@@ -25,7 +26,8 @@ extern "C"
             const char *location_id,
             const char *product_id,
             const char *vendor_id
-        )
+        ),
+        ErrorCallbackT error_callback = nullptr
     ) -> int;
 
 #ifdef __cplusplus

include/cpp_core/interface/serial_in_bytes_total.h

@@ -11,7 +11,7 @@ extern "C"
      * @brief Total number of bytes received since the port was opened.
      *
      * @param handle Port handle.
-     * @return Total number of bytes read.
+     * @return Total number of bytes read or a negative error code.
      */
     MODULE_API auto serialInBytesTotal(int64_t handle) -> int64_t;