Create new callback mechanism for dApp status to the E2 Agent

* Implemented callback that is triggered each time the status of a dApp changes

* Added documentation of new functionalities and missing ones, and added new tests for new functionalities, bumped version to 0.0.2

Author: Ninjabippo1205

README.md

@@ -228,7 +228,11 @@ The main facade class for RAN vendors.
 | `is_running()` | Check if agent is running |
 | `register_sm(sm)` | Register a Service Model |
 | `get_available_ran_functions()` | Get available RAN function IDs from registered SMs |
+| `set_dapp_report_handler(handler)` | Set callback for incoming dApp reports (dApp → RAN) |
+| `set_dapp_status_changed_handler(handler)` | Set callback for dApp status changes (connect, disconnect, subscribe, unsubscribe) |
 | `send_indication(dapp_id, ran_function_id, data)` | Send an indication to a specific dApp |
+| `send_xapp_control(dapp_id, ran_function_id, data)` | Forward an xApp control action to a specific dApp |
+| `send_message_ack(request_id, response_code)` | Send a message acknowledgment (positive or negative) to a dApp |
 | `get_registered_dapps()` | Get list of registered dApp IDs |
 | `get_dapp_subscriptions(dapp_id)` | Get subscriptions for a dApp |
 | `get_ran_function_subscribers(ran_function_id)` | Get subscribers for a RAN function |

VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

examples/simple_agent.cpp

@@ -259,6 +259,13 @@ int main(int argc, char* argv[]) {
         return 1;
     }
 
