c_api.h File Reference

#include <stdint.h>
#include <stddef.h>
#include "libe3/error_codes.h"

Go to the source code of this file.

Classes
struct	e3_c_service_model_desc_t
	Descriptor describing a ServiceModel implemented in C. More...
struct	e3_config_t
	Configuration for creating an E3Agent from C. More...

Typedefs
typedef struct e3_agent_handle_s	e3_agent_handle_t
typedef struct e3_service_model_handle_s	e3_service_model_handle_t
typedef e3_error_t(*	e3_sm_init_cb) (void *sm_context)
typedef void(*	e3_sm_destroy_cb) (void *sm_context)
typedef e3_error_t(*	e3_sm_start_cb) (void *sm_context)
typedef void(*	e3_sm_stop_cb) (void *sm_context)
typedef int(*	e3_sm_is_running_cb) (void *sm_context)
typedef e3_error_t(*	e3_sm_process_control_cb) (e3_service_model_handle_t *sm_handle, void *sm_context, uint32_t request_message_id, uint32_t dapp_id, uint32_t ran_function_id, uint32_t control_id, const uint8_t *data, size_t data_len, uint32_t sequence_id)
typedef void(*	e3_dapp_report_cb) (uint32_t dapp_id, uint32_t ran_function_id, const uint8_t *report_data, size_t report_data_len, uint32_t sequence_id)
typedef void(*	e3_dapp_status_changed_cb) (void)

Functions
e3_error_t	e3_agent_set_dapp_status_changed_handler (e3_agent_handle_t *agent, e3_dapp_status_changed_cb handler)
	Set callback for dApp status changes.
e3_service_model_handle_t *	e3_service_model_create_from_c (const e3_c_service_model_desc_t *desc)
	Create a ServiceModel implementation backed by C callbacks.
void	e3_service_model_destroy (e3_service_model_handle_t *sm)
	Destroy a C-backed ServiceModel handle.
e3_error_t	e3_service_model_emit_indication (e3_service_model_handle_t *sm, uint32_t dapp_id, uint32_t ran_function_id, const uint8_t *data, size_t data_len)
	Emit an indication message from a ServiceModel to the outbound queue.
e3_error_t	e3_service_model_emit_message_ack (e3_service_model_handle_t *sm, uint32_t request_id, int response_code)
	Emit a message acknowledgment from a ServiceModel.
e3_agent_handle_t *	e3_agent_create_default ()
	Create/destroy an E3Agent handle.
e3_agent_handle_t *	e3_agent_create_with_config (const e3_config_t *config)
	Create a new E3Agent with the given configuration.
void	e3_agent_destroy (e3_agent_handle_t *agent)
	Destroy an E3Agent handle.
e3_error_t	e3_agent_init (e3_agent_handle_t *agent)
	Initialize the agent.
e3_error_t	e3_agent_start (e3_agent_handle_t *agent)
	Start the agent processing threads and accept dApp connections.
void	e3_agent_stop (e3_agent_handle_t *agent)
	Stop the agent and release runtime resources.
int	e3_agent_get_state (e3_agent_handle_t *agent)
	Get the agent state as an integer matching libe3::AgentState.
int	e3_agent_is_running (e3_agent_handle_t *agent)
	Query whether the agent is currently running.
e3_error_t	e3_agent_set_dapp_report_handler (e3_agent_handle_t *agent, e3_dapp_report_cb handler)
	Set callback for incoming dApp reports (dApp -> RAN).
uint32_t *	e3_agent_get_available_ran_functions (e3_agent_handle_t *agent, size_t *out_len)
	Return a newly-allocated array of available RAN function IDs.
uint32_t *	e3_agent_get_registered_dapps (e3_agent_handle_t *agent, size_t *out_len)
	Return a newly-allocated array of registered dApp IDs.
uint32_t *	e3_agent_get_dapp_subscriptions (e3_agent_handle_t *agent, uint32_t dapp_id, size_t *out_len)
	Return a newly-allocated array of RAN function IDs subscribed by a dApp.
