Wall clock time, timezone and user-facing time formatting. More...

Macros
#define	TIME_STRING_REQUIRED_LENGTH 20
	Buffer size for common strings like "Wednesday" or "30 minutes ago".

#define	TIME_STRING_TIME_LENGTH 10
	Buffer size for a time, e.g.

#define	TIME_STRING_DATE_LENGTH 10
	Buffer size for a day and month, e.g.

#define	TIME_STRING_DAY_DATE_LENGTH 3
	Buffer size for a day of the month, e.g.

Functions
void	clock_init (void)
	Initialize the clock service.

void	clock_hourly_chime_arm (void)
	Arm the hourly chime.

void	clock_get_time_tm (struct tm *time_tm)
	Get the current local time from the RTC.

size_t	clock_format_time (char *buffer, uint8_t size, int16_t hours, int16_t minutes, bool add_space)
	Format a time of day according to the user's 12h/24h preference.

size_t	clock_copy_time_string_timestamp (char *buffer, uint8_t size, time_t timestamp)
	Same as clock_copy_time_string(), for a given timestamp.

size_t	clock_get_time_number (char *buffer, size_t buffer_size, time_t timestamp)
	Format a time as "7:30" or "15:00" depending on the user's 12h/24h preference.

size_t	clock_get_time_word (char *buffer, size_t buffer_size, time_t timestamp)
	Get the AM/PM designator of a time.

void	clock_get_event_relative_time_string (char number_buffer, int number_buffer_size, char word_buffer, int word_buffer_size, time_t timestamp, uint16_t duration, time_t current_day, bool all_day)
	Get the relative time string of an event, split in a number and a word.

void	clock_set_24h_style (bool is_24h_style)
	Set the user's time display style.

bool	clock_timezone_source_is_manual (void)
	Check whether the timezone is selected manually.

void	clock_set_manual_timezone_source (bool manual)
	Set the timezone source.

bool	clock_time_source_is_manual (void)
	Check whether the time is set manually.

void	clock_set_manual_time_source (bool manual)
	Set the time source.

void	clock_request_time_from_phone (void)
	Ask the phone to send its current time.

void	clock_get_timezone_region (char *region_name, const size_t buffer_size)
	Get the name of the current timezone region, e.g.

int16_t	clock_get_timezone_region_id (void)
	Get the current timezone region.

void	clock_set_timezone_by_region_id (uint16_t region_id)
	Switch to a timezone region and fire a time change event.

void	clock_set_time (time_t utc_time)
	Set the current UTC time and fire a time change event.

void	clock_get_friendly_date (char *buffer, int buf_size, time_t timestamp)
	Get a friendly date for a timestamp.

void	clock_get_since_time (char *buffer, int buf_size, time_t timestamp)
	Get a friendly time elapsed since a timestamp, e.g.

void	clock_get_until_time (char *buffer, int buf_size, time_t timestamp, int max_relative_hrs)
	Get a friendly time relative to a timestamp, e.g.

void	clock_get_until_time_without_fulltime (char *buffer, int buf_size, time_t timestamp, int max_relative_hrs)
	clock_get_until_time_capitalized() that never writes the time of day.

size_t	clock_get_date (char *buffer, int buf_size, time_t timestamp)
	Get the date in MM/DD format.

size_t	clock_get_date_tm (char buffer, int buf_size, const struct tm time_tm)
	Same as clock_get_date(), from a broken-down time.

size_t	clock_get_day_date (char *buffer, int buf_size, time_t timestamp)
	Get the day of the month in DD format.

size_t	clock_get_month_named_date (char *buffer, size_t buffer_size, time_t timestamp)
	Get the date as month name and day, e.g.

size_t	clock_get_month_named_abbrev_date (char *buffer, size_t buffer_size, time_t timestamp)
	Get the date as abbreviated month name and day, e.g.

void	clock_get_until_time_capitalized (char *buffer, int buf_size, time_t timestamp, int max_relative_hrs)
	Capitalized clock_get_until_time(), e.g.

const char *	clock_get_relative_daypart_string (time_t current_timestamp, uint32_t hours_in_the_future)
	Get a daypart phrase for a time in the future, e.g.

void	clock_hour_and_minute_add (int hour, int minute, int delta_minutes)
	Add minutes to a wall clock time, wrapping around 24 hours.

Detailed Description

Wall clock time, timezone and user-facing time formatting.

