Feat/serial helpers

README.md

@@ -21,7 +21,7 @@ This repository does not provide a ready-to-load shared library by itself. It pr
 
 ## What It Provides
 
-- Header-only C-compatible serial API definitions under `include/cpp_core`
+- Header-only C++ API definitions with unmangled C linkage under `include/cpp_core`
 - Modern C++26 helper surface for `std::expected`-based error propagation, strong typed config values, and compile-time reflection helpers
 - A generated version surface used consistently across all platform bindings
 - An installable CMake package target: `cpp_core::cpp_core`
@@ -30,7 +30,7 @@ This repository does not provide a ready-to-load shared library by itself. It pr
 
 - `include/cpp_core/serial.h`: aggregated C ABI for serial operations
 - `include/cpp_core/status_code.h`: shared status-code model
-- `include/cpp_core/interface/get_version.h`: version struct and `getVersion`
+- `include/cpp_core/interface/meta.h`: metadata struct and exported `meta` function
 
 ## Quick Start
 
@@ -50,25 +50,22 @@ Use the exported headers in your implementation:
 
 ```cpp
 #include <cpp_core/serial.h>
-#include <cpp_core/interface/get_version.h>
+#include <cpp_core/interface/meta.h>
 
 auto serialOpen(
- void *port,
- int baudrate,
- int data_bits,
- int parity,
- int stop_bits,
+ const char *port,
+ const cpp_core::SerialConfig *config,
  ErrorCallbackT error_callback
 ) -> intptr_t;
 ```
 
 Read the version data baked into the checkout:
 
 ```cpp
-#include <cpp_core/interface/get_version.h>
+#include <cpp_core/interface/meta.h>
 
-cpp_core::Version version{};
-getVersion(&version);
+cpp_core::Meta metadata{};
+meta(&metadata);
 ```
 
 ## Building This Repository
