core.h File Reference

Core LwM2M client API. More...

#include <anj/init.h>
#include <anj/compat/net/anj_net_api.h>
#include <anj/defs.h>
#include <anj/dm/core.h>
#include <anj/lwm2m_send.h>

Go to the source code of this file.

Data Structures
struct	anj_configuration_struct

Macros
#define	ANJ_SUPPORTED_BINDING_MODES   "UT"

Typedefs
typedef void	anj_connection_status_callback_t(void *arg, anj_t *anj, anj_conn_status_t conn_status)
typedef struct anj_configuration_struct	anj_configuration_t

Enumerations
enum	anj_conn_status_t {   ANJ_CONN_STATUS_INITIAL , ANJ_CONN_STATUS_INVALID , ANJ_CONN_STATUS_FAILURE , ANJ_CONN_STATUS_BOOTSTRAPPING ,   ANJ_CONN_STATUS_BOOTSTRAPPED , ANJ_CONN_STATUS_REGISTERING , ANJ_CONN_STATUS_REGISTERED , ANJ_CONN_STATUS_SUSPENDED ,   ANJ_CONN_STATUS_ENTERING_QUEUE_MODE , ANJ_CONN_STATUS_QUEUE_MODE }
enum	anj_core_change_type_t { ANJ_CORE_CHANGE_TYPE_VALUE_CHANGED = 0 , ANJ_CORE_CHANGE_TYPE_ADDED = 1 , ANJ_CORE_CHANGE_TYPE_DELETED = 2 }

Functions
int	anj_core_init (anj_t *anj, const anj_configuration_t *config)
void	anj_core_step (anj_t *anj)
anj_time_duration_t	anj_core_next_step_time (anj_t *anj)
void	anj_core_server_obj_disable_executed (anj_t *anj, uint32_t timeout)
void	anj_core_server_obj_registration_update_trigger_executed (anj_t *anj)
void	anj_core_server_obj_bootstrap_request_trigger_executed (anj_t *anj)
void	anj_core_data_model_changed (anj_t *anj, const anj_uri_path_t *path, anj_core_change_type_t change_type)
void	anj_core_disable_server (anj_t *anj, anj_time_duration_t timeout)
void	anj_core_request_bootstrap (anj_t *anj)
void	anj_core_restart (anj_t *anj)
void	anj_core_request_update (anj_t *anj)
int	anj_core_shutdown (anj_t *anj)

Detailed Description

Core LwM2M client API.

Declares configuration, connection state, and main loop functions that drive the Anjay Lite client.

Macro Definition Documentation

ANJ_SUPPORTED_BINDING_MODES

#define ANJ_SUPPORTED_BINDING_MODES   "UT"

Typedef Documentation

anj_configuration_t

typedef struct anj_configuration_struct anj_configuration_t

Anjay Lite configuration. Provided in anj_core_init function.

anj_connection_status_callback_t

typedef void anj_connection_status_callback_t(void *arg, anj_t *anj, anj_conn_status_t conn_status)

Callback type for connection status change notifications.

This function is called whenever the connection state of the LwM2M client changes — e.g., transitioning from ANJ_CONN_STATUS_REGISTERING to ANJ_CONN_STATUS_REGISTERED, or entering Queue Mode.

Users may use this callback to monitor client connectivity and act accordingly (e.g., update UI, manage power states, or trigger other logic).

Parameters

arg	Opaque argument passed to the callback, as provided in anj_dm_device_object_init_t::reboot_cb_arg.
anj	Anjay object.
conn_status	New connection status value; see anj_conn_status_t.

Enumeration Type Documentation

anj_conn_status_t

enum anj_conn_status_t

This enum represents the possible states of a server connection.

Enumerator
ANJ_CONN_STATUS_INITIAL	Initial state of the client after startup. Anjay Lite will automatically attempt to transition to either ANJ_CONN_STATUS_BOOTSTRAPPING or ANJ_CONN_STATUS_REGISTERING, depending on the configuration. If the provided configuration is invalid or incomplete, the client will immediately transition to ANJ_CONN_STATUS_INVALID.
ANJ_CONN_STATUS_INVALID	Provided configuration is invalid and a connection cannot be established. This state is transient — the client will immediately transition to ANJ_CONN_STATUS_FAILURE to indicate a permanent failure.
ANJ_CONN_STATUS_FAILURE	Indicates that bootstrap or registration has permanently failed (i.e., all configured retry attempts have been exhausted). In this case, reinitialization of the Anjay Lite client is required to attempt a new connection cycle. This can be done by calling anj_core_restart.
ANJ_CONN_STATUS_BOOTSTRAPPING	Bootstrap process is ongoing.
ANJ_CONN_STATUS_BOOTSTRAPPED	Bootstrapping process has finished successfully.
ANJ_CONN_STATUS_REGISTERING	Registering process is ongoing.
ANJ_CONN_STATUS_REGISTERED	Registering/Updating process has finished successfully.
ANJ_CONN_STATUS_SUSPENDED	Connection is suspended. If the suspension was initiated by the server the client will remain suspended until the Disable Timeout (Resource /1/x/5) expires. If the suspension was initiated by the client application no action is taken until user decides to resume or timeout occurs.
ANJ_CONN_STATUS_ENTERING_QUEUE_MODE	Client is entering Queue Mode.
ANJ_CONN_STATUS_QUEUE_MODE	Client is in Queue Mode: new requests still can be sent to the server, but no new messages are received.

