refactor(c-api): add logging infrastructure and explicit MQTT error reporting

Author: Jan VL

include/sparkplug/edge_node.hpp

@@ -1,7 +1,7 @@
-// include/sparkplug/edge_node.hpp
 #pragma once
 
 #include "detail/compat.hpp"
+#include "logging.hpp"
 #include "mqtt_handle.hpp"
 #include "payload_builder.hpp"
 #include "sparkplug_b.pb.h"
@@ -129,13 +129,9 @@ class EdgeNode {
         username{}; ///< MQTT username for authentication (optional)
     std::optional<std::string>
         password{}; ///< MQTT password for authentication (optional)
-    std::optional<CommandCallback>
-        command_callback{}; ///< Optional callback for NCMD messages (subscribed before
-                            ///< NBIRTH)
-    std::optional<std::string>
-        primary_host_id{}; ///< Optional Primary Host Application ID. If set, EdgeNode
-                           ///< will subscribe to STATE/{primary_host_id} and wait for
-                           ///< {"online":true} before publishing NBIRTH/DBIRTH
+    std::optional<CommandCallback> command_callback{};
+    std::optional<std::string> primary_host_id{};
+    std::optional<LogCallback> log_callback{};
   };
 
   /**
@@ -179,6 +175,8 @@ class EdgeNode {
    */
   void set_tls(std::optional<TlsOptions> tls);
 
+  void set_log_callback(std::optional<LogCallback> callback);
+
   /**
    * @brief Connects to the MQTT broker and establishes a Sparkplug B session.
    *
@@ -424,6 +422,8 @@ class EdgeNode {
                          std::string_view target_device_id,
                          PayloadBuilder& payload);
 
+  void log(LogLevel level, std::string_view message) const noexcept;
+
 private:
   /**
    * @brief Tracks state for an individual device attached to this edge node.

include/sparkplug/host_application.hpp

@@ -1,7 +1,7 @@
-// include/sparkplug/host_application.hpp
 #pragma once
 
 #include "detail/compat.hpp"
+#include "logging.hpp"
 #include "mqtt_handle.hpp"
 #include "payload_builder.hpp"
 #include "sparkplug_b.pb.h"
@@ -19,21 +19,6 @@
 
 namespace sparkplug {
 
-/**
- * @brief Log severity levels for library diagnostics.
- */
-enum class LogLevel {
-  DEBUG = 0, ///< Detailed debugging information
-  INFO = 1,  ///< Informational messages
-  WARN = 2,  ///< Warning messages (potential issues)
-  ERROR = 3  ///< Error messages (serious problems)
-};
-
-/**
- * @brief Callback function type for receiving log messages from the library.
- */
-using LogCallback = std::function<void(LogLevel, std::string_view)>;
-
 /**
  * @brief Callback function type for receiving Sparkplug B messages.
  *

include/sparkplug/logging.hpp

@@ -0,0 +1,12 @@
+#pragma once
+
+#include <functional>
+#include <string_view>
+
+namespace sparkplug {
+
+enum class LogLevel { DEBUG = 0, INFO = 1, WARN = 2, ERROR = 3 };
+
+using LogCallback = std::function<void(LogLevel, std::string_view)>;
+
+} // namespace sparkplug

include/sparkplug/sparkplug_c.h

@@ -210,12 +210,10 @@ int sparkplug_publisher_set_tls(sparkplug_publisher_t* pub,
                                 const char* private_key_password,
                                 int enable_server_cert_auth);
 
-/**
- * @brief Connects the publisher to the MQTT broker.
- *
- * @param pub Publisher handle
- * @return 0 on success, -1 on failure
- */
+void sparkplug_publisher_set_log_callback(sparkplug_publisher_t* pub,
+                                          sparkplug_log_callback_t callback,
+                                          void* user_data);
+
 int sparkplug_publisher_connect(sparkplug_publisher_t* pub);
 
 /**

src/c_bindings.cpp

@@ -1,4 +1,3 @@
-// src/c_bindings.cpp
 #include "sparkplug/edge_node.hpp"
 #include "sparkplug/host_application.hpp"
 #include "sparkplug/payload_builder.hpp"
@@ -197,10 +196,35 @@ int sparkplug_publisher_set_tls(sparkplug_publisher_t* pub,
   return 0;
 }
 
+void sparkplug_publisher_set_log_callback(sparkplug_publisher_t* pub,
+                                          sparkplug_log_callback_t callback,
+                                          void* user_data) {
+  if (!pub) {
+    return;
+  }
+
+  if (callback) {
+    auto cpp_callback = [callback, user_data](sparkplug::LogLevel level,
+                                              std::string_view message) {
+      callback(static_cast<int>(level), message.data(), message.size(), user_data);
+    };
+    pub->impl.set_log_callback(std::move(cpp_callback));
+  } else {
+    pub->impl.set_log_callback(std::nullopt);
+  }
+}
+
 int sparkplug_publisher_connect(sparkplug_publisher_t* pub) {
   if (!pub)
     return -1;
-  return pub->impl.connect().has_value() ? 0 : -1;
+
+  auto result = pub->impl.connect();
+  if (!result.has_value()) {
+    auto error_msg = std::format("EdgeNode MQTT connection failed: {}", result.error());
+    pub->impl.log(sparkplug::LogLevel::ERROR, error_msg);
+    return -1;
+  }
+  return 0;
 }
 
 int sparkplug_publisher_disconnect(sparkplug_publisher_t* pub) {
@@ -869,7 +893,13 @@ int sparkplug_host_application_connect(sparkplug_host_application_t* host) {
   }
 
   auto result = host->impl.connect();
-  return result.has_value() ? 0 : -1;
+  if (!result.has_value()) {
+    auto error_msg =
+        std::format("HostApplication MQTT connection failed: {}", result.error());
+    host->impl.log(sparkplug::LogLevel::ERROR, error_msg);
+    return -1;
+  }
+  return 0;
 }
 
 int sparkplug_host_application_disconnect(sparkplug_host_application_t* host) {

src/edge_node.cpp

@@ -188,6 +188,11 @@ void EdgeNode::set_tls(std::optional<TlsOptions> tls) {
   config_.tls = std::move(tls);
 }
 
+void EdgeNode::set_log_callback(std::optional<LogCallback> callback) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  config_.log_callback = std::move(callback);
+}
+
 stdx::expected<void, std::string> EdgeNode::connect() {
   std::lock_guard<std::mutex> lock(mutex_);
 
@@ -870,4 +875,10 @@ EdgeNode::publish_device_command(std::string_view target_edge_node_id,
   return publish_message(client, topic_str, payload_data, qos, false);
 }
 
+void EdgeNode::log(LogLevel level, std::string_view message) const noexcept {
+  if (config_.log_callback) {
+    config_.log_callback.value()(level, message);
+  }
+}
+
 } // namespace sparkplug