File espos_time_policy.h¶

FileList > espos_time > include > espos_time_policy.h

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "esp_err.h"
#include "espos_time.h"

Classes¶

Type	Name
struct	espos_time_policy_port_t
struct	espos_time_policy_t

Public Functions¶

Type	Name
size_t	espos_time_iso8601_format (int64_t unix_ms, char * buf, size_t n) Write `unix_ms` as "2026-09-07T10:12:13.456Z" into buf and return the length written.
int64_t	espos_time_iso8601_parse (const char * s) Parse an ISO 8601 timestamp — "2026-09-07T10:12:13.456Z", the shape a SignalK server puts on navigation.datetime — into unix milliseconds.
int64_t	espos_time_policy_at_ms (const espos_time_policy_t * p, int64_t mono_ms) What the clock read at monotonic stamp `mono_ms` — the call that makes a buffered value keep its own time.
void	espos_time_policy_init (espos_time_policy_t * p, const espos_time_policy_port_t * port, void * ctx, uint32_t stale_after_h) `stale_after_h` is CONFIG_ESPOS_TIME_RTC_STALE_H on a device: how long a time restored from RTC memory across a deep sleep still counts as known.
bool	espos_time_policy_is_synced (const espos_time_policy_t * p) Does the device know what time it is? True for any source that set the clock this boot; for SRC_RTC also only while the restored time is younger than `stale_after_h` .
int64_t	espos_time_policy_now_ms (const espos_time_policy_t * p) Unix milliseconds now, or 0 when no source has set the clock.
esp_err_t	espos_time_policy_set (espos_time_policy_t * p, int64_t unix_ms, espos_time_src_t src) Offer `unix_ms` from`src` .
esp_err_t	espos_time_policy_set_aged (espos_time_policy_t * p, int64_t unix_ms, espos_time_src_t src, int64_t prior_age_ms) espos_time_policy_set() for a value that was already`prior_age_ms` old when it arrived — the deep-sleep case, where the instant in RTC memory was recorded before the nap.

Public Functions Documentation¶

function espos_time_iso8601_format¶

Write unix_ms as "2026-09-07T10:12:13.456Z" into buf and return the length written.

size_t espos_time_iso8601_format (
    int64_t unix_ms,
    char * buf,
    size_t n
)

unix_ms of 0 or below, or a buffer shorter than ESPOS_TIME_ISO_MAX, yields "" and 0. Pure: no locale, no libc time conversion, no timezone — a fixed civil-calendar computation, which is also why it is testable on any host and identical on every target.

function espos_time_iso8601_parse¶

Parse an ISO 8601 timestamp — "2026-09-07T10:12:13.456Z", the shape a SignalK server puts on navigation.datetime — into unix milliseconds.

int64_t espos_time_iso8601_parse (
    const char * s
)

Accepts a missing fractional part, any number of fractional digits, and a numeric offset ("+02:00") as well as "Z". Returns 0 on anything it does not understand, which callers treat as "no time in this value".

function espos_time_policy_at_ms¶

What the clock read at monotonic stamp mono_ms — the call that makes a buffered value keep its own time.

int64_t espos_time_policy_at_ms (
    const espos_time_policy_t * p,
    int64_t mono_ms
)

Correct even when the sync happened after mono_ms was taken, because the offset applies to the whole timeline. 0 when unsynced.

function espos_time_policy_init¶

stale_after_h is CONFIG_ESPOS_TIME_RTC_STALE_H on a device: how long a time restored from RTC memory across a deep sleep still counts as known.

void espos_time_policy_init (
    espos_time_policy_t * p,
    const espos_time_policy_port_t * port,
    void * ctx,
    uint32_t stale_after_h
)

0 disables the staleness rule entirely.

function espos_time_policy_is_synced¶

Does the device know what time it is? True for any source that set the clock this boot; for SRC_RTC also only while the restored time is younger than stale_after_h .

bool espos_time_policy_is_synced (
    const espos_time_policy_t * p
)

A stale RTC time is still returned by now_ms() — it is the best guess available and better than nothing for a log prefix — but it is not represented as synced, and it does not stop a real source from replacing it.

function espos_time_policy_now_ms¶

Unix milliseconds now, or 0 when no source has set the clock.

int64_t espos_time_policy_now_ms (
    const espos_time_policy_t * p
)

function espos_time_policy_set¶

Offer unix_ms fromsrc .

esp_err_t espos_time_policy_set (
    espos_time_policy_t * p,
    int64_t unix_ms,
    espos_time_src_t src
)

Accepted when no clock is set, when src ranks at or above the source that set the current one (so a source may always refresh itself), and refused with ESP_ERR_INVALID_STATE otherwise — that is the whole of "a lower-ranked source never overrides SNTP once it synced". ESP_ERR_INVALID_ARG for a non-positive unix_ms or an out-of-range src.

function espos_time_policy_set_aged¶

espos_time_policy_set() for a value that was alreadyprior_age_ms old when it arrived — the deep-sleep case, where the instant in RTC memory was recorded before the nap.

esp_err_t espos_time_policy_set_aged (
    espos_time_policy_t * p,
    int64_t unix_ms,
    espos_time_src_t src,
    int64_t prior_age_ms
)

The staleness rule counts that age too, so a device that sleeps for two days does not wake up calling a two-day-old clock fresh. prior_age_ms below 0 is treated as 0.

The documentation for this class was generated from the following file espos_time/include/espos_time_policy.h