E3Agent - Main façade for RAN vendor integration. More...

#include <e3_agent.hpp>

Classes
struct	Impl
	E3Agent implementation details. More...

Public Member Functions
	E3Agent (E3Config config=E3Config{})
	Construct an E3Agent with configuration.
	~E3Agent ()
	Destructor - ensures clean shutdown.
	E3Agent (const E3Agent &)=delete
E3Agent &	operator= (const E3Agent &)=delete
	E3Agent (E3Agent &&) noexcept
E3Agent &	operator= (E3Agent &&) noexcept
ErrorCode	init ()
	Initialize the agent.
ErrorCode	start ()
	Start the agent.
void	stop ()
	Stop the agent.
AgentState	state () const noexcept
	Get current agent state.
bool	is_running () const noexcept
	Check if agent is running.
ErrorCode	register_sm (std::unique_ptr< ServiceModel > sm)
	Register a Service Model.
std::vector< uint32_t >	get_available_ran_functions () const
	Get available RAN function IDs.
void	set_dapp_report_handler (DAppReportHandler handler)
	Set callback for incoming dApp reports (dApp → RAN). Call before start(). When a dApp sends a DApp report, this callback is invoked.
void	set_dapp_status_changed_handler (DAppStatusChangedHandler handler)
	Set callback for dApp status changes. Called when a dApp connects, disconnects, subscribes, or unsubscribes. Call before start().
ErrorCode	send_indication (uint32_t dapp_id, uint32_t ran_function_id, const std::vector< uint8_t > &data)
	Send an indication message to a specific dApp.
ErrorCode	send_xapp_control (uint32_t dapp_id, uint32_t ran_function_id, const std::vector< uint8_t > &control_data, uint32_t sequence_id)
	Send an xApp control action to a specific dApp coming from the E2SM-DAPP.
ErrorCode	send_message_ack (uint32_t request_id, ResponseCode response_code)
	Send a message acknowledgment (e.g. ack a control/request from dApp).
void	set_setup_response_handler (SetupResponseHandler handler)
void	set_subscription_response_handler (SubscriptionResponseHandler handler)
void	set_indication_handler (IndicationHandler handler)
void	set_xapp_control_handler (XAppControlHandler handler)
void	set_message_ack_handler (MessageAckHandler handler)
std::optional< uint32_t >	dapp_id () const noexcept
	dApp identifier assigned by the RAN in SetupResponse.
std::vector< uint32_t >	subscribed_ran_functions () const
std::vector< uint32_t >	active_subscription_ids () const
ErrorCode	wait_for_setup (std::chrono::milliseconds timeout)
	Block until the dApp setup handshake completes.
ErrorCode	subscribe (uint32_t ran_function_id, std::vector< uint32_t > telemetry_ids, std::vector< uint32_t > control_ids, std::optional< uint32_t > sub_time=std::nullopt, std::optional< uint32_t > periodicity=std::nullopt, uint32_t *out_request_id=nullptr)
	Subscribe to a RAN function. Must be called after a positive setup.
ErrorCode	unsubscribe (uint32_t ran_function_id)
ErrorCode	send_control (uint32_t ran_function_id, uint32_t control_id, std::vector< uint8_t > action_data, uint32_t sequence_id=0, uint32_t *out_message_id=nullptr)
	Send a dApp control action to the RAN.
ErrorCode	send_report (uint32_t ran_function_id, std::vector< uint8_t > report_data, uint32_t sequence_id, uint32_t *out_message_id=nullptr)
	Send a dApp report to the RAN.
ErrorCode	release ()
std::vector< uint32_t >	get_registered_dapps () const
	Get list of registered dApp IDs.
std::vector< uint32_t >	get_dapp_subscriptions (uint32_t dapp_id) const
	Get subscriptions for a dApp.
std::vector< uint32_t >	get_ran_function_subscribers (uint32_t ran_function_id) const
	Get subscribers for a RAN function.
std::vector< uint32_t >	get_active_ran_functions () const
	Get the RAN functions that currently have at least one subscriber.