uint32_t *	e3_agent_get_ran_function_subscribers (e3_agent_handle_t *agent, uint32_t ran_function_id, size_t *out_len)
	Return a newly-allocated array of dApp IDs subscribed to a RAN function.
uint32_t *	e3_agent_get_active_ran_functions (e3_agent_handle_t *agent, size_t *out_len)
	Return a newly-allocated array of RAN function IDs that currently have at least one subscriber (RAN role).
uint32_t	e3_agent_get_subscription_periodicity (e3_agent_handle_t *agent, uint32_t dapp_id, uint32_t ran_function_id)
	Get the reporting periodicity a dApp requested for a RAN function.
uint32_t *	e3_agent_get_subscription_telemetry_ids (e3_agent_handle_t *agent, uint32_t dapp_id, uint32_t ran_function_id, size_t *out_len)
	Get the telemetry IDs a dApp requested for a RAN function.
uint32_t *	e3_agent_get_subscription_control_ids (e3_agent_handle_t *agent, uint32_t dapp_id, uint32_t ran_function_id, size_t *out_len)
	Get the control IDs a dApp requested for a RAN function.
void	e3_agent_free_uint32_array (uint32_t *arr)
	Free an array previously returned by the e3_agent_get_* helpers.
e3_error_t	e3_agent_send_indication (e3_agent_handle_t *agent, uint32_t dapp_id, uint32_t ran_function_id, const uint8_t *data, size_t data_len)
	Send an indication message to a specific dApp.
e3_error_t	e3_agent_send_xapp_control (e3_agent_handle_t *agent, uint32_t dapp_id, uint32_t ran_function_id, const uint8_t *control_data, size_t control_data_len, uint32_t sequence_id)
	Send an xApp control action to a specific dApp (e.g. from E2/SM).
e3_error_t	e3_agent_send_message_ack (e3_agent_handle_t *agent, uint32_t request_id, int response_code)
	Send a message acknowledgment (e.g. ack a control/request from dApp).
size_t	e3_agent_dapp_count (e3_agent_handle_t *agent)
	Number of registered dApps known to the agent.
size_t	e3_agent_subscription_count (e3_agent_handle_t *agent)
	Total number of active subscriptions tracked by the agent.
e3_error_t	e3_agent_register_sm (e3_agent_handle_t *agent, e3_service_model_handle_t *sm)
	Register a ServiceModel implementation with the agent.

Typedef Documentation

e3_agent_handle_t

typedef struct e3_agent_handle_s e3_agent_handle_t

Definition at line 21 of file c_api.h.

e3_dapp_report_cb

typedef void(* e3_dapp_report_cb) (uint32_t dapp_id, uint32_t ran_function_id, const uint8_t *report_data, size_t report_data_len, uint32_t sequence_id)

Definition at line 46 of file c_api.h.

e3_dapp_status_changed_cb

typedef void(* e3_dapp_status_changed_cb) (void)

Callback when dApp status changes (connect, disconnect, subscribe, unsubscribe).

Definition at line 56 of file c_api.h.

e3_service_model_handle_t

typedef struct e3_service_model_handle_s e3_service_model_handle_t

Definition at line 22 of file c_api.h.

e3_sm_destroy_cb

typedef void(* e3_sm_destroy_cb) (void *sm_context)

Definition at line 27 of file c_api.h.

e3_sm_init_cb

typedef e3_error_t(* e3_sm_init_cb) (void *sm_context)

Definition at line 26 of file c_api.h.

e3_sm_is_running_cb

typedef int(* e3_sm_is_running_cb) (void *sm_context)

Definition at line 30 of file c_api.h.

e3_sm_process_control_cb

typedef e3_error_t(* e3_sm_process_control_cb) (e3_service_model_handle_t *sm_handle, void *sm_context, uint32_t request_message_id, uint32_t dapp_id, uint32_t ran_function_id, uint32_t control_id, const uint8_t *data, size_t data_len, uint32_t sequence_id)

Definition at line 31 of file c_api.h.

e3_sm_start_cb

typedef e3_error_t(* e3_sm_start_cb) (void *sm_context)

