time_source.h File Reference

Multi-source time fallback matrix (DETWS_ENABLE_TIME_SOURCE). More...

#include "ServerConfig.h"
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Typedefs
typedef uint32_t(*	TimeSourceFn) (void)
	A time source: returns the current Unix epoch seconds for this source, or 0 if it currently has no valid time.

Functions
bool	detws_time_source_add (const char *name, uint8_t priority, TimeSourceFn fn)
	Register a time source.
uint32_t	detws_time_now (void)
	Current best time.
const char *	detws_time_source_active (void)
	Name of the source that satisfied the last detws_time_now(), or nullptr.
void	detws_time_source_reset (void)
	Clear all registered sources.
size_t	detws_time_http_date (char *out, size_t out_cap)
	The current best time (detws_time_now, any registered NTP / GPS / RTC / ... source) formatted as an RFC 7231 IMF-fixdate into out.

Detailed Description

Multi-source time fallback matrix (DETWS_ENABLE_TIME_SOURCE).

A small, zero-heap registry of user-defined time sources (NTP, an RTC, GPS, a manually-set clock, ...). Each source is a callback returning the current Unix epoch seconds, or 0 when that source currently has no valid time. Sources are registered with a priority; detws_time_now() queries them in ascending priority order and returns the first nonzero result, so the device falls back automatically when its preferred clock is unavailable (e.g. GPS loses its fix -> RTC -> NTP). The validity rule lives in each user callback (return 0 when invalid/stale), keeping this layer a pure prioritizer.

Everything lives in a fixed BSS table (DETWS_TIME_SOURCE_MAX entries); no heap. The whole core is host-testable. The API is declared unconditionally and compiles to no-op stubs when DETWS_ENABLE_TIME_SOURCE is 0.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file time_source.h.

Typedef Documentation

TimeSourceFn

typedef uint32_t(* TimeSourceFn) (void)

A time source: returns the current Unix epoch seconds for this source, or 0 if it currently has no valid time.

Definition at line 36 of file time_source.h.

Function Documentation

detws_time_source_add()

bool detws_time_source_add	(	const char *	name,
		uint8_t	priority,
		TimeSourceFn	fn
	)

Register a time source.

Parameters

name	stable label (referenced by pointer; must outlive the source - point it at a string literal / static, like the rest of the lib).
priority	lower value = higher priority (queried first).
fn	the source callback.

Returns

true if registered; false if fn is null or the table is full.

Definition at line 101 of file time_source.cpp.

detws_time_now()

uint32_t detws_time_now

(

void

)

Current best time.

Queries registered sources in ascending priority and returns the first nonzero epoch (stopping at the first valid source). Returns 0 if none have valid time.

Definition at line 105 of file time_source.cpp.

Referenced by detws_time_http_date().

detws_time_source_active()

const char * detws_time_source_active

(

void

)

Name of the source that satisfied the last detws_time_now(), or nullptr.

Definition at line 109 of file time_source.cpp.

detws_time_source_reset()

void detws_time_source_reset

(

void

)

Clear all registered sources.

Definition at line 113 of file time_source.cpp.

detws_time_http_date()

size_t detws_time_http_date	(	char *	out,
		size_t	out_cap
	)

The current best time (detws_time_now, any registered NTP / GPS / RTC / ... source) formatted as an RFC 7231 IMF-fixdate into out.

Returns

bytes written, or 0 with an empty out when no source currently has a valid time.

This is what lets the HTTP Date: header be fed by whatever time source is enabled, not just NTP: register RTC / GPS / NTP via detws_time_source_add() and the header follows the priority.

Definition at line 122 of file time_source.cpp.

References detws_http_date(), and detws_time_now().