uint32_t	get_subscription_periodicity (uint32_t dapp_id, uint32_t ran_function_id) const
	Get the reporting periodicity a dApp requested for a RAN function.
std::vector< uint32_t >	get_subscription_telemetry_ids (uint32_t dapp_id, uint32_t ran_function_id) const
	Get the telemetry IDs a dApp requested for a RAN function.
std::vector< uint32_t >	get_subscription_control_ids (uint32_t dapp_id, uint32_t ran_function_id) const
	Get the control IDs a dApp requested for a RAN function.
const E3Config &	config () const noexcept
	Get current configuration.
size_t	dapp_count () const
	Get number of registered dApps.
size_t	subscription_count () const
	Get total number of active subscriptions.
	E3Agent (E3Config config)
	~E3Agent ()
ErrorCode	init ()
ErrorCode	start ()
void	stop ()
AgentState	state () const noexcept
bool	is_running () const noexcept
ErrorCode	send_indication (uint32_t dapp_id, uint32_t ran_function_id, const std::vector< uint8_t > &data)
ErrorCode	send_message_ack (uint32_t request_id, ResponseCode response_code)
ErrorCode	unsubscribe (uint32_t ran_function_id)
ErrorCode	send_control (uint32_t ran_function_id, uint32_t control_id, std::vector< uint8_t > action_data, uint32_t sequence_id=0)
ErrorCode	send_report (uint32_t ran_function_id, std::vector< uint8_t > report_data, uint32_t sequence_id)
ErrorCode	release ()
std::vector< uint32_t >	subscribed_ran_functions () const
std::vector< uint32_t >	active_subscription_ids () const
const E3Config &	config () const noexcept
size_t	dapp_count () const
size_t	subscription_count () const

Detailed Description

E3Agent - Main façade for RAN vendor integration.

This class is the primary entry point for integrating E3AP functionality into a RAN function (DU, CU-CP, CU-UP). It provides:

Simple lifecycle management (init, start, stop, destroy)
Service Model registration
Automatic routing of control actions to the correct Service Model
Thread-safe operation

Usage Example:

// Create agent with configuration
libe3::E3Config config;
config.link_layer = libe3::E3LinkLayer::ZMQ;
config.transport_layer = libe3::E3TransportLayer::IPC;
config.encoding = libe3::EncodingFormat::JSON;
// Set custom ports if needed
config.setup_port = 9990;
config.subscriber_port = 9999;
config.publisher_port = 9991;
 
libe3::E3Agent agent(config);
 
// Register Service Models
agent.register_sm(std::make_unique<MySpectrumSM>());
 
// Start the agent
if (agent.start() != libe3::ErrorCode::SUCCESS) {
    // Handle error
}
 
// ... agent runs, handling dApp connections and messages ...
 
// Shutdown
agent.stop();

Thread Safety: All public methods are thread-safe. The agent manages its own internal threads for protocol handling.

Definition at line 85 of file e3_agent.hpp.

Constructor & Destructor Documentation

◆ E3Agent() [1/4]

libe3::E3Agent::E3Agent ( E3Config config = E3Config{} )

explicit

Construct an E3Agent with configuration.

Parameters

config Agent configuration

Definition at line 41 of file e3_agent.cpp.

◆ ~E3Agent() [1/2]

libe3::E3Agent::~E3Agent ( )

Destructor - ensures clean shutdown.

Definition at line 47 of file e3_agent.cpp.

◆ E3Agent() [2/4]

libe3::E3Agent::E3Agent ( const E3Agent & )

delete

◆ E3Agent() [3/4]

libe3::E3Agent::E3Agent ( E3Agent && )

defaultnoexcept

◆ E3Agent() [4/4]

libe3::E3Agent::E3Agent ( E3Config config )

◆ ~E3Agent() [2/2]

libe3::E3Agent::~E3Agent ( )

Member Function Documentation

◆ active_subscription_ids() [1/2]

std::vector< uint32_t > libe3::E3Agent::active_subscription_ids ( ) const

Subscription IDs this dApp currently holds.

Definition at line 400 of file e3_agent.cpp.