Keeps the RTC time and timezone, handles the time endpoint messages from the phone, tracks DST transitions and formats times and dates according to the user's 12h/24h preference and language. Entities shared with the app SDK are documented in the SDK's Wall Time group.

Macro Definition Documentation

◆ TIME_STRING_DATE_LENGTH

#define TIME_STRING_DATE_LENGTH 10

Buffer size for a day and month, e.g.

"04/27".

◆ TIME_STRING_DAY_DATE_LENGTH

#define TIME_STRING_DAY_DATE_LENGTH 3

Buffer size for a day of the month, e.g.

"27".

◆ TIME_STRING_REQUIRED_LENGTH

#define TIME_STRING_REQUIRED_LENGTH 20

Buffer size for common strings like "Wednesday" or "30 minutes ago".

◆ TIME_STRING_TIME_LENGTH

#define TIME_STRING_TIME_LENGTH 10

Buffer size for a time, e.g.

"14:20".

Function Documentation

◆ clock_copy_time_string_timestamp()

size_t clock_copy_time_string_timestamp	(	char *	buffer,
		uint8_t	size,
		time_t	timestamp
	)

Same as clock_copy_time_string(), for a given timestamp.

Parameters

[out]	buffer	Output buffer.
	size	Size of `buffer`.
	timestamp	Time to format.

Returns: Length of the formatted string, as returned by snprintf().

◆ clock_format_time()

size_t clock_format_time	(	char *	buffer,
		uint8_t	size,
		int16_t	hours,
		int16_t	minutes,
		bool	add_space
	)

Format a time of day according to the user's 12h/24h preference.

In 12h style, "AM" or "PM" is appended.

Parameters

[out]	buffer	Output buffer.
	size	Size of `buffer`.
	hours	Hour, 0-23.
	minutes	Minute, 0-59.
	add_space	Whether to add a space between the time and AM/PM.

Returns: Length of the formatted string, as returned by snprintf(); 0 if buffer is NULL or size is 0.

◆ clock_get_date()

size_t clock_get_date	(	char *	buffer,
		int	buf_size,
		time_t	timestamp
	)

Get the date in MM/DD format.

Parameters

[out]	buffer	Output buffer, at least TIME_STRING_DATE_LENGTH bytes.
	buf_size	Size of `buffer`.
	timestamp	Time to format.

Returns: Length of the formatted string, as returned by strftime().

◆ clock_get_date_tm()

size_t clock_get_date_tm	(	char *	buffer,
		int	buf_size,
		const struct tm *	time_tm
	)

Same as clock_get_date(), from a broken-down time.

Avoids a localtime_r() round trip in tick handlers, which already get a struct tm.

Parameters

[out]	buffer	Output buffer, at least TIME_STRING_DATE_LENGTH bytes.
	buf_size	Size of `buffer`.
	time_tm	Local time to format.

Returns: Length of the formatted string, as returned by strftime().

◆ clock_get_day_date()

size_t clock_get_day_date	(	char *	buffer,
		int	buf_size,
		time_t	timestamp
	)

Get the day of the month in DD format.

Parameters

[out]	buffer	Output buffer, at least TIME_STRING_DAY_DATE_LENGTH bytes.
	buf_size	Size of `buffer`.
	timestamp	Time to format.

Returns: Length of the formatted string, as returned by strftime().

◆ clock_get_event_relative_time_string()

void clock_get_event_relative_time_string	(	char *	number_buffer,
		int	number_buffer_size,
		char *	word_buffer,
		int	word_buffer_size,
		time_t	timestamp,
		uint16_t	duration,
		time_t	current_day,
		bool	all_day
	)

Get the relative time string of an event, split in a number and a word.

E.g. "10" and " MIN. TO", so they can be rendered in different fonts. Close to the event, the word is "Now" and the number empty; further away, the event time is used. All-day events and middle days of multi-day events give "Today" or "All day".

Parameters

[out]	number_buffer	Output buffer for the number.
	number_buffer_size	Size of `number_buffer`.
[out]	word_buffer	Output buffer for the word.
	word_buffer_size	Size of `word_buffer`.
	timestamp	Event start time.
	duration	Event duration, in minutes.
	current_day	Midnight of the day being displayed.
	all_day	Whether the event lasts all day.

◆ clock_get_friendly_date()

void clock_get_friendly_date	(	char *	buffer,
		int	buf_size,
		time_t	timestamp
	)

Get a friendly date for a timestamp.

"Today", "Yesterday" or "Tomorrow", the weekday name up to 5 days ahead, else e.g. "June 21".

Parameters

