Time

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_structBuffer to hold the current time as a gos_iso8601_t
[in]add_timezoneIf 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_strBuffer to hold the current time as a gos_iso8601_str_t
[in]add_timezoneIf 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_msBuffer to hold the current time
[in]add_timezoneIf 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_ptrBuffer to hold the current time in seconds
[in]add_timezoneIf 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_ptrBuffer 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_ptrPoint 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_ptrBuffer 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_structUTC time as a gos_iso8601_t object
[out]iso8601_strconverted, 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_structUTC time as a gos_iso8601_t object
[out]utc_ms_ptrCurrent 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]timeNew 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]offsetTimezone 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_msCurrent UTC time in milliseconds WITHOUT a timezone offset
[in]timezone_offsetTimezone offset in seconds, leave a 0 if not used
[out]iso8601_structPointer 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_msCurrent UTC time in milliseconds WITHOUT a timezone offset
[in]timezone_offsetTimezone offset in seconds, leave a 0 if not used
[out]iso8601_strPointer 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.