◆ active_subscription_ids() [2/2]

std::vector< uint32_t > libe3::E3Agent::active_subscription_ids ( ) const

◆ config() [1/2]

const E3Config & libe3::E3Agent::config ( ) const

noexcept

Get current configuration.

Definition at line 321 of file e3_agent.cpp.

◆ config() [2/2]

const E3Config & libe3::E3Agent::config ( ) const

noexcept

◆ dapp_count() [1/2]

size_t libe3::E3Agent::dapp_count ( ) const

Get number of registered dApps.

Definition at line 329 of file e3_agent.cpp.

◆ dapp_count() [2/2]

size_t libe3::E3Agent::dapp_count ( ) const

◆ dapp_id()

std::optional< uint32_t > libe3::E3Agent::dapp_id ( ) const

noexcept

dApp identifier assigned by the RAN in SetupResponse.

Returns: nullopt until setup completes (or on RAN-role agents).

Definition at line 390 of file e3_agent.cpp.

◆ get_active_ran_functions()

std::vector< uint32_t > libe3::E3Agent::get_active_ran_functions ( ) const

Get the RAN functions that currently have at least one subscriber.

RAN role only. Unlike get_available_ran_functions() (which lists every registered Service Model), this returns only the RAN functions a dApp is actively subscribed to.

Returns: List of RAN function IDs with one or more subscribers

Definition at line 283 of file e3_agent.cpp.

◆ get_available_ran_functions()

std::vector< uint32_t > libe3::E3Agent::get_available_ran_functions ( ) const

Get available RAN function IDs.

Returns the RAN function IDs from all registered Service Models.

Definition at line 172 of file e3_agent.cpp.

◆ get_dapp_subscriptions()

std::vector< uint32_t > libe3::E3Agent::get_dapp_subscriptions ( uint32_t dapp_id ) const

Get subscriptions for a dApp.

Parameters

dapp_id dApp identifier

Returns: List of RAN function IDs the dApp is subscribed to

Definition at line 269 of file e3_agent.cpp.

◆ get_ran_function_subscribers()

std::vector< uint32_t > libe3::E3Agent::get_ran_function_subscribers ( uint32_t ran_function_id ) const

Get subscribers for a RAN function.

Parameters

ran_function_id RAN function identifier

Returns: List of dApp IDs subscribed to this RAN function

Definition at line 276 of file e3_agent.cpp.

◆ get_registered_dapps()

std::vector< uint32_t > libe3::E3Agent::get_registered_dapps ( ) const

Get list of registered dApp IDs.

Definition at line 262 of file e3_agent.cpp.

◆ get_subscription_control_ids()

std::vector< uint32_t > libe3::E3Agent::get_subscription_control_ids	(	uint32_t	dapp_id,
		uint32_t	ran_function_id ) const

Get the control IDs a dApp requested for a RAN function.

Returns: vector of control IDs (empty if none requested or subscription not found)

Definition at line 308 of file e3_agent.cpp.

◆ get_subscription_periodicity()

uint32_t libe3::E3Agent::get_subscription_periodicity	(	uint32_t	dapp_id,
		uint32_t	ran_function_id ) const

Get the reporting periodicity a dApp requested for a RAN function.

Returns: periodicity in microseconds, 0 if not set or subscription not found

Definition at line 290 of file e3_agent.cpp.

◆ get_subscription_telemetry_ids()

std::vector< uint32_t > libe3::E3Agent::get_subscription_telemetry_ids	(	uint32_t	dapp_id,
		uint32_t	ran_function_id ) const

Get the telemetry IDs a dApp requested for a RAN function.

Returns: vector of telemetry IDs (empty if none requested or subscription not found)

Definition at line 299 of file e3_agent.cpp.

◆ init() [1/2]

ErrorCode libe3::E3Agent::init ( )

Initialize the agent.

Initializes internal components but does not start processing. Must be called before start().

Returns: ErrorCode::SUCCESS on success; ErrorCode::ALREADY_INITIALIZED if already initialized

Definition at line 59 of file e3_agent.cpp.

◆ init() [2/2]

