A facitility to synchronize time for SSL certificates validation or for the whole system. More...

Typedefs
typedef int(*	plgd_set_system_time_fn_t) (oc_clock_time_t time, void *user_data)
	Function used to set time on the whole system invoked whenever the plgd time is updated. More...

typedef void(*	plgd_time_on_fetch_fn_t) (oc_status_t code, oc_clock_time_t time, void *data)
	Callback invoked when plgd_time_fetch request receives a response or timeouts. More...

Enumerations
enum	plgd_time_fetch_flags_t { PLGD_TIME_FETCH_FLAG_TCP_SESSION_OPENED }

enum	plgd_time_status_t { PLGD_TIME_STATUS_SYNCING = 1 , PLGD_TIME_STATUS_IN_SYNC , PLGD_TIME_STATUS_IN_SYNC_FROM_STORAGE }

Functions
oc_clock_time_t	plgd_time (void)
	Calculate current plgd time. More...

void	plgd_time_configure (bool use_in_mbedtls, plgd_set_system_time_fn_t set_system_time, void *set_system_time_data)
	Configure the plgd time feature. More...

bool	plgd_time_dump (void)
	Save persistent data of the plgd time resource to storage. More...

bool	plgd_time_fetch (plgd_time_fetch_config_t fetch, unsigned *flags)
	Fetch time from an endpoint by a GET request. More...

plgd_time_fetch_config_t	plgd_time_fetch_config (const oc_endpoint_t endpoint, const char uri, plgd_time_on_fetch_fn_t on_fetch, void *on_fetch_data, uint16_t timeout, int selected_identity_credid, bool disable_time_verification)
	Convenience wrapper to create plgd_time_fetch_config_t with default \ verification function. More...

plgd_time_fetch_config_t	plgd_time_fetch_config_with_custom_verification (const oc_endpoint_t endpoint, const char uri, plgd_time_on_fetch_fn_t on_fetch, void *on_fetch_data, uint16_t timeout, int selected_identity_credid, oc_pki_verify_certificate_cb_t verify, oc_pki_user_data_t verify_data)
	Convenience wrapper to create plgd_time_fetch_config_t with a custom verification function. More...

bool	plgd_time_is_active (void)
	Plgd time is active (ie it is set to a valid, non-zero value). More...

oc_clock_time_t	plgd_time_last_synced_time (void)
	Get the latest synchronization time. More...

bool	plgd_time_load (void)
	Load persistent data of the plgd time resource from storage. More...

unsigned long	plgd_time_seconds (void)
	Calculate the number of seconds since the Unix Epoch. More...

void	plgd_time_set_status (plgd_time_status_t status)
	Set plgd time status. More...

int	plgd_time_set_time (oc_clock_time_t time)
	Synchronize the plgd time. More...

plgd_time_status_t	plgd_time_status (void)
	Get plgd time status. More...

Detailed Description

A facitility to synchronize time for SSL certificates validation or for the whole system.

Typedef Documentation

◆ plgd_set_system_time_fn_t

typedef int(* plgd_set_system_time_fn_t) (oc_clock_time_t time, void *user_data)

Function used to set time on the whole system invoked whenever the plgd time is updated.

Parameters

time	current time
user_data	custom user data passed from the caller

◆ plgd_time_on_fetch_fn_t

typedef void(* plgd_time_on_fetch_fn_t) (oc_status_t code, oc_clock_time_t time, void *data)

Callback invoked when plgd_time_fetch request receives a response or timeouts.

Parameters

code	response code of the time fetch request
time	time provided by the endpoint (only valid if `code` is OC_STATUS_OK)
data	custom user data

Function Documentation

◆ plgd_time()

oc_clock_time_t plgd_time ( void )

Calculate current plgd time.

The plgd time is calculated by adding synchronization time and elapsed time since the synchronization. The value should represent number of ticks since the Unix Epoch (1970-01-01 00:00:00 +0000 UTC).

Returns: >=0 number of system ticks since the Unix Epoch; -1 on error

See also: plgd_time_set_time

◆ plgd_time_configure()

void plgd_time_configure	(	bool	use_in_mbedtls,
		plgd_set_system_time_fn_t	set_system_time,
		void *	set_system_time_data
	)

Configure the plgd time feature.

Parameters

use_in_mbedtls	propagate the oc_plgd_time function to mbedTLS, if false then the standard time function will be used in mbedTLS (only used in OC_SECURE builds)
set_system_time	function used to set time on the whole system (for example: a wrapper over the settimeofday function on Linux) whenever the plgd time is modified (by plgd_time_set_time or a POST request)
set_system_time_data	user data passed to set_system_time

Note: to report synchronization status use plgd_time_set_status

See also: plgd_time_set_time

