iot_clock.h File Reference

Time-related functions used by libraries in this SDK. More...

#include "iot_config.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "types/iot_platform_types.h"

Go to the source code of this file.

Functions
bool	IotClock_GetTimestring (char *pBuffer, size_t bufferSize, size_t *pTimestringLength)
	Generates a human-readable timestring, such as "01 Jan 2018 12:00". More...
uint64_t	IotClock_GetTimeMs (void)
	Returns a nonzero, monotonically-increasing system time in milliseconds. More...
void	IotClock_SleepMs (uint32_t sleepTimeMs)
	Delay for the given number of milliseconds. More...
bool	IotClock_TimerCreate (IotTimer_t *pNewTimer, IotThreadRoutine_t expirationRoutine, void *pArgument)
	Create a new timer. More...
void	IotClock_TimerDestroy (IotTimer_t *pTimer)
	Free resources used by a timer. More...
bool	IotClock_TimerArm (IotTimer_t *pTimer, uint32_t relativeTimeoutMs, uint32_t periodMs)
	Arm a timer to expire at the given relative timeout. More...

Detailed Description

Time-related functions used by libraries in this SDK.

Function Documentation

IotClock_GetTimestring()

bool IotClock_GetTimestring	(	char *	pBuffer,
		size_t	bufferSize,
		size_t *	pTimestringLength
	)

Generates a human-readable timestring, such as "01 Jan 2018 12:00".

This function uses the system clock to generate a human-readable timestring. This timestring is printed by the logging functions.

Parameters

[out]	pBuffer	A buffer to store the timestring in.
[in]	bufferSize	The size of pBuffer.
[out]	pTimestringLength	The actual length of the timestring stored in pBuffer.

Returns

true if a timestring was successfully generated; false otherwise.

Warning

The implementation of this function must not call any logging functions.

Example

char timestring[ 32 ];
size_t timestringLength = 0;

if( IotClock_GetTimestring( timestring, 32, &timestringLength ) == true )
{
    printf( "Timestring: %.*s", timestringLength, timestring );
}

IotClock_GetTimeMs()

uint64_t IotClock_GetTimeMs

(

void

)

Returns a nonzero, monotonically-increasing system time in milliseconds.

This function reads a millisecond-resolution system clock. The clock should always be monotonically-increasing; therefore, real-time clocks that may be set by another process are not suitable for this function's implementation.

Returns

The value of the system clock. This function is not expected to fail.

Example

// Get current time.
uint64_t currentTime = IotClock_GetTimeMs();

IotClock_SleepMs()

void IotClock_SleepMs

(

uint32_t

sleepTimeMs

)

Delay for the given number of milliseconds.

This function suspends its calling thread for at least sleepTimeMs milliseconds.

Parameters

[in]

sleepTimeMs

Sleep time (in milliseconds).

IotClock_TimerCreate()

bool IotClock_TimerCreate	(	IotTimer_t *	pNewTimer,
		IotThreadRoutine_t	expirationRoutine,
		void *	pArgument
	)

Create a new timer.

This function creates a new, unarmed timer. It must be called on an uninitialized IotTimer_t. This function must not be called on an already-initialized IotTimer_t.

Parameters

[out]	pNewTimer	Set to a new timer handle on success.
[in]	expirationRoutine	The function to run when this timer expires. This function should be called in its own detached thread.
[in]	pArgument	The argument to pass to expirationRoutine.

Returns

true if the timer is successfully created; false otherwise.

See also

IotClock_TimerDestroy, IotClock_TimerArm

IotClock_TimerDestroy()

void IotClock_TimerDestroy

(

IotTimer_t *

pTimer

)

Free resources used by a timer.

This function frees resources used by a timer. It must be called on an initialized IotTimer_t. No other timer functions should be called on pTimer after calling this function (unless the timer is re-created).

This function will stop the pTimer if it is armed.

Parameters

[in]

pTimer

The timer to destroy.

See also

IotClock_TimerCreate, IotClock_TimerArm

IotClock_TimerArm()

bool IotClock_TimerArm	(	IotTimer_t *	pTimer,
		uint32_t	relativeTimeoutMs,
		uint32_t	periodMs
	)

Arm a timer to expire at the given relative timeout.

This function arms a timer to run its expiration routine at the given time.

If periodMs is nonzero, the timer should expire periodically at intervals such as:

• relativeTimeoutMs
• relativeTimeoutMs + periodMs
• relativeTimeoutMs + 2 * periodMs
• Etc. (subject to some jitter).

Setting periodMs to 0 arms a one-shot, non-periodic timer.

Parameters

[in]	pTimer	The timer to arm.
[in]	relativeTimeoutMs	When the timer should expire, relative to the time this function is called.
[in]	periodMs	How often the timer should expire again after relativeTimerMs.

Returns

true if the timer was successfully armed; false otherwise.

See also

IotClock_TimerCreate, IotClock_TimerDestroy

Example

void timerExpirationRoutine( void * pArgument );

void timerExample( void )
{
    IotTimer_t timer;

    if( IotClock_TimerCreate( &timer, timerExpirationRoutine, NULL ) == true )
    {
        // Set the timer to periodically expire every 10 seconds.
        if( IotClock_TimerArm( &timer, 10000, 10000 ) == true )
        {
            // Wait for timer to expire.
        }

        IotClock_TimerDestroy( &timer );
    }
}