ErrorCode libe3::E3Agent::init ( )

◆ is_running() [1/2]

bool libe3::E3Agent::is_running ( ) const

noexcept

Check if agent is running.

Definition at line 144 of file e3_agent.cpp.

◆ is_running() [2/2]

bool libe3::E3Agent::is_running ( ) const

noexcept

◆ operator=() [1/2]

E3Agent & libe3::E3Agent::operator= ( const E3Agent & )

delete

◆ operator=() [2/2]

E3Agent & libe3::E3Agent::operator= ( E3Agent && )

defaultnoexcept

◆ register_sm()

ErrorCode libe3::E3Agent::register_sm ( std::unique_ptr< ServiceModel > sm )

Register a Service Model.

Service Models must be registered before start() is called. Each SM handles one or more RAN function IDs.

Parameters

sm	Service Model to register (ownership transferred)

Returns: ErrorCode::SUCCESS on success; ErrorCode::SM_ALREADY_REGISTERED if RAN function already has SM; ErrorCode::STATE_ERROR if agent is already running

Definition at line 152 of file e3_agent.cpp.

◆ release() [1/2]

ErrorCode libe3::E3Agent::release ( )

Send a ReleaseMessage. The dApp stays running until stop() is called.

Definition at line 451 of file e3_agent.cpp.

◆ release() [2/2]

ErrorCode libe3::E3Agent::release ( )

◆ send_control() [1/2]

ErrorCode libe3::E3Agent::send_control	(	uint32_t	ran_function_id,
		uint32_t	control_id,
		std::vector< uint8_t >	action_data,
		uint32_t	sequence_id = 0 )

◆ send_control() [2/2]

ErrorCode libe3::E3Agent::send_control	(	uint32_t	ran_function_id,
		uint32_t	control_id,
		std::vector< uint8_t >	action_data,
		uint32_t	sequence_id = 0,
		uint32_t *	out_message_id = nullptr )

Send a dApp control action to the RAN.

Parameters

sequence_id	correlation id of the xApp procedure this control re-issues; leave 0 for a control the dApp decided on its own.
out_message_id	when non-null, receives the assigned E3-MessageID on success, so the caller can correlate a later ack/response back to this send.

Definition at line 430 of file e3_agent.cpp.

◆ send_indication() [1/2]

ErrorCode libe3::E3Agent::send_indication	(	uint32_t	dapp_id,
		uint32_t	ran_function_id,
		const std::vector< uint8_t > &	data )

Send an indication message to a specific dApp.

Parameters

dapp_id	Target dApp identifier
ran_function_id	RAN function identifier
data	E3SM-encoded indication data

Returns: ErrorCode::SUCCESS on success

Definition at line 197 of file e3_agent.cpp.

◆ send_indication() [2/2]

ErrorCode libe3::E3Agent::send_indication	(	uint32_t	dapp_id,
		uint32_t	ran_function_id,
		const std::vector< uint8_t > &	data )

◆ send_message_ack() [1/2]

ErrorCode libe3::E3Agent::send_message_ack	(	uint32_t	request_id,
		ResponseCode	response_code )

Send a message acknowledgment (e.g. ack a control/request from dApp).

Parameters

request_id	ID of the request being acknowledged
response_code	ResponseCode::POSITIVE (0) or NEGATIVE (1)

Returns: ErrorCode::SUCCESS on success

Definition at line 249 of file e3_agent.cpp.

◆ send_message_ack() [2/2]

ErrorCode libe3::E3Agent::send_message_ack	(	uint32_t	request_id,
		ResponseCode	response_code )

◆ send_report() [1/2]

ErrorCode libe3::E3Agent::send_report	(	uint32_t	ran_function_id,
		std::vector< uint8_t >	report_data,
		uint32_t	sequence_id )

◆ send_report() [2/2]

ErrorCode libe3::E3Agent::send_report	(	uint32_t	ran_function_id,
		std::vector< uint8_t >	report_data,
		uint32_t	sequence_id,
		uint32_t *	out_message_id = nullptr )

Send a dApp report to the RAN.

Parameters

