ntp.h File Reference

API for Network Time Protocol (NTP) client functionality. More...

#include <anj/init.h>
#include <anj/compat/net/anj_net_api.h>
#include <anj/defs.h>
#include <anj/persistence.h>

Go to the source code of this file.

Data Structures
struct	anj_ntp_configuration_struct

Macros
#define	ANJ_NTP_ERR_IN_PROGRESS   -1
#define	ANJ_NTP_ERR_CONFIGURATION   -2
#define	ANJ_NTP_ERR_OBJECT_CREATION_FAILED   -3

Typedefs
typedef void	anj_ntp_event_callback_t(void *arg, anj_ntp_t *ntp, anj_ntp_status_t status, anj_time_real_t synchronized_time)
typedef struct anj_ntp_configuration_struct	anj_ntp_configuration_t

Enumerations
enum	anj_ntp_status_t {   ANJ_NTP_STATUS_INITIAL , ANJ_NTP_STATUS_PERIOD_EXCEEDED , ANJ_NTP_STATUS_IN_PROGRESS , ANJ_NTP_STATUS_FINISHED_SUCCESSFULLY ,   ANJ_NTP_STATUS_FINISHED_WITH_ERROR , ANJ_NTP_STATUS_OBJECT_UPDATED }

Functions
int	anj_ntp_init (anj_t *anj, anj_ntp_t *ntp, const anj_ntp_configuration_t *config)
void	anj_ntp_step (anj_ntp_t *ntp)
int	anj_ntp_start (anj_ntp_t *ntp)
void	anj_ntp_terminate (anj_ntp_t *ntp)
int	anj_ntp_obj_store (anj_ntp_t *ntp, const anj_persistence_context_t *ctx)
int	anj_ntp_obj_restore (anj_ntp_t *ntp, const anj_persistence_context_t *ctx)

Detailed Description

API for Network Time Protocol (NTP) client functionality.

This module provides functions to synchronize the system time with NTP servers and adds support for the standard LwM2M NTP object (OID 3415). It allows initializing the NTP client, starting time synchronization, and retrieving the current time. Logic is based on callbacks and state machine, suitable for integration into the main application loop.

Typedef Documentation

anj_ntp_configuration_t

typedef struct anj_ntp_configuration_struct anj_ntp_configuration_t

NTP module configuration structure. Should be filled before passing to anj_ntp_init.

anj_ntp_event_callback_t

typedef void anj_ntp_event_callback_t(void *arg, anj_ntp_t *ntp, anj_ntp_status_t status, anj_time_real_t synchronized_time)

Callback type for NTP events.

This callback is invoked whenever the NTP module reports a new event, such as a status change or the completion of a time synchronization operation.

When the status is ANJ_NTP_STATUS_FINISHED_SUCCESSFULLY, the callback will also provide the synchronized time via the synchronized_time parameter.

Parameters

arg	Opaque user argument passed to the callback.
ntp	NTP object reporting the status change.
status	Current NTP status value; see anj_ntp_status_t.
synchronized_time	The synchronized time provided by the NTP module. Valid only when status is ANJ_NTP_STATUS_FINISHED_SUCCESSFULLY.

Enumeration Type Documentation

anj_ntp_status_t

enum anj_ntp_status_t

This enum represents the possible states of a NTP module.

Enumerator
ANJ_NTP_STATUS_INITIAL	Initial state of the module after startup. Start new NTP synchronization by calling anj_ntp_start.
ANJ_NTP_STATUS_PERIOD_EXCEEDED	The time since the last synchronization (successful or not) exceeds the NTP period resource value. NTP synchronization should be started. Call anj_ntp_start to initiate synchronization.
ANJ_NTP_STATUS_IN_PROGRESS	NTP synchronization is started and is currently in progress.
ANJ_NTP_STATUS_FINISHED_SUCCESSFULLY	NTP synchronization has finished successfully. New time is provided through callback. Time sync error resource is set to false. Last time sync resource is updated.
ANJ_NTP_STATUS_FINISHED_WITH_ERROR	NTP synchronization has finished with error. New time is not available. Time sync error resource is set to true. Last time sync resource is updated.
ANJ_NTP_STATUS_OBJECT_UPDATED	NTP object state has been updated by LwM2M Server and should be persisted.

Function Documentation

anj_ntp_init()

int anj_ntp_init	(	anj_t *	anj,
		anj_ntp_t *	ntp,
		const anj_ntp_configuration_t *	config
	)

Initializes NTP module internal state variable. Installs NTP object into Anjay instance. Last time sync resource is initialized to the time of initialization.

Parameters

anj	Anjay Lite instance.
ntp	Pointer to a variable that will hold the state of NTP module.
config	Configuration structure for the NTP module. Object pointed to by this pointer can be freed after this function returns, as it is copied internally.

Returns

0 on success, ANJ_NTP_ERR_CONFIGURATION if the provided configuration is invalid, ANJ_NTP_ERR_OBJECT_CREATION_FAILED if NTP object creation in Anjay instance failed.

anj_ntp_obj_restore()

int anj_ntp_obj_restore	(	anj_ntp_t *	ntp,
		const anj_persistence_context_t *	ctx
	)

Deserializes the LwM2M NTP Object from the persistence stream. Should be called after successful initialization of NTP module.

Reads NTP Object instance and its resources from the underlying medium via ctx->read.

Parameters

ntp	NTP Object context to fill.
ctx	Persistence context; must have anj_persistence_context_t::direction set to ANJ_PERSISTENCE_RESTORE.

Returns

0 on success, negative value on error.

anj_ntp_obj_store()

int anj_ntp_obj_store	(	anj_ntp_t *	ntp,
		const anj_persistence_context_t *	ctx
	)

Serializes the current LwM2M NTP Object into the persistence stream. Should be called before shutting down the application or when the NTP object state changes (ANJ_NTP_STATUS_OBJECT_UPDATED event).

Writes NTP Object instance and its resources to the underlying medium via ctx->write.

Parameters

ntp	NTP Object context to serialize.
ctx	Persistence context; must have anj_persistence_context_t::direction set to ANJ_PERSISTENCE_STORE.

Returns

0 on success, negative value on error.

anj_ntp_start()

int anj_ntp_start

(

anj_ntp_t *

ntp

)

Starts a new NTP time synchronization operation.

Parameters

ntp	NTP module state.

Returns

0 on success, ANJ_NTP_ERR_IN_PROGRESS if a download is already in progress.

anj_ntp_step()

void anj_ntp_step

(

anj_ntp_t *

ntp

)

Main step function of the Anjay Lite NTP module.

This function should be called regularly in the main application loop. It drives the internal state machine and handles all scheduled operations related to NTP time synchronization.

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

Parameters

ntp	NTP module state.

anj_ntp_terminate()

void anj_ntp_terminate

(

anj_ntp_t *

ntp

)

Terminates the current NTP time synchronization operation and cleans up the NTP module.

This function should be called when the synchronization is no longer needed or when an error condition requires aborting the process. It has effect only when the NTP module is in the ANJ_NTP_STATUS_IN_PROGRESS. If called in any other state, the function has no effect.

After calling this function, the module's status will transition to ANJ_NTP_STATUS_FINISHED_WITH_ERROR.

Subsequent calls to anj_ntp_step will complete the termination sequence by closing the UDP exchange and terminating the connection.

Parameters

ntp	NTP module state.