anj_core_change_type_t

enum anj_core_change_type_t

Contains information about the type of changes of the data model. Used in anj_core_data_model_changed function.

Enumerator
ANJ_CORE_CHANGE_TYPE_VALUE_CHANGED	Resource or Resource Instance value changed.
ANJ_CORE_CHANGE_TYPE_ADDED	Object Instance or Resource Instance added.
ANJ_CORE_CHANGE_TYPE_DELETED	Object Instance or Resource Instance deleted.

Function Documentation

anj_core_data_model_changed()

void anj_core_data_model_changed	(	anj_t *	anj,
		const anj_uri_path_t *	path,
		anj_core_change_type_t	change_type
	)

Informs the library that the application has modified the data model.

This function must be called whenever the application itself changes any Object, Instance, or Resource in the data model — i.e., when the change is not a direct result of an operation initiated by the LwM2M Server.

Typical examples where this function MUST be called:

• ANJ_CORE_CHANGE_TYPE_VALUE_CHANGED — a Resource or Resource Instance value was modified by the application logic (not by a Write/Execute from the Server). This may trigger a LwM2M Notify message.
  • Special case: if the Lifetime Resource of the Server object (Object ID: ANJ_OBJ_ID_SERVER) is changed, this will additionally trigger a registration update with the new lifetime value.
• ANJ_CORE_CHANGE_TYPE_ADDED — the application created a new Object Instance or Resource Instance. This may trigger a Notify, and for new Object Instances also a registration update.
• ANJ_CORE_CHANGE_TYPE_DELETED — the application removed an Object Instance or Resource Instance. This removes associated observations and attributes, and for Object Instances also triggers a registration update.

Warning

Do not call this for changes that are a direct result of LwM2M Server operations (e.g., after a Write or Create request). Such cases are handled internally by the library.

Parameters

anj	Anjay object.
path	Pointer to the path of the changed Resource or affected Instance.
change_type	Type of change; see anj_core_change_type_t.

anj_core_disable_server()

void anj_core_disable_server	(	anj_t *	anj,
		anj_time_duration_t	timeout
	)

Temporarily disables the LwM2M Server connection.

If the server is currently active and registered, a De-Register message will be sent before the connection is closed. If the server is already disabled, calling this function updates the disable timeout.

The server will be automatically re-enabled after the specified duration. To disable the server indefinitely, set timeout to ANJ_TIME_DURATION_INVALID.

Parameters

anj	Anjay object.
timeout	Duration of the disable period, expressed as anj_time_duration_t.

anj_core_init()

int anj_core_init	(	anj_t *	anj,
		const anj_configuration_t *	config
	)

Initializes the core of the Anjay Lite library. The anj object must be created and allocated by the user before calling this function.

Warning

User must ensure that real (calendar) time (see anj_time_real_now) is set correctly before calling this function. Many internal mechanisms depend on the monotonic clock. Significant adjustments of the clock (e.g. via NTP or manual update) after initialization may cause the library to behave incorrectly.

Parameters

anj	Anjay object to operate on.
config	Configuration structure.

Returns

0 on success, a non-zero value in case of an error.

anj_core_next_step_time()

anj_time_duration_t anj_core_next_step_time

(

anj_t *

anj

)

Returns the time until the next call to anj_core_step is required.

In most cases, the returned value will be ANJ_TIME_DURATION_ZERO, indicating that the main loop should call anj_core_step immediately.

However, in certain low-activity states, this function may return a positive value:

• If the client is in ANJ_CONN_STATUS_SUSPENDED, the value indicates the remaining time until the scheduled wake-up.
• If the client is in ANJ_CONN_STATUS_QUEUE_MODE, the value reflects the time remaining until the next scheduled Update or Notification.

This function is useful for optimizing power consumption or sleeping, allowing the main loop to wait the appropriate amount of time before calling anj_core_step again.

Note

For example, if the device is in Queue Mode and the next Update message is scheduled to be sent in 20 seconds and there is no active observations, this function will return anj_time_duration_t representing 20 seconds.

Returned value might become outdated if anj_core_change_type_t is called after this function returns. In such case, the application should call anj_core_next_step_time again to get an updated value.

This function allows the integration layer to optimize power consumption or sleep scheduling by delaying calls to anj_core_step until necessary.

Parameters

anj	Anjay object to operate on.

Returns

anj_time_duration_t until the next anj_core_step is required.

See also

anj_time_duration_t

anj_time_scalar_from_duration

anj_core_request_bootstrap()

void anj_core_request_bootstrap

(

anj_t *

anj

)

Forces the start of a Bootstrap sequence.

This function immediately initiates a client-side Bootstrap procedure, regardless of the current connection status.

Note

If a Bootstrap session is already active, this function has no effect.

