git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/FreeRTOS-IoT-Libraries/c_sdk/platform/iot_clock.h

   1 /*\r
   2  * IoT Platform V1.1.0\r
   3  * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  */\r
  22 \r
  23 /**\r
  24  * @file iot_clock.h\r
  25  * @brief Time-related functions used by libraries in this SDK.\r
  26  */\r
  27 \r
  28 #ifndef IOT_CLOCK_H_\r
  29 #define IOT_CLOCK_H_\r
  30 \r
  31 /* The config header is always included first. */\r
  32 #include "iot_config.h"\r
  33 \r
  34 /* Standard includes. */\r
  35 #include <stdbool.h>\r
  36 #include <stddef.h>\r
  37 #include <stdint.h>\r
  38 \r
  39 /* Platform layer types include. */\r
  40 #include "types/iot_platform_types.h"\r
  41 \r
  42 /**\r
  43  * @functionspage{platform_clock,platform clock component,Clock}\r
  44  * - @functionname{platform_clock_function_gettimestring}\r
  45  * - @functionname{platform_clock_function_gettimems}\r
  46  * - @functionname{platform_clock_function_sleepms}\r
  47  * - @functionname{platform_clock_function_timercreate}\r
  48  * - @functionname{platform_clock_function_timerdestroy}\r
  49  * - @functionname{platform_clock_function_timerarm}\r
  50  */\r
  51 \r
  52 /**\r
  53  * @functionpage{IotClock_GetTimestring,platform_clock,gettimestring}\r
  54  * @functionpage{IotClock_GetTimeMs,platform_clock,gettimems}\r
  55  * @functionpage{IotClock_SleepMs,platform_clock,sleepms}\r
  56  * @functionpage{IotClock_TimerCreate,platform_clock,timercreate}\r
  57  * @functionpage{IotClock_TimerDestroy,platform_clock,timerdestroy}\r
  58  * @functionpage{IotClock_TimerArm,platform_clock,timerarm}\r
  59  */\r
  60 \r
  61 /**\r
  62  * @brief Generates a human-readable timestring, such as "01 Jan 2018 12:00".\r
  63  *\r
  64  * This function uses the system clock to generate a human-readable timestring.\r
  65  * This timestring is printed by the [logging functions](@ref logging_functions).\r
  66  *\r
  67  * @param[out] pBuffer A buffer to store the timestring in.\r
  68  * @param[in] bufferSize The size of `pBuffer`.\r
  69  * @param[out] pTimestringLength The actual length of the timestring stored in\r
  70  * `pBuffer`.\r
  71  *\r
  72  * @return `true` if a timestring was successfully generated; `false` otherwise.\r
  73  *\r
  74  * @warning The implementation of this function must not call any [logging functions]\r
  75  * (@ref logging_functions).\r
  76  *\r
  77  * <b>Example</b>\r
  78  * @code{c}\r
  79  * char timestring[ 32 ];\r
  80  * size_t timestringLength = 0;\r
  81  *\r
  82  * if( IotClock_GetTimestring( timestring, 32, &timestringLength ) == true )\r
  83  * {\r
  84  *     printf( "Timestring: %.*s", timestringLength, timestring );\r
  85  * }\r
  86  * @endcode\r
  87  */\r
  88 /* @[declare_platform_clock_gettimestring] */\r
  89 bool IotClock_GetTimestring( char * pBuffer,\r
  90                              size_t bufferSize,\r
  91                              size_t * pTimestringLength );\r
  92 /* @[declare_platform_clock_gettimestring] */\r
  93 \r
  94 /**\r
  95  * @brief Returns a nonzero, monotonically-increasing system time in milliseconds.\r
  96  *\r
  97  * This function reads a millisecond-resolution system clock. The clock should\r
  98  * always be monotonically-increasing; therefore, real-time clocks that may be\r
  99  * set by another process are not suitable for this function's implementation.\r
 100  *\r
 101  * @return The value of the system clock. This function is not expected to fail.\r
 102  *\r
 103  * <b>Example</b>\r
 104  * @code{c}\r
 105  * // Get current time.\r
 106  * uint64_t currentTime = IotClock_GetTimeMs();\r
 107  * @endcode\r
 108  */\r
 109 /* @[declare_platform_clock_gettimems] */\r
 110 uint64_t IotClock_GetTimeMs( void );\r
 111 /* @[declare_platform_clock_gettimems] */\r
 112 \r
 113 /**\r
 114  * @brief Delay for the given number of milliseconds.\r
 115  *\r
 116  * This function suspends its calling thread for at least `sleepTimeMs` milliseconds.\r
 117  *\r
 118  * @param[in] sleepTimeMs Sleep time (in milliseconds).\r
 119  */\r
 120 /* @[declare_platform_clock_sleepms] */\r
 121 void IotClock_SleepMs( uint32_t sleepTimeMs );\r
 122 /* @[declare_platform_clock_sleepms] */\r
 123 \r
 124 /**\r
 125  * @brief Create a new timer.\r
 126  *\r
 127  * This function creates a new, unarmed timer. It must be called on an uninitialized\r
 128  * #IotTimer_t. This function must not be called on an already-initialized #IotTimer_t.\r
 129  *\r
 130  * @param[out] pNewTimer Set to a new timer handle on success.\r
 131  * @param[in] expirationRoutine The function to run when this timer expires. This\r
 132  * function should be called in its own <i>detached</i> thread.\r
 133  * @param[in] pArgument The argument to pass to `expirationRoutine`.\r
 134  *\r
 135  * @return `true` if the timer is successfully created; `false` otherwise.\r
 136  *\r
 137  * @see @ref platform_clock_function_timerdestroy, @ref platform_clock_function_timerarm\r
 138  */\r
 139 /* @[declare_platform_clock_timercreate] */\r
 140 bool IotClock_TimerCreate( IotTimer_t * pNewTimer,\r
 141                            IotThreadRoutine_t expirationRoutine,\r
 142                            void * pArgument );\r
 143 /* @[declare_platform_clock_timercreate] */\r
 144 \r
 145 /**\r
 146  * @brief Free resources used by a timer.\r
 147  *\r
 148  * This function frees resources used by a timer. It must be called on an initialized\r
 149  * #IotTimer_t. No other timer functions should be called on `pTimer` after calling\r
 150  * this function (unless the timer is re-created).\r
 151  *\r
 152  * This function will stop the `pTimer` if it is armed.\r
 153  *\r
 154  * @param[in] pTimer The timer to destroy.\r
 155  *\r
 156  * @see @ref platform_clock_function_timercreate, @ref platform_clock_function_timerarm\r
 157  */\r
 158 /* @[declare_platform_clock_timerdestroy] */\r
 159 void IotClock_TimerDestroy( IotTimer_t * pTimer );\r
 160 /* @[declare_platform_clock_timerdestroy] */\r
 161 \r
 162 /**\r
 163  * @brief Arm a timer to expire at the given relative timeout.\r
 164  *\r
 165  * This function arms a timer to run its expiration routine at the given time.\r
 166  *\r
 167  * If `periodMs` is nonzero, the timer should expire periodically at intervals\r
 168  * such as:\r
 169  * - `relativeTimeoutMs`\r
 170  * - `relativeTimeoutMs + periodMs`\r
 171  * - `relativeTimeoutMs + 2 * periodMs`\r
 172  * - Etc. (subject to some jitter).\r
 173  *\r
 174  * Setting `periodMs` to `0` arms a one-shot, non-periodic timer.\r
 175  *\r
 176  * @param[in] pTimer The timer to arm.\r
 177  * @param[in] relativeTimeoutMs When the timer should expire, relative to the time\r
 178  * this function is called.\r
 179  * @param[in] periodMs How often the timer should expire again after `relativeTimerMs`.\r
 180  *\r
 181  * @return `true` if the timer was successfully armed; `false` otherwise.\r
 182  *\r
 183  * @see @ref platform_clock_function_timercreate, @ref platform_clock_function_timerdestroy\r
 184  *\r
 185  * <b>Example</b>\r
 186  * @code{c}\r
 187  *\r
 188  * void timerExpirationRoutine( void * pArgument );\r
 189  *\r
 190  * void timerExample( void )\r
 191  * {\r
 192  *     IotTimer_t timer;\r
 193  *\r
 194  *     if( IotClock_TimerCreate( &timer, timerExpirationRoutine, NULL ) == true )\r
 195  *     {\r
 196  *         // Set the timer to periodically expire every 10 seconds.\r
 197  *         if( IotClock_TimerArm( &timer, 10000, 10000 ) == true )\r
 198  *         {\r
 199  *             // Wait for timer to expire.\r
 200  *         }\r
 201  *\r
 202  *         IotClock_TimerDestroy( &timer );\r
 203  *     }\r
 204  * }\r
 205  * @endcode\r
 206  */\r
 207 /* @[declare_platform_clock_timerarm] */\r
 208 bool IotClock_TimerArm( IotTimer_t * pTimer,\r
 209                         uint32_t relativeTimeoutMs,\r
 210                         uint32_t periodMs );\r
 211 /* @[declare_platform_clock_timerarm] */\r
 212 \r
 213 #endif /* ifndef IOT_CLOCK_H_ */\r