[out]	buffer	Output buffer.
	buf_size	Size of `buffer`.
	timestamp	Time to describe.

◆ clock_get_month_named_abbrev_date()

size_t clock_get_month_named_abbrev_date	(	char *	buffer,
		size_t	buffer_size,
		time_t	timestamp
	)

Get the date as abbreviated month name and day, e.g.

"Jul 16".

Parameters

[out]	buffer	Output buffer.
	buffer_size	Size of `buffer`.
	timestamp	Time to format.

Returns: Length of the formatted string.

◆ clock_get_month_named_date()

size_t clock_get_month_named_date	(	char *	buffer,
		size_t	buffer_size,
		time_t	timestamp
	)

Get the date as month name and day, e.g.

"July 16".

Parameters

[out]	buffer	Output buffer.
	buffer_size	Size of `buffer`.
	timestamp	Time to format.

Returns: Length of the formatted string.

◆ clock_get_relative_daypart_string()

const char * clock_get_relative_daypart_string	(	time_t	current_timestamp,
		uint32_t	hours_in_the_future
	)

Get a daypart phrase for a time in the future, e.g.

"this evening".

Covers today and tomorrow, then a single phrase for the day after and a catch-all beyond. The phrase is a lower bound, as in "Powered 'til at least ...".

Parameters

current_timestamp	Current time.
hours_in_the_future	Hours after `current_timestamp`.

Returns: Untranslated phrase, to be passed through i18n.

◆ clock_get_since_time()

void clock_get_since_time	(	char *	buffer,
		int	buf_size,
		time_t	timestamp
	)

Get a friendly time elapsed since a timestamp, e.g.

"Now" or "5 minutes ago".

Future timestamps are treated as now. Beyond 24 hours, or on another day, the date and time are used.

Parameters

[out]	buffer	Output buffer.
	buf_size	Size of `buffer`.
	timestamp	Time to describe.

◆ clock_get_time_number()

size_t clock_get_time_number	(	char *	buffer,
		size_t	buffer_size,
		time_t	timestamp
	)

Format a time as "7:30" or "15:00" depending on the user's 12h/24h preference.

AM/PM is not included; see clock_get_time_word(). Leading whitespace is stripped.

Parameters

[out]	buffer	Output buffer.
	buffer_size	Size of `buffer`.
	timestamp	Time to format.

Returns: Length of the formatted string.

◆ clock_get_time_tm()

void clock_get_time_tm ( struct tm * time_tm )

Get the current local time from the RTC.

Parameters

[out] time_tm Current local time.

◆ clock_get_time_word()

size_t clock_get_time_word	(	char *	buffer,
		size_t	buffer_size,
		time_t	timestamp
	)

Get the AM/PM designator of a time.

Use with clock_get_time_number() to form a full time.

Parameters

[out]	buffer	Output buffer; set to an empty string in 24h style.
	buffer_size	Size of `buffer`.
	timestamp	Time to format.

Returns: Length of the formatted string, 0 in 24h style.

◆ clock_get_timezone_region()

void clock_get_timezone_region	(	char *	region_name,
		const size_t	buffer_size
	)

Get the name of the current timezone region, e.g.

"America/Chicago".

Writes "---" if no timezone is set, or the UTC offset (e.g. "UTC-4") if the region is unknown.

Parameters

[out]	region_name	Output buffer, at least TIMEZONE_NAME_LENGTH bytes.
	buffer_size	Size of `region_name`.

◆ clock_get_timezone_region_id()

int16_t clock_get_timezone_region_id ( void )

Get the current timezone region.

Returns: Index of the current timezone in the timezone database.

◆ clock_get_until_time()

void clock_get_until_time	(	char *	buffer,
		int	buf_size,
		time_t	timestamp,
		int	max_relative_hrs
	)

Get a friendly time relative to a timestamp, e.g.

"Now" or "In 5 hours".

Past timestamps give "... ago". Beyond max_relative_hrs hours, or on another day, the date and time are used.

Parameters

[out]	buffer	Output buffer.
	buf_size	Size of `buffer`.
	timestamp	Time to describe.
	max_relative_hrs	Number of hours for which a relative time is used.

◆ clock_get_until_time_capitalized()

void clock_get_until_time_capitalized	(	char *	buffer,
		int	buf_size,
		time_t	timestamp,
		int	max_relative_hrs
	)

Capitalized clock_get_until_time(), e.g.

"NOW" or "IN 5 H".

Parameters

