This contains all time functionality. More...

Modules

Types
Time specific types.

Functions

gos_result_t gos_time_get_uptime (uint64_t *uptime_ms_ptr)
Returns the system's uptime. More...
gos_result_t gos_time_get_current_utc_ms ( gos_utc_ms_t *utc_time_ms, bool add_timezone)
Returns the current UTC time in milliseconds. More...
gos_result_t gos_time_set_current_utc_ms ( gos_utc_ms_t time)
Sets the current time in milliseconds. More...
gos_result_t gos_time_get_current_utc_seconds ( gos_utc_seconds_t *utc_time_seconds_ptr, bool add_timezone)
Returns the current time in seconds. More...
gos_result_t gos_time_get_current_utc_as_iso8601 ( gos_iso8601_t *iso8601_struct, bool add_timezone)
Returns the current time as a gos_iso8601_t struct. More...
gos_result_t gos_time_get_current_utc_as_iso8601_str ( gos_iso8601_str_t *iso8601_str, bool add_timezone)
Returns the current time as a gos_iso8601_str_t . More...
gos_result_t gos_time_set_timezone_offset ( gos_timezone_offset_t offset)
Set the current timezone offset. More...
gos_result_t gos_time_get_timezone_offset ( gos_timezone_offset_t *offset_ptr)
Get the current timezone offset. More...
gos_result_t gos_time_get_ms_since_time_set (uint64_t *ms_since_last_set_ptr)
Return the number of milliseconds since the time was last set. More...
gos_result_t gos_time_utc_ms_to_iso8601 ( gos_utc_ms_t utc_ms, gos_timezone_offset_t timezone_offset, gos_iso8601_t *iso8601_struct)
Convert from UTC time in milliseconds to gos_iso8601_t struct. More...
gos_result_t gos_time_utc_ms_to_iso8601_str ( gos_utc_ms_t utc_ms, gos_timezone_offset_t timezone_offset, gos_iso8601_str_t *iso8601_str)
Convert from UTC time in milliseconds to gos_iso8601_str_t struct. More...
gos_result_t gos_time_iso8601_to_utc_ms (const gos_iso8601_t *iso8601_struct, gos_utc_ms_t *utc_ms_ptr)
Convert from gos_iso8601_t to UTC time in milliseconds. More...
gos_result_t gos_time_iso8601_to_str (const gos_iso8601_t *iso8601_struct, gos_iso8601_str_t *iso8601_str)
Convert from gos_iso8601_t to gos_iso8601_str_t . More...

Detailed Description

This contains all time functionality.

Function Documentation

gos_time_get_current_utc_as_iso8601()

gos_result_t gos_time_get_current_utc_as_iso8601 ( gos_iso8601_t * iso8601_struct,
bool add_timezone
)

Returns the current time as a gos_iso8601_t struct.

This has similar functionality to gos_time_get_current_utc_ms() except the current time is returned as a gos_iso8601_t

Parameters
[out] iso8601_struct Buffer to hold the current time as a gos_iso8601_t
[in] add_timezone If true then include the timezone offset in the returned value, if false then return UTC time with 0 timezone offset
Returns
gos_result_t result of api call

gos_time_get_current_utc_as_iso8601_str()

gos_result_t gos_time_get_current_utc_as_iso8601_str ( gos_iso8601_str_t * iso8601_str,
bool add_timezone
)

Returns the current time as a gos_iso8601_str_t .

This has similar functionality to gos_time_get_current_utc_ms() except the current time is returned as a gos_iso8601_str_t

Note
The returned iso8601_str is null-terminated and can be directly printed as a string
Parameters
[out] iso8601_str Buffer to hold the current time as a gos_iso8601_str_t
[in] add_timezone If true then include the timezone offset in the returned value, if false then return UTC time with 0 timezone offset
Returns
gos_result_t result of api call
Examples:
dms/messages/main.c , dms/telemetry/main.c , network/http_server/requests/root_page.c , network/tcp_client/main.c , network/udp_client/main.c , network/websocket_client/main.c , utility/msgpack/read_write_buffer.c , and utility/msgpack/read_write_stream.c .

gos_time_get_current_utc_ms()

gos_result_t gos_time_get_current_utc_ms ( gos_utc_ms_t * utc_time_ms,
bool add_timezone
)

Returns the current UTC time in milliseconds.

This returns the current time as the number of milliseconds since the Epoch. i.e. This returns UNIX time.

Note
If the time.zone variable is set and add_timezone is true then the timezone will be included in the returned value.

The current time may be set with gos_time_set_current_utc_ms() . However, the recommended approach is to use Network Time Protocol (NTP) to retrieve the time from the network, see ntp.enabled . Additionally, see gos_ntp_update() for more details about obtaining the current UTC time via NTP.

This API will return GOS_NEVER_SET if the time was never set.

Note
The value returned by this API is maintained by Real-Time Clock (RTC) hardware. The time will persist through reboots and resets as long as the device is powered.

See time.rtc for more details.

Parameters
[out] utc_time_ms Buffer to hold the current time
[in] add_timezone If true then include the timezone offset in the returned value, if false then return UTC time with 0 timezone offset
Returns
gos_result_t result of api call
Examples:
dms/messages/main.c , file/log_file/main.c , file/log_file_encrypted/main.c , utility/msgpack/read_write_buffer.c , and utility/msgpack/read_write_stream.c .

gos_time_get_current_utc_seconds()

gos_result_t gos_time_get_current_utc_seconds ( gos_utc_seconds_t * utc_time_seconds_ptr,
bool add_timezone
)

Returns the current time in seconds.

This has similar functionality to gos_time_get_current_utc_ms() except the current time is returned as a gos_utc_seconds_t

Parameters
[out] utc_time_seconds_ptr Buffer to hold the current time in seconds
[in] add_timezone If true then include the timezone offset in the returned value, if false then return UTC time with 0 timezone offset
Returns
gos_result_t result of api call

gos_time_get_ms_since_time_set()

gos_result_t gos_time_get_ms_since_time_set ( uint64_t * ms_since_last_set_ptr )

Return the number of milliseconds since the time was last set.

This returns the number of millseconds since the UTC time was last set.

Parameters
[out] ms_since_last_set_ptr Buffer to hold the number of milliseconds since the UTC time was last set
Returns
gos_result_t result of api call

gos_time_get_timezone_offset()

gos_result_t gos_time_get_timezone_offset ( gos_timezone_offset_t * offset_ptr )

Get the current timezone offset.

This returns the current timezone offset in seconds.

Parameters
[out] offset_ptr Point to hold the current timezone offset, see gos_timezone_offset_t
Returns
gos_result_t result of api call

gos_time_get_uptime()

gos_result_t gos_time_get_uptime ( uint64_t * uptime_ms_ptr )

Returns the system's uptime.

The returns the number of milliseconds since the system was started.

Parameters
[out] uptime_ms_ptr Buffer to hold current up time in milliseconds
Returns
gos_result_t result of api call
Examples:
dms/messages/main.c .

gos_time_iso8601_to_str()

gos_result_t gos_time_iso8601_to_str ( const gos_iso8601_t * iso8601_struct,
gos_iso8601_str_t * iso8601_str
)

Convert from gos_iso8601_t to gos_iso8601_str_t .

This is a helper function to convert from a gos_iso8601_t to an gos_iso8601_str_t The returned gos_iso8601_str_t is null-terminated and can be directly printed as a string.

Parameters
[in] iso8601_struct UTC time as a gos_iso8601_t object
[out] iso8601_str converted, printable ISO8601 string
Returns
gos_result_t result of api call

gos_time_iso8601_to_utc_ms()

gos_result_t gos_time_iso8601_to_utc_ms ( const gos_iso8601_t * iso8601_struct,
gos_utc_ms_t * utc_ms_ptr
)

Convert from gos_iso8601_t to UTC time in milliseconds.

This is a helper function to convert from a gos_iso8601_t to UTC time in milliseconds

Note
The returned utc_ms_ptr will contain the timezone offset if the supplied iso8601_struct contains a timezone offset.
Parameters
[in] iso8601_struct UTC time as a gos_iso8601_t object
[out] utc_ms_ptr Current UTC time in milliseconds
Returns
gos_result_t result of api call

gos_time_set_current_utc_ms()

gos_result_t gos_time_set_current_utc_ms ( gos_utc_ms_t time )

Sets the current time in milliseconds.

This updates the current Real-Time Clock value (RTC). The value set will persist through reboots as long as the device is powered.

Note
This API is not needed if Network Time Protocol (NTP) is used. See gos_ntp_update() for more details
On some platforms the time can only be set to the nearest second. On these platforms, the millisecond part of the supplied time is dropped
The specified time should NOT contain a timezone offset
Parameters
[in] time New UTC time, i.e. the current number of milliseconds since the Epoch
Returns
gos_result_t result of api call

gos_time_set_timezone_offset()

gos_result_t gos_time_set_timezone_offset ( gos_timezone_offset_t offset )

Set the current timezone offset.

This updates the current timezone offset. The supplied offset should be the a positive or negative integer in seconds from the UTC base time.

See time.zone for more details on setting the timezone via Gecko OS setting.

Note
You must invoke gos_settings_save() for the value to persist through reboots.
Parameters
[in] offset Timezone offset in seconds, see gos_timezone_offset_t
Returns
gos_result_t result of api call

gos_time_utc_ms_to_iso8601()

gos_result_t gos_time_utc_ms_to_iso8601 ( gos_utc_ms_t utc_ms,
gos_timezone_offset_t timezone_offset,
gos_iso8601_t * iso8601_struct
)

Convert from UTC time in milliseconds to gos_iso8601_t struct.

This is a helper function to convert from UTC time in milliseconds to a gos_iso8601_t struct

Parameters
[in] utc_ms Current UTC time in milliseconds WITHOUT a timezone offset
[in] timezone_offset Timezone offset in seconds, leave a 0 if not used
[out] iso8601_struct Pointer to gos_iso8601_t to hold converted time
Returns
gos_result_t result of api call

gos_time_utc_ms_to_iso8601_str()

gos_result_t gos_time_utc_ms_to_iso8601_str ( gos_utc_ms_t utc_ms,
gos_timezone_offset_t timezone_offset,
gos_iso8601_str_t * iso8601_str
)

Convert from UTC time in milliseconds to gos_iso8601_str_t struct.

This is a helper function to convert from UTC time in milliseconds to a gos_iso8601_str_t struct The gos_iso8601_str_t is null-terminated and can be directly printed as a string.

Parameters
[in] utc_ms Current UTC time in milliseconds WITHOUT a timezone offset
[in] timezone_offset Timezone offset in seconds, leave a 0 if not used
[out] iso8601_str Pointer to gos_iso8601_str_t to hold converted time as a string
Returns
gos_result_t result of api call
Examples:
file/log_file/main.c , and file/log_file_encrypted/main.c .