sequence_id	correlation id the dApp assigns to this detection. It is the head of the loop's chain and is mandatory on the wire.
out_message_id	when non-null, receives the assigned E3-MessageID on success, so the caller can correlate a later ack/response back to this send.

Definition at line 441 of file e3_agent.cpp.

◆ send_xapp_control()

ErrorCode libe3::E3Agent::send_xapp_control	(	uint32_t	dapp_id,
		uint32_t	ran_function_id,
		const std::vector< uint8_t > &	control_data,
		uint32_t	sequence_id )

Send an xApp control action to a specific dApp coming from the E2SM-DAPP.

Parameters

dapp_id	Target dApp identifier
ran_function_id	RAN function identifier
control_data	E3SM-encoded control payload
sequence_id	Correlation id from the E2SM-DAPP control header, so the dApp can carry it back on the control it re-issues.

Returns: ErrorCode::SUCCESS on success

Definition at line 226 of file e3_agent.cpp.

◆ set_dapp_report_handler()

void libe3::E3Agent::set_dapp_report_handler ( DAppReportHandler handler )

Set callback for incoming dApp reports (dApp → RAN). Call before start(). When a dApp sends a DApp report, this callback is invoked.

Definition at line 179 of file e3_agent.cpp.

◆ set_dapp_status_changed_handler()

void libe3::E3Agent::set_dapp_status_changed_handler ( DAppStatusChangedHandler handler )

Set callback for dApp status changes. Called when a dApp connects, disconnects, subscribes, or unsubscribes. Call before start().

Definition at line 186 of file e3_agent.cpp.

◆ set_indication_handler()

void libe3::E3Agent::set_indication_handler ( IndicationHandler handler )

Set callback for incoming IndicationMessage (RAN → dApp).

Definition at line 369 of file e3_agent.cpp.

◆ set_message_ack_handler()

void libe3::E3Agent::set_message_ack_handler ( MessageAckHandler handler )

Set callback for incoming MessageAck (RAN → dApp).

Definition at line 383 of file e3_agent.cpp.

◆ set_setup_response_handler()

void libe3::E3Agent::set_setup_response_handler ( SetupResponseHandler handler )

Set callback for incoming SetupResponse (RAN → dApp).

Definition at line 355 of file e3_agent.cpp.

◆ set_subscription_response_handler()

void libe3::E3Agent::set_subscription_response_handler ( SubscriptionResponseHandler handler )

Set callback for incoming SubscriptionResponse (RAN → dApp).

Definition at line 362 of file e3_agent.cpp.

◆ set_xapp_control_handler()

void libe3::E3Agent::set_xapp_control_handler ( XAppControlHandler handler )

Set callback for incoming XAppControlAction (xApp → dApp via RAN).

Definition at line 376 of file e3_agent.cpp.

◆ start() [1/2]

ErrorCode libe3::E3Agent::start ( )

Start the agent.

Starts the internal processing threads and begins accepting dApp connections. If not already initialized, calls init() first.

Returns: ErrorCode::SUCCESS on success

Definition at line 105 of file e3_agent.cpp.

◆ start() [2/2]

ErrorCode libe3::E3Agent::start ( )

◆ state() [1/2]

AgentState libe3::E3Agent::state ( ) const

noexcept

Get current agent state.

Definition at line 137 of file e3_agent.cpp.

◆ state() [2/2]

AgentState libe3::E3Agent::state ( ) const

noexcept

◆ stop() [1/2]

void libe3::E3Agent::stop ( )

Stop the agent.

Stops all processing threads and closes connections. The agent can be restarted with start().

Definition at line 127 of file e3_agent.cpp.

◆ stop() [2/2]

void libe3::E3Agent::stop ( )

◆ subscribe()

ErrorCode libe3::E3Agent::subscribe	(	uint32_t	ran_function_id,
		std::vector< uint32_t >	telemetry_ids,
		std::vector< uint32_t >	control_ids,
		std::optional< uint32_t >	sub_time = std::nullopt,
		std::optional< uint32_t >	periodicity = std::nullopt,
		uint32_t *	out_request_id = nullptr )

