AWS IoT Device SDK C: Platform
Platform portability layer
Return to main page ↑
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]pBufferA buffer to store the timestring in.
[in]bufferSizeThe size of pBuffer.
[out]pTimestringLengthThe 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]sleepTimeMsSleep 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]pNewTimerSet to a new timer handle on success.
[in]expirationRoutineThe function to run when this timer expires. This function should be called in its own detached thread.
[in]pArgumentThe 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]pTimerThe 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]pTimerThe timer to arm.
[in]relativeTimeoutMsWhen the timer should expire, relative to the time this function is called.
[in]periodMsHow 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.
}
}
}