+    // Handle dApp status changes (connect, subscribe, unsubscribe, disconnect)
+    agent.set_dapp_status_changed_handler([&agent]() {
+        std::cout << "[STATUS] dApp status changed — "
+                  << "dApps: " << agent.dapp_count()
+                  << ", subscriptions: " << agent.subscription_count() << "\n";
+    });
+
     // Handle dApp reports for the RAN
     agent.set_dapp_report_handler([](const libe3::DAppReport& report) {
         // In the RAN report is sent to the xApp through E2, here we just decode it as en example

include/libe3/c_api.h

@@ -44,6 +44,24 @@ typedef void (*e3_dapp_report_cb)(
     size_t report_data_len
 );
 
+/** Callback when dApp status changes (connect, disconnect, subscribe, unsubscribe). */
+typedef void (*e3_dapp_status_changed_cb)(void);
+
+/**
+ * @brief Set callback for dApp status changes.
+ *
+ * Called when a dApp connects, disconnects, subscribes, or unsubscribes.
+ * Pass NULL as \p handler to clear the callback.
+ *
+ * @param agent Agent handle
+ * @param handler Callback invoked on each dApp status change
+ * @return \ref e3_error_t (see \ref libe3::ErrorCode; 0 == SUCCESS)
+ */
+e3_error_t e3_agent_set_dapp_status_changed_handler(
+    e3_agent_handle_t* agent,
+    e3_dapp_status_changed_cb handler
+);
+
 /**
  * @brief Descriptor describing a ServiceModel implemented in C.
  *

include/libe3/e3_agent.hpp

@@ -26,6 +26,9 @@ class E3Interface;
 /** Callback for incoming dApp reports (dApp → RAN). Set before start() to handle reports. */
 using DAppReportHandler = std::function<void(const DAppReport&)>;
 
+/** Callback when dApp status changes (connect, disconnect, subscribe, unsubscribe). */
+using DAppStatusChangedHandler = std::function<void()>;
+
 /**
  * @brief E3Agent - Main façade for RAN vendor integration
  *
@@ -162,6 +165,13 @@ class E3Agent {
      */
     void set_dapp_report_handler(DAppReportHandler handler);
 
+    /**
+     * @brief Set callback for dApp status changes.
+     * Called when a dApp connects, disconnects, subscribes, or unsubscribes.
+     * Call before start().
+     */
+    void set_dapp_status_changed_handler(DAppStatusChangedHandler handler);
+
     // =========================================================================
     // Manual Operations
     // =========================================================================

include/libe3/e3_interface.hpp

@@ -34,6 +34,7 @@ class E3Agent;
 using SetupRequestHandler = std::function<ResponseCode(const SetupRequest&, SetupResponse&)>;
 using SubscriptionRequestHandler = std::function<ResponseCode(const SubscriptionRequest&)>;
 using DAppReportHandler = std::function<void(const DAppReport&)>;
+using DAppStatusChangedHandler = std::function<void()>;
 
 /**
  * @brief E3Interface - Internal protocol coordination
@@ -137,6 +138,12 @@ class E3Interface {
         dapp_report_handler_ = std::move(handler);
     }
 
+    void set_dapp_status_changed_handler(DAppStatusChangedHandler handler) {
+        dapp_status_changed_handler_ = std::move(handler);
+    }
+
+    void notify_dapp_status_changed();
+
 private:
     // Configuration
     E3Config config_;
@@ -160,6 +167,8 @@ class E3Interface {
     // Event handlers
     DAppReportHandler dapp_report_handler_;
 
+    DAppStatusChangedHandler dapp_status_changed_handler_;
+
     // =========================================================================
     // Thread Entry Points
     // =========================================================================

src/c_api.cpp

@@ -358,4 +358,23 @@ const char* e3_error_to_string(e3_error_t code) {
         default: return "UNKNOWN_ERROR_CODE";
     }
 }
+
+e3_error_t e3_agent_set_dapp_status_changed_handler(
+    e3_agent_handle_t* agent,
+    e3_dapp_status_changed_cb handler
+) {
+    if (!agent || !agent->agent) return static_cast<int>(ErrorCode::INVALID_PARAM);
+
+    if (!handler) {
+        agent->agent->set_dapp_status_changed_handler(DAppStatusChangedHandler{});
+        return static_cast<int>(ErrorCode::SUCCESS);
+    }
+
+    agent->agent->set_dapp_status_changed_handler(
+        [handler]() { handler(); }
+    );
+
+    return static_cast<int>(ErrorCode::SUCCESS);
+}
+
 } // extern "C"

src/core/e3_agent.cpp

@@ -23,6 +23,7 @@ struct E3Agent::Impl {
     E3Config config;
     std::unique_ptr<E3Interface> interface;
     DAppReportHandler dapp_report_handler;
+    DAppStatusChangedHandler dapp_status_changed_handler;
 
     explicit Impl(E3Config cfg) : config(std::move(cfg)) {}
 };
@@ -66,6 +67,10 @@ ErrorCode E3Agent::init() {
     if (impl_->dapp_report_handler) {
         impl_->interface->set_dapp_report_handler(impl_->dapp_report_handler);
     }
+
+    if (impl_->dapp_status_changed_handler) {
+        impl_->interface->set_dapp_status_changed_handler(impl_->dapp_status_changed_handler);
+    }
 
     E3_LOG_INFO(LOG_TAG) << "E3Agent initialized successfully";
     return ErrorCode::SUCCESS;
@@ -148,6 +153,13 @@ void E3Agent::set_dapp_report_handler(DAppReportHandler handler) {
     }
 }
 
+void E3Agent::set_dapp_status_changed_handler(DAppStatusChangedHandler handler) {
+    impl_->dapp_status_changed_handler = std::move(handler);
+    if (impl_->interface && impl_->dapp_status_changed_handler) {
+        impl_->interface->set_dapp_status_changed_handler(impl_->dapp_status_changed_handler);
+    }
+}
+
 // =========================================================================
 // Manual Operations
 // =========================================================================

src/core/e3_interface.cpp

@@ -200,6 +200,12 @@ ErrorCode E3Interface::register_sm(std::unique_ptr<ServiceModel> sm) {
     return SmRegistry::instance().register_sm(std::move(sm));
 }
 
+void E3Interface::notify_dapp_status_changed() {
+    if (dapp_status_changed_handler_) {
+        dapp_status_changed_handler_();
+    }
+}
+
 // =========================================================================
 // Thread Entry Points
 // =========================================================================
@@ -433,6 +439,7 @@ void E3Interface::handle_setup_request(const SetupRequest& request, uint32_t req
     if (result == ErrorCode::SUCCESS) {
         response_code = ResponseCode::POSITIVE;
         E3_LOG_INFO(LOG_TAG) << "dApp '" << request.dapp_name << "' registered with assigned ID " << assigned_dapp_id;
+        notify_dapp_status_changed();
     } else {
         E3_LOG_ERROR(LOG_TAG) << "Failed to register dApp '" << request.dapp_name << "': " << error_code_to_string(result);
     }
@@ -508,6 +515,9 @@ void E3Interface::handle_subscription_request(const SubscriptionRequest& request
             E3_LOG_INFO(LOG_TAG) << "Subscription added: dApp " << request.dapp_identifier
                                  << " -> RAN function " << request.ran_function_identifier
                                  << " (subscription_id=" << subscription_id << ")";
+            if (result == ErrorCode::SUCCESS) {
+                notify_dapp_status_changed();
+            }
         } else {
             E3_LOG_ERROR(LOG_TAG) << "Failed to add subscription: " 
                                   << error_code_to_string(result);
@@ -543,6 +553,7 @@ void E3Interface::handle_subscription_delete(const SubscriptionDelete& del, uint
     if (result == ErrorCode::SUCCESS) {
         response_code = ResponseCode::POSITIVE;
         E3_LOG_INFO(LOG_TAG) << "Subscription " << del.subscription_id << " removed for dApp " << del.dapp_identifier;
+        notify_dapp_status_changed();
     } else {
         E3_LOG_ERROR(LOG_TAG) << "Failed to remove subscription: "
                               << error_code_to_string(result);
@@ -610,6 +621,7 @@ void E3Interface::handle_dapp_disconnection(uint32_t dapp_id) {
     if (result == ErrorCode::SUCCESS) {
         E3_LOG_INFO(LOG_TAG) << "dApp " << dapp_id << " unregistered, " 
                              << subscriptions.size() << " subscriptions removed";
+        notify_dapp_status_changed();
     } else {
         E3_LOG_ERROR(LOG_TAG) << "Failed to unregister dApp " << dapp_id << ": "
                               << error_code_to_string(result);

tests/test_e3_agent.cpp

@@ -202,6 +202,71 @@ TEST(E3Agent_move_semantics) {
     ASSERT_EQ(funcs.size(), 1u);
 }
 
+TEST(E3Agent_set_dapp_status_changed_handler_before_init) {
+    E3Config config;
+    config.ran_identifier = "status-cb-test";
+
+    E3Agent agent(std::move(config));
+
+    bool called = false;
+    agent.set_dapp_status_changed_handler([&called]() {
+        called = true;
+    });
+
+    // Handler is stored but cannot fire until the agent is running and a
+    // dApp actually connects/subscribes. Verify that setting it before init
+    // does not crash and the agent initialises normally.
+    auto result = agent.init();
+    ASSERT_EQ(error_to_int(result), error_to_int(ErrorCode::SUCCESS));
+}
+
+TEST(E3Agent_set_dapp_status_changed_handler_after_init) {
+    E3Config config;
+    config.ran_identifier = "status-cb-after-init";
+
+    E3Agent agent(std::move(config));
+    agent.init();
+
+    bool called = false;
+    agent.set_dapp_status_changed_handler([&called]() {
+        called = true;
+    });
+
+    // Handler is forwarded to the already-created E3Interface.
+    // No crash, and agent state remains valid.
+    ASSERT_NE(state_to_int(agent.state()), state_to_int(AgentState::UNINITIALIZED));
+}
+
+TEST(E3Agent_set_dapp_status_changed_handler_nullptr_clears) {
+    E3Config config;
+    config.ran_identifier = "status-cb-clear";
+
+    E3Agent agent(std::move(config));
+
+    // Set a handler then clear it with an empty function.
+    agent.set_dapp_status_changed_handler([]() {});
+    agent.set_dapp_status_changed_handler(DAppStatusChangedHandler{});
+
+    auto result = agent.init();
+    ASSERT_EQ(error_to_int(result), error_to_int(ErrorCode::SUCCESS));
+}
+
+TEST(E3Agent_set_dapp_status_changed_handler_replace) {
+    E3Config config;
+    config.ran_identifier = "status-cb-replace";
+
+    E3Agent agent(std::move(config));
+
+    int counter = 0;
+    agent.set_dapp_status_changed_handler([&counter]() { counter = 1; });
+    agent.set_dapp_status_changed_handler([&counter]() { counter = 2; });
+
+    // The second handler should replace the first. Verify no crash and
+    // the agent still initialises correctly.
+    auto result = agent.init();
+    ASSERT_EQ(error_to_int(result), error_to_int(ErrorCode::SUCCESS));
+}
+
 TEST(E3Agent_destructor_stops) {
     bool was_running = false;
     {