Definition at line 28 of file c_api.h.

e3_sm_stop_cb

typedef void(* e3_sm_stop_cb) (void *sm_context)

Definition at line 29 of file c_api.h.

Function Documentation

e3_agent_create_default()

e3_agent_handle_t * e3_agent_create_default

(

)

Create/destroy an E3Agent handle.

Create a new E3Agent with a default configuration.

The returned handle must be destroyed with e3_agent_destroy when no longer needed.

Returns

e3_agent_handle_t* on success, NULL on allocation error

Definition at line 186 of file c_api.cpp.

e3_agent_create_with_config()

e3_agent_handle_t * e3_agent_create_with_config

(

const e3_config_t *

config

)

Create a new E3Agent with the given configuration.

If config is NULL, behaves like e3_agent_create_default. String fields in config are copied; the caller may free them after the call. Use 0 or NULL for fields to keep library defaults (e.g. setup_port 0 → 9990).

Parameters

config

Configuration (ports, endpoints, link/transport layer, etc.)

Returns

e3_agent_handle_t* on success, NULL on allocation error

Definition at line 190 of file c_api.cpp.

e3_agent_dapp_count()

size_t e3_agent_dapp_count

(

e3_agent_handle_t *

agent

)

Number of registered dApps known to the agent.

Definition at line 418 of file c_api.cpp.

e3_agent_destroy()

void e3_agent_destroy

(

e3_agent_handle_t *

agent

)

Destroy an E3Agent handle.

This will free the underlying resources. If the agent is currently running, callers should stop it with e3_agent_stop first.

Definition at line 222 of file c_api.cpp.

e3_agent_free_uint32_array()

void e3_agent_free_uint32_array

(

uint32_t *

arr

)

Free an array previously returned by the e3_agent_get_* helpers.

Definition at line 376 of file c_api.cpp.

e3_agent_get_active_ran_functions()

uint32_t * e3_agent_get_active_ran_functions	(	e3_agent_handle_t *	agent,
		size_t *	out_len )

Return a newly-allocated array of RAN function IDs that currently have at least one subscriber (RAN role).

See e3_agent_get_available_ran_functions for ownership semantics.

Definition at line 339 of file c_api.cpp.

e3_agent_get_available_ran_functions()

uint32_t * e3_agent_get_available_ran_functions	(	e3_agent_handle_t *	agent,
		size_t *	out_len )

Return a newly-allocated array of available RAN function IDs.

The returned array is allocated with malloc and the caller must free it with e3_agent_free_uint32_array. The number of elements is written to out_len if non-NULL. Returns NULL and sets out_len to 0 if there are no entries or the handle is invalid.

Definition at line 315 of file c_api.cpp.

e3_agent_get_dapp_subscriptions()

uint32_t * e3_agent_get_dapp_subscriptions	(	e3_agent_handle_t *	agent,
		uint32_t	dapp_id,
		size_t *	out_len )

Return a newly-allocated array of RAN function IDs subscribed by a dApp.

Parameters

dapp_id

dApp identifier to query

Definition at line 327 of file c_api.cpp.

e3_agent_get_ran_function_subscribers()

uint32_t * e3_agent_get_ran_function_subscribers	(	e3_agent_handle_t *	agent,
		uint32_t	ran_function_id,
		size_t *	out_len )

Return a newly-allocated array of dApp IDs subscribed to a RAN function.

Parameters

ran_function_id

RAN function identifier to query

Definition at line 333 of file c_api.cpp.

e3_agent_get_registered_dapps()

uint32_t * e3_agent_get_registered_dapps	(	e3_agent_handle_t *	agent,
		size_t *	out_len )

Return a newly-allocated array of registered dApp IDs.

See e3_agent_get_available_ran_functions for ownership semantics.

Definition at line 321 of file c_api.cpp.

e3_agent_get_state()

int e3_agent_get_state

(

e3_agent_handle_t *

agent

)

Get the agent state as an integer matching libe3::AgentState.

Useful for callers in C to inspect agent status. Returns an int with the enum value; AgentState::ERROR is returned on invalid handle.