Subscribe to a RAN function. Must be called after a positive setup.

Parameters

out_request_id when non-null, receives the assigned E3-MessageID on success, so the caller can correlate the SubscriptionResponse (which echoes request_id) back to this subscribe call.

Definition at line 411 of file e3_agent.cpp.

◆ subscribed_ran_functions() [1/2]

std::vector< uint32_t > libe3::E3Agent::subscribed_ran_functions ( ) const

RAN functions this dApp is currently subscribed to.

Definition at line 395 of file e3_agent.cpp.

◆ subscribed_ran_functions() [2/2]

std::vector< uint32_t > libe3::E3Agent::subscribed_ran_functions ( ) const

◆ subscription_count() [1/2]

size_t libe3::E3Agent::subscription_count ( ) const

Get total number of active subscriptions.

Definition at line 341 of file e3_agent.cpp.

◆ subscription_count() [2/2]

size_t libe3::E3Agent::subscription_count ( ) const

◆ unsubscribe() [1/2]

ErrorCode libe3::E3Agent::unsubscribe ( uint32_t ran_function_id )

Send a SubscriptionDelete for a previously subscribed RAN function.

Definition at line 424 of file e3_agent.cpp.

◆ unsubscribe() [2/2]

ErrorCode libe3::E3Agent::unsubscribe ( uint32_t ran_function_id )

◆ wait_for_setup()

ErrorCode libe3::E3Agent::wait_for_setup ( std::chrono::milliseconds timeout )

Block until the dApp setup handshake completes.

Returns: SUCCESS on positive SetupResponse, CONNECTION_FAILED on negative, TIMEOUT if the wait elapses, INVALID_PARAM on RAN-role.

Definition at line 405 of file e3_agent.cpp.

The documentation for this class was generated from the following files:

/home/runner/work/libe3/libe3/include/libe3/e3_agent.hpp
/home/runner/work/libe3/libe3/swig/libe3_swig.hpp
/home/runner/work/libe3/libe3/src/core/e3_agent.cpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ E3Agent() [1/4]

◆ ~E3Agent() [1/2]

◆ E3Agent() [2/4]

◆ E3Agent() [3/4]

◆ E3Agent() [4/4]

◆ ~E3Agent() [2/2]

Member Function Documentation

◆ active_subscription_ids() [1/2]

◆ active_subscription_ids() [2/2]

◆ config() [1/2]

◆ config() [2/2]

◆ dapp_count() [1/2]

◆ dapp_count() [2/2]

◆ dapp_id()

◆ get_active_ran_functions()

◆ get_available_ran_functions()

◆ get_dapp_subscriptions()

◆ get_ran_function_subscribers()

◆ get_registered_dapps()

◆ get_subscription_control_ids()

◆ get_subscription_periodicity()

◆ get_subscription_telemetry_ids()

◆ init() [1/2]

◆ init() [2/2]

◆ is_running() [1/2]

◆ is_running() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ register_sm()

◆ release() [1/2]

◆ release() [2/2]

◆ send_control() [1/2]

◆ send_control() [2/2]

◆ send_indication() [1/2]

◆ send_indication() [2/2]

◆ send_message_ack() [1/2]

◆ send_message_ack() [2/2]

◆ send_report() [1/2]

◆ send_report() [2/2]

◆ send_xapp_control()

◆ set_dapp_report_handler()

◆ set_dapp_status_changed_handler()

◆ set_indication_handler()

◆ set_message_ack_handler()

◆ set_setup_response_handler()

◆ set_subscription_response_handler()

◆ set_xapp_control_handler()

◆ start() [1/2]

◆ start() [2/2]

◆ state() [1/2]

◆ state() [2/2]

◆ stop() [1/2]

◆ stop() [2/2]

◆ subscribe()

◆ subscribed_ran_functions() [1/2]

◆ subscribed_ran_functions() [2/2]

◆ subscription_count() [1/2]

◆ subscription_count() [2/2]

◆ unsubscribe() [1/2]

◆ unsubscribe() [2/2]

◆ wait_for_setup()