@@ -94,29 +91,43 @@ The main aggregated interface lives in:
 #include <cpp_core/serial.h>
 ```
 
-The ABI is intentionally plain-C friendly: functions either return a status code, return a value-or-negative-status, or return an opaque handle-or-negative-status.
+The API requires a C++ compiler, while exported functions use unmangled C linkage through `MODULE_API`. Functions either return a status code, return a value-or-negative-status, or return an opaque handle-or-negative-status.
 
 Example:
 
 ```cpp
 MODULE_API auto serialOpen(
- void *port,
- int baudrate,
- int data_bits,
- int parity = 0,
- int stop_bits = 0,
+ const char *port,
+ const cpp_core::SerialConfig *config,
  ErrorCallbackT error_callback = nullptr
 ) -> intptr_t;
 ```
 
+Line settings and per-operation timeout settings use explicit configuration
+structures. `flow_mode` is applied as part of `serialOpen` together with the
+other line settings:
+
+```cpp
+constexpr auto serial_config = cpp_core::SerialConfig::make<
+ 115'200,
+ cpp_core::DataBits::kEight,
+ cpp_core::Parity::kNone,
+ cpp_core::StopBits::kOne,
+ cpp_core::FlowControl::kRtsCts>();
+constexpr auto timeout_config = cpp_core::SerialTimeoutConfig::make<50, 1>();
+
+const auto handle = serialOpen(port, &serial_config);
+const auto bytes_read = serialRead(handle, buffer, buffer_size, &timeout_config);
+```
+
 This model keeps the ABI easy to consume from TypeScript hosts, Rust, Python, or other FFI hosts without requiring C++ runtime coupling.
 
 For C++ callers, the helper surface includes:
 
 - `include/cpp_core/result.hpp`: `Result<T>`, `Status`, `forwardUnexpected(...)`, plus the native `std::expected` monadic operations
 - `include/cpp_core/scope_guard.hpp`: `onScopeExit(...)`, `onScopeFail(...)`, `onScopeSuccess(...)`, `defer(...)`
 - `include/cpp_core/strong_types.hpp`: arithmetic-preserving strong integral wrappers and enum conversion helpers
-- `include/cpp_core/serial_config.hpp`: typed config construction with `Result<SerialConfig>` validation helpers
+- `include/cpp_core/serial_config.hpp`: typed line and timeout config construction with validation helpers
 - `include/cpp_core/reflection.hpp`: GCC 16 / C++26 reflection helpers such as enum/member counts and names, plus public field counts and names
 
 ## Versioning
@@ -131,8 +142,8 @@ Version information is generated from Git during CMake configure and written int
 The version data is exposed through:
 
 - the `version` namespace in `include/cpp_core/version.hpp`
-- the `cpp_core::Version` struct
-- the `getVersion(cpp_core::Version *out)` ABI function
+- the `cpp_core::Meta` struct
+- the exported `meta(cpp_core::Meta *out)` ABI function
 
 ## Relationship to Platform Repositories
 

include/cpp_core/error_callback.h

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

include/cpp_core/interface/meta.h

@@ -0,0 +1,38 @@
+#pragma once
+#include "../module_api.h"
+#include "../version.hpp"
+
+namespace cpp_core
+{
+/**
+ * Build and source metadata for the loaded cpp_core-based library.
+ */
+struct Meta
+{
+ int major = version::MAJOR; ///< Semantic-version major component.
+ int minor = version::MINOR; ///< Semantic-version minor component.
+ int patch = version::PATCH; ///< Semantic-version patch component.
+ int commits_since_tag = version::GIT_COMMIT_COUNT; ///< Commits since the closest Git tag.
+ int is_dirty = version::GIT_IS_DIRTY ? 1 : 0; ///< 1 for uncommitted changes, otherwise 0.
+
+ const char *version_string = version::VERSION; ///< Complete generated version string.
+ const char *prerelease = version::PRERELEASE; ///< Prerelease identifier, or an empty string.
+ const char *prerelease_type = version::PRERELEASE_TYPE; ///< Prerelease kind such as `alpha` or `rc`.
+ const char *prerelease_number = version::PRERELEASE_NUMBER; ///< Prerelease number, or an empty string.
+
+ const char *git_tag = version::GIT_TAG; ///< Closest Git tag.
+ const char *git_describe_hash = version::GIT_DESCRIBE_HASH; ///< Hash component reported by Git describe.
+ const char *git_commit_hash_short = version::GIT_COMMIT_HASH_SHORT; ///< Abbreviated commit hash.
+ const char *git_commit_hash_full = version::GIT_COMMIT_HASH_FULL; ///< Full commit hash.
+ const char *git_commit_date = version::GIT_COMMIT_DATE; ///< Commit timestamp including timezone.
+ const char *git_branch = version::GIT_BRANCH; ///< Branch name used for the build.
+ const char *git_dirty_suffix = version::GIT_DIRTY_SUFFIX; ///< `-dirty` or an empty string.
+};
+} // namespace cpp_core
+
+/**
+ * @brief Copy metadata for the loaded library.
+ *
+ * @param[out] out Structure receiving the metadata. Passing `nullptr` is a no-op.
+ */
+MODULE_API void meta(cpp_core::Meta *out);

include/cpp_core/interface/serial_abort_read.h

@@ -3,23 +3,14 @@
 #include "../module_api.h"
 #include <cstdint>
 
-#ifdef __cplusplus
-extern "C"
-{
-#endif
-
- /**
- * @brief Abort a blocking read operation running in a different thread.
- *
- * The target read function returns immediately with
- * ::cpp_core::StatusCode::Io::kAbortReadError.
- *
- * @param handle Port handle.
- * @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::StatusCode on error.
- */
- MODULE_API auto serialAbortRead(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
-
-#ifdef __cplusplus
-}
-#endif
+/**
+ * @brief Abort a blocking read operation running in a different thread.
+ *
+ * The target read function returns immediately with
+ * ::cpp_core::StatusCode::Io::kAbortReadError.
+ *
+ * @param handle Port handle.
+ * @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::StatusCode on error.
+ */
+MODULE_API auto serialAbortRead(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;

include/cpp_core/interface/serial_abort_write.h

@@ -3,23 +3,14 @@
 #include "../module_api.h"
 #include <cstdint>
 
-#ifdef __cplusplus
-extern "C"
-{
-#endif
-
- /**
- * @brief Abort a blocking write operation running in a different thread.
- *
- * The target write function returns immediately with
- * ::cpp_core::StatusCode::Io::kAbortWriteError.
- *
- * @param handle Port handle.
- * @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::StatusCode on error.
- */
- MODULE_API auto serialAbortWrite(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
-
-#ifdef __cplusplus
-}
-#endif
+/**
+ * @brief Abort a blocking write operation running in a different thread.
+ *
+ * The target write function returns immediately with
+ * ::cpp_core::StatusCode::Io::kAbortWriteError.
+ *
+ * @param handle Port handle.
+ * @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::StatusCode on error.
+ */
+MODULE_API auto serialAbortWrite(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;

include/cpp_core/interface/serial_clear_buffer_in.h

@@ -3,23 +3,14 @@
 #include "../module_api.h"
 #include <cstdint>
 
-#ifdef __cplusplus
-extern "C"
-{
-#endif
-
- /**
- * @brief Clear (flush) the device's input buffer.
- *
- * Discards every byte the driver has already received but the application
- * has not yet read.
- *
- * @param handle Port handle.
- * @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::StatusCode on error.
- */
- MODULE_API auto serialClearBufferIn(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
-
-#ifdef __cplusplus
-}
-#endif
+/**
+ * @brief Clear (flush) the device's input buffer.
+ *
+ * Discards every byte the driver has already received but the application
+ * has not yet read.
+ *
+ * @param handle Port handle.
+ * @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::StatusCode on error.
+ */
+MODULE_API auto serialClearBufferIn(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;

include/cpp_core/interface/serial_clear_buffer_out.h

@@ -3,23 +3,14 @@
 #include "../module_api.h"
 #include <cstdint>
 
-#ifdef __cplusplus
-extern "C"
-{
-#endif
-
- /**
- * @brief Clear (flush) the device's output buffer.
- *
- * Blocks until all queued bytes have been transmitted and then discards any
- * remaining data.
- *
- * @param handle Port handle.
- * @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::StatusCode on error.
- */
- MODULE_API auto serialClearBufferOut(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
-
-#ifdef __cplusplus
-}
-#endif
+/**
+ * @brief Clear (flush) the device's output buffer.
+ *
+ * Blocks until all queued bytes have been transmitted and then discards any
+ * remaining data.
+ *
+ * @param handle Port handle.
+ * @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::StatusCode on error.
+ */
+MODULE_API auto serialClearBufferOut(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;

include/cpp_core/interface/serial_close.h

@@ -3,23 +3,14 @@
 #include "../module_api.h"
 #include <cstdint>
 
-#ifdef __cplusplus
-extern "C"
-{
-#endif
-
- /**
- * @brief Close a previously opened serial port.
- *
- * The handle becomes invalid after the call. Passing an already invalid
- * (<= 0) handle is a no-op.
- *
- * @param handle Handle obtained from serialOpen().
- * @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::StatusCode on error.
- */
- MODULE_API auto serialClose(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
-
-#ifdef __cplusplus
-}
-#endif
+/**
+ * @brief Close a previously opened serial port.
+ *
+ * The handle becomes invalid after the call. Passing an already invalid
+ * (<= 0) handle is a no-op.
+ *
+ * @param handle Handle obtained from serialOpen().
+ * @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::StatusCode on error.
+ */
+MODULE_API auto serialClose(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;