Definition at line 268 of file c_api.cpp.

e3_agent_get_subscription_control_ids()

uint32_t * e3_agent_get_subscription_control_ids	(	e3_agent_handle_t *	agent,
		uint32_t	dapp_id,
		uint32_t	ran_function_id,
		size_t *	out_len )

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

Caller must free the returned array with e3_agent_free_uint32_array().

Parameters

out_len

receives the number of elements (set to 0 on error/empty)

Returns

newly-allocated array, or NULL if empty/error

Definition at line 365 of file c_api.cpp.

e3_agent_get_subscription_periodicity()

uint32_t e3_agent_get_subscription_periodicity	(	e3_agent_handle_t *	agent,
		uint32_t	dapp_id,
		uint32_t	ran_function_id )

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 345 of file c_api.cpp.

e3_agent_get_subscription_telemetry_ids()

uint32_t * e3_agent_get_subscription_telemetry_ids	(	e3_agent_handle_t *	agent,
		uint32_t	dapp_id,
		uint32_t	ran_function_id,
		size_t *	out_len )

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

Caller must free the returned array with e3_agent_free_uint32_array().

Parameters

out_len

receives the number of elements (set to 0 on error/empty)

Returns

newly-allocated array, or NULL if empty/error

Definition at line 354 of file c_api.cpp.

e3_agent_init()

e3_error_t e3_agent_init

(

e3_agent_handle_t *

agent

)

Initialize the agent.

Prepares internal resources; must be called before e3_agent_start. Returns a e3_error_t (see libe3::ErrorCode; 0 == SUCCESS).

Definition at line 227 of file c_api.cpp.

e3_agent_is_running()

int e3_agent_is_running

(

e3_agent_handle_t *

agent

)

Query whether the agent is currently running.

Returns

1 if running, 0 otherwise (or on invalid handle)

Definition at line 273 of file c_api.cpp.

e3_agent_register_sm()

e3_error_t e3_agent_register_sm	(	e3_agent_handle_t *	agent,
		e3_service_model_handle_t *	sm )

Register a ServiceModel implementation with the agent.

Ownership of sm is transferred to the agent on success and callers must not free the handle after a successful call. On failure the caller retains ownership and should call e3_service_model_destroy.

Fails with E3_INVALID_PARAM if the descriptor the handle was built from carried no ran_function_data, or more than 32768 bytes of it, and with E3_SM_ALREADY_REGISTERED if another SM already holds the same RAN function id.

Returns

e3_error_t ErrorCode value (0 == success)

Definition at line 242 of file c_api.cpp.

e3_agent_send_indication()

e3_error_t e3_agent_send_indication	(	e3_agent_handle_t *	agent,
		uint32_t	dapp_id,
		uint32_t	ran_function_id,
		const uint8_t *	data,
		size_t	data_len )

Send an indication message to a specific dApp.

Parameters

agent	Agent handle
dapp_id	Target dApp identifier
ran_function_id	RAN function identifier
data	Pointer to E3SM-encoded payload (may be NULL)
data_len	Length of payload in bytes

Returns

e3_error_t (see libe3::ErrorCode; 0 == SUCCESS)

Definition at line 380 of file c_api.cpp.

e3_agent_send_message_ack()

e3_error_t e3_agent_send_message_ack	(	e3_agent_handle_t *	agent,
		uint32_t	request_id,
		int	response_code )

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

Parameters

agent	Agent handle
request_id	ID of the request being acknowledged
response_code	0 = positive (success), 1 = negative (failure)

Returns

e3_error_t (see libe3::ErrorCode; 0 == SUCCESS)

Definition at line 408 of file c_api.cpp.

e3_agent_send_xapp_control()

e3_error_t e3_agent_send_xapp_control	(	e3_agent_handle_t *	agent,
		uint32_t	dapp_id,
		uint32_t	ran_function_id,
		const uint8_t *	control_data,
		size_t	control_data_len,
		uint32_t	sequence_id )

Send an xApp control action to a specific dApp (e.g. from E2/SM).

Parameters

agent	Agent handle
dapp_id	Target dApp identifier
ran_function_id	RAN function identifier
control_data	Pointer to E3SM-encoded control payload (may be NULL if data_len is 0)
control_data_len	Length of payload in bytes
sequence_id	Correlation id from the E2SM-DAPP control header; the dApp carries it back on the control it re-issues, which is how the RAN matches the applied control to the xApp procedure that asked for it.

Returns

e3_error_t (see libe3::ErrorCode; 0 == SUCCESS)

Definition at line 393 of file c_api.cpp.

e3_agent_set_dapp_report_handler()

e3_error_t e3_agent_set_dapp_report_handler	(	e3_agent_handle_t *	agent,
		e3_dapp_report_cb	handler )

Set callback for incoming dApp reports (dApp -> RAN).

Pass NULL as handler to clear the callback.

Parameters

agent	Agent handle
handler	Callback invoked for each incoming dApp report

Returns

e3_error_t (see libe3::ErrorCode; 0 == SUCCESS)

Definition at line 278 of file c_api.cpp.

e3_agent_set_dapp_status_changed_handler()

e3_error_t e3_agent_set_dapp_status_changed_handler	(	e3_agent_handle_t *	agent,
		e3_dapp_status_changed_cb	handler )

Set callback for dApp status changes.

Called when a dApp connects, disconnects, subscribes, or unsubscribes. Pass NULL as handler to clear the callback.

Parameters

agent	Agent handle
handler	Callback invoked on each dApp status change

Returns

e3_error_t (see libe3::ErrorCode; 0 == SUCCESS)

Definition at line 437 of file c_api.cpp.

e3_agent_start()

e3_error_t e3_agent_start

(

e3_agent_handle_t *

agent

)

Start the agent processing threads and accept dApp connections.

Returns a e3_error_t (see libe3::ErrorCode; 0 == SUCCESS).

Definition at line 232 of file c_api.cpp.

e3_agent_stop()

void e3_agent_stop

(

e3_agent_handle_t *

agent

)

Stop the agent and release runtime resources.

Safe to call even if the agent is not running. Returns nothing; errors are ignored.

Definition at line 237 of file c_api.cpp.

e3_agent_subscription_count()

size_t e3_agent_subscription_count

(

e3_agent_handle_t *

agent

)

Total number of active subscriptions tracked by the agent.

Definition at line 423 of file c_api.cpp.

e3_service_model_create_from_c()

e3_service_model_handle_t * e3_service_model_create_from_c

(

const e3_c_service_model_desc_t *

desc

)

Create a ServiceModel implementation backed by C callbacks.

The returned pointer owns a C++ ServiceModel instance. The caller retains ownership until the model is registered with an agent via e3_agent_register_sm, at which point ownership is transferred to the agent and e3_service_model_destroy will no longer free the object.

Parameters

desc	Descriptor containing metadata and callback function pointers

Returns

e3_service_model_handle_t* on success, NULL on allocation error

Definition at line 127 of file c_api.cpp.

e3_service_model_destroy()

void e3_service_model_destroy

(

e3_service_model_handle_t *

sm

)

Destroy a C-backed ServiceModel handle.

If the model has been registered with an agent (ownership transferred), this function is a no-op and the agent takes responsibility for cleanup.

Definition at line 136 of file c_api.cpp.

e3_service_model_emit_indication()

e3_error_t e3_service_model_emit_indication	(	e3_service_model_handle_t *	sm,
		uint32_t	dapp_id,
		uint32_t	ran_function_id,
		const uint8_t *	data,
		size_t	data_len )

Emit an indication message from a ServiceModel to the outbound queue.

This is intended for C-backed ServiceModels. The message is forwarded by the internal publisher path.

Definition at line 143 of file c_api.cpp.

e3_service_model_emit_message_ack()

e3_error_t e3_service_model_emit_message_ack	(	e3_service_model_handle_t *	sm,
		uint32_t	request_id,
		int	response_code )

Emit a message acknowledgment from a ServiceModel.

Definition at line 170 of file c_api.cpp.