[out]	buffer	Output buffer.
	buf_size	Size of `buffer`.
	timestamp	Time to describe.
	max_relative_hrs	Number of hours for which a relative time is used.

◆ clock_get_until_time_without_fulltime()

void clock_get_until_time_without_fulltime	(	char *	buffer,
		int	buf_size,
		time_t	timestamp,
		int	max_relative_hrs
	)

clock_get_until_time_capitalized() that never writes the time of day.

Where the full form would include a time, only the day is written (e.g. "Yesterday", "Monday").

Parameters

[out]	buffer	Output buffer.
	buf_size	Size of `buffer`.
	timestamp	Time to describe.
	max_relative_hrs	Number of hours for which a relative time is used.

◆ clock_hour_and_minute_add()

void clock_hour_and_minute_add	(	int *	hour,
		int *	minute,
		int	delta_minutes
	)

Add minutes to a wall clock time, wrapping around 24 hours.

Parameters

[in,out]	hour	Hour, 0-23.
[in,out]	minute	Minute, 0-59.
	delta_minutes	Minutes to add, may be negative.

◆ clock_hourly_chime_arm()

void clock_hourly_chime_arm ( void )

Arm the hourly chime.

Call once the services it uses (system resources, alerts preferences, vibe pattern service) are initialized.

◆ clock_init()

void clock_init ( void )

Initialize the clock service.

Moves an invalid RTC time forward to the minimum valid boot timestamp, loads the timezone and starts the per-minute DST watch.

◆ clock_request_time_from_phone()

void clock_request_time_from_phone ( void )

Ask the phone to send its current time.

The phone answers with a set UTC and timezone message (sub-command 0x03). Does nothing if there is no system session.

◆ clock_set_24h_style()

void clock_set_24h_style ( bool is_24h_style )

Set the user's time display style.

Parameters

is_24h_style true for 24h style, false for 12h style.

◆ clock_set_manual_time_source()

void clock_set_manual_time_source ( bool manual )

Set the time source.

Parameters

manual true to set the time on the watch, false to use the phone's time.

◆ clock_set_manual_timezone_source()

void clock_set_manual_timezone_source ( bool manual )

Set the timezone source.

Parameters

manual true to use a timezone selected in settings, false to use the phone's timezone.

◆ clock_set_time()

void clock_set_time ( time_t utc_time )

Set the current UTC time and fire a time change event.

Parameters

utc_time New UTC time.

◆ clock_set_timezone_by_region_id()

void clock_set_timezone_by_region_id ( uint16_t region_id )

Switch to a timezone region and fire a time change event.

Parameters

region_id Index of the timezone in the timezone database.

◆ clock_time_source_is_manual()

bool clock_time_source_is_manual ( void )

Check whether the time is set manually.

With a manual source the user sets the time in settings; otherwise the phone sets it.

Returns: true if the time source is manual, false if it is the phone.

◆ clock_timezone_source_is_manual()

bool clock_timezone_source_is_manual ( void )

Check whether the timezone is selected manually.

With a manual source the user selects the timezone in settings; otherwise the phone sets it.

Returns: true if the timezone source is manual, false if it is the phone.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ TIME_STRING_DATE_LENGTH

◆ TIME_STRING_DAY_DATE_LENGTH

◆ TIME_STRING_REQUIRED_LENGTH

◆ TIME_STRING_TIME_LENGTH

Function Documentation

◆ clock_copy_time_string_timestamp()

◆ clock_format_time()

◆ clock_get_date()

◆ clock_get_date_tm()

◆ clock_get_day_date()

◆ clock_get_event_relative_time_string()

◆ clock_get_friendly_date()

◆ clock_get_month_named_abbrev_date()

◆ clock_get_month_named_date()

◆ clock_get_relative_daypart_string()

◆ clock_get_since_time()

◆ clock_get_time_number()

◆ clock_get_time_tm()

◆ clock_get_time_word()

◆ clock_get_timezone_region()

◆ clock_get_timezone_region_id()

◆ clock_get_until_time()

◆ clock_get_until_time_capitalized()

◆ clock_get_until_time_without_fulltime()

◆ clock_hour_and_minute_add()

◆ clock_hourly_chime_arm()

◆ clock_init()

◆ clock_request_time_from_phone()

◆ clock_set_24h_style()

◆ clock_set_manual_time_source()

◆ clock_set_manual_timezone_source()

◆ clock_set_time()

◆ clock_set_timezone_by_region_id()

◆ clock_time_source_is_manual()

◆ clock_timezone_source_is_manual()