Warning

If the client is in the ANJ_CONN_STATUS_SUSPENDED state due to a server-triggered Disable operation (see anj_core_server_obj_disable_executed), it is expected to remain disconnected until the disable timeout expires. Reconnecting earlier is technically possible, but it will cause the client to ignore the server's request to stay offline for the specified duration.

Parameters

anj	Anjay object.

anj_core_request_update()

void anj_core_request_update

(

anj_t *

anj

)

Forces to start a Registration Update sequence.

Note

If a registration session is not active, this function will have no effect.

Parameters

anj	Anjay object.

anj_core_restart()

void anj_core_restart

(

anj_t *

anj

)

Restarts the Anjay Lite client by resetting its internal state to ANJ_CONN_STATUS_INITIAL.

This fully reinitializes the LwM2M connection cycle and can be used after configuration changes, error recovery, or a user-triggered reset.

Actions performed:

• If the client is registered, a De-Register message is sent before the connection is closed.
• If Bootstrap or Registration is in progress, it is aborted immediately.

Warning

If the client is in the ANJ_CONN_STATUS_SUSPENDED state due to a server-triggered Disable operation (see anj_core_server_obj_disable_executed), it is expected to remain disconnected until the disable timeout expires. Reconnecting earlier is technically possible, but it will cause the client to ignore the server's request to stay offline for the specified duration.

Parameters

anj	Anjay object.

anj_core_server_obj_bootstrap_request_trigger_executed()

void anj_core_server_obj_bootstrap_request_trigger_executed

(

anj_t *

anj

)

Should be called when Bootstrap-Request Trigger resource of Server Object (/1/x/9) is executed.

Note

The bootstrap process will be scheduled but delayed until the currently processed LwM2M request is fully completed.

De-Register message will be sent to the server before the connection with Management Server is closed and Bootstrap is started.

Parameters

anj	Anjay object.

anj_core_server_obj_disable_executed()

void anj_core_server_obj_disable_executed	(	anj_t *	anj,
		uint32_t	timeout
	)

Should be called when the Disable Resource of the Server Object (/1/x/4) is executed.

Note

The disable process will be scheduled but delayed until the currently processed LwM2M request is fully completed.

A De-Register message will be sent to the server before the connection is closed.

Parameters

anj	Anjay object.
timeout	Timeout for which the server should remain disabled, in seconds. This value MUST be taken from the Disable Timeout Resource (/1/x/5) of the Server Object Instance corresponding to the LwM2M server that has executed the Resource. If that resource is not present, the default value of ANJ_DISABLE_TIMEOUT_DEFAULT_VALUE SHALL be used.

anj_core_server_obj_registration_update_trigger_executed()

void anj_core_server_obj_registration_update_trigger_executed

(

anj_t *

anj

)

Should be called when Registration Update Trigger Resource of Server Object (/1/x/8) is executed.

Note

The Update operation will be scheduled but delayed until the currently processed LwM2M request is fully completed.

Parameters

anj	Anjay object.

anj_core_shutdown()

int anj_core_shutdown

(

anj_t *

anj

)

Shuts down the Anjay Lite client instance.

This function halts all active LwM2M operations and clears the client's internal state. Once called, the anj object becomes unusable unless it is reinitialized using anj_core_init.

The following cleanup steps are performed:

• All queued Send operations are canceled and removed.
• All observation and attribute storage entries are deleted.
• Any ongoing LwM2M exchanges (e.g., registration, update, notification, Server-initiated requests) are terminated.

Note

LwM2M Objects registered via anj_dm_add_obj are user-managed. This function does not free or reset those objects; users are responsible for their manual deallocation if needed.

Internally, this function invokes a sequence of operations to tear down networking, including shutting down and closing sockets, and releasing network context state. If any of these steps return ANJ_NET_EAGAIN, indicating that the operation is not yet complete, this function will immediately return that value. In this case, the client is not yet fully shut down, and the function should be called again later to complete the process.

If any networking-related call returns an error other than ANJ_NET_EAGAIN, the client is still fully shut down internally, but some network resources (such as sockets or internal handles) may not have been properly released.

Warning

If shutdown fails due to networking errors, there is a risk that sockets or system-level resources allocated by the client will not be completely cleaned up. This is especially important in long-running processes or test environments where resource leaks could accumulate.

Note

If blocking behavior is acceptable, the shutdown can be safely handled in a loop:

int ret;
do {
    ret = anj_core_shutdown(&anj);
} while (ret == ANJ_NET_EAGAIN);

Parameters

anj	Pointer to the Anjay client instance to shut down.

Returns

0 on success, ANJ_NET_EAGAIN if shutdown is still in progress, or a different error code on failure.

anj_core_step()

void anj_core_step

(

anj_t *

anj

)

Main step function of the Anjay Lite library.

This function should be called regularly in the main application loop. It drives the internal state machine and handles all scheduled operations related to LwM2M communication (e.g., bootstrap, registration, notifications, Queue Mode transitions, etc.).

This function is non-blocking, unless a custom network implementation introduces blocking behavior.

Parameters

anj	Anjay object to operate on.