◆ plgd_time_dump()

bool plgd_time_dump ( void )

Save persistent data of the plgd time resource to storage.

Returns: true on success; false on failure

◆ plgd_time_fetch()

bool plgd_time_fetch	(	plgd_time_fetch_config_t	fetch,
		unsigned *	flags
	)

Fetch time from an endpoint by a GET request.

For TLS/DTLS/TCP communication the request will use an existing session or a peer. If there is no existing session or peer then it will attempt to create it and after the request is finished it will be closed. (If the session or peer existed before the fetch time request it won't be closed.)

The closing of TCP sessions in iotivity-lite is asynchronous and is executed on the network thread. There are no guarantees about the timing. The session might've be already closed before plgd_time_fetch returns or it might be closed some time later. This might cause an issue if you try to create a TCP connection to the same endpoint right away after calling plgd_time_fetch. If the asynchronous closing of the previous session hasn't finished yet then it will close your session, because in the current implementation sessions are indexed by the endpoint address and not by some unique IDs. You can avoid this problem by checking for PLGD_TIME_FETCH_FLAG_TCP_SESSION_OPENED. The flag is appended to flags when plgd_time_fetch opens a new TCP session. (When a new session is opened by plgd_time_fetch it will always be scheduled to close before the function returns). To check if a session is closed use oc_tcp_connection_state. To wait for a session to close use oc_add_session_event_callback_v1, which will invoke a custom callback when a session is disconnected.

Parameters

	fetch	fetch time configuration
[out]	flags	output flags

Returns: true on success; false on failure

See also: plgd_time_fetch_config_t; plgd_time_fetch_flags_t; oc_add_session_event_callback_v1; oc_tcp_connection_state

◆ plgd_time_fetch_config()

plgd_time_fetch_config_t plgd_time_fetch_config	(	const oc_endpoint_t *	endpoint,
		const char *	uri,
		plgd_time_on_fetch_fn_t	on_fetch,
		void *	on_fetch_data,
		uint16_t	timeout,
		int	selected_identity_credid,
		bool	disable_time_verification
	)

Convenience wrapper to create plgd_time_fetch_config_t with default \ verification function.

◆ plgd_time_fetch_config_with_custom_verification()

plgd_time_fetch_config_t plgd_time_fetch_config_with_custom_verification	(	const oc_endpoint_t *	endpoint,
		const char *	uri,
		plgd_time_on_fetch_fn_t	on_fetch,
		void *	on_fetch_data,
		uint16_t	timeout,
		int	selected_identity_credid,
		oc_pki_verify_certificate_cb_t	verify,
		oc_pki_user_data_t	verify_data
	)

Convenience wrapper to create plgd_time_fetch_config_t with a custom verification function.

◆ plgd_time_is_active()

bool plgd_time_is_active ( void )

Plgd time is active (ie it is set to a valid, non-zero value).

Returns: true plgd time is synchronized; false otherwise

See also: plgd_time_set_time

◆ plgd_time_last_synced_time()

oc_clock_time_t plgd_time_last_synced_time ( void )

Get the latest synchronization time.

◆ plgd_time_load()

bool plgd_time_load ( void )

Load persistent data of the plgd time resource from storage.

Returns: true on success, data was loaded; false otherwise

Note: on successful call the plgd time status is set to PLGD_TIME_STATUS_IN_SYNC_FROM_STORAGE

◆ plgd_time_seconds()

unsigned long plgd_time_seconds ( void )

Calculate the number of seconds since the Unix Epoch.

◆ plgd_time_set_status()

void plgd_time_set_status ( plgd_time_status_t status )

Set plgd time status.

◆ plgd_time_set_time()

int plgd_time_set_time ( oc_clock_time_t time )

Synchronize the plgd time.

Store the synchronization time and the monotonic time of the synchronization. The plgd time is then calculated as synchronization time + time since elapsed since synchronization.

Parameters

time	synchronization time

Returns: 0 on success; -1 on failure

Note: on successful call the plgd time status is set to PLGD_TIME_STATUS_IN_SYNC

◆ plgd_time_status()

plgd_time_status_t plgd_time_status ( void )

Get plgd time status.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ plgd_set_system_time_fn_t

◆ plgd_time_on_fetch_fn_t

Function Documentation

◆ plgd_time()

◆ plgd_time_configure()

◆ plgd_time_dump()

◆ plgd_time_fetch()

◆ plgd_time_fetch_config()

◆ plgd_time_fetch_config_with_custom_verification()

◆ plgd_time_is_active()

◆ plgd_time_last_synced_time()

◆ plgd_time_load()

◆ plgd_time_seconds()

◆ plgd_time_set_status()

◆ plgd_time_set_time()

◆ plgd_time_status()