1 // Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef __ESP_SNTP_H__ 16 #define __ESP_SNTP_H__ 17 18 #include "lwip/err.h" 19 #include "lwip/apps/sntp.h" 20 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /* 27 * The time update takes place in the sntp_sync_time() function. 28 * The user has the ability to redefine this function in order 29 * to re-define its functionality. This function has two time update modes, 30 * which can be set via the sntp_set_sync_mode() function. 31 * Two modes are available: 32 * - the first is an immediate update when receiving time from the sntp server, 33 * - the second is a smooth time update (if the time error is no more than 35 minutes, 34 * and an immediate update if the error is more than 35 minutes). 35 * 36 * To receive notification of time synchronization, 37 * you can use the callback function or get the synchronization status 38 * via the sntp_get_sync_status() function. 39 * 40 * To determine the time synchronization time on the device, you can use: 41 * 1) sntp_set_time_sync_notification_cb() function to set the callback function, 42 * which is convenient to use to receive notification of the update time. 43 * 2) sntp_get_sync_status() function for getting time synchronization status. 44 * After the time synchronization is completed, the status will be 45 * SNTP_SYNC_STATUS_COMPLETED, after, it will be reseted to SNTP_SYNC_STATUS_RESET 46 * to wait for the next sync cycle. 47 */ 48 49 /// SNTP time update mode 50 typedef enum { 51 SNTP_SYNC_MODE_IMMED, /*!< Update system time immediately when receiving a response from the SNTP server. */ 52 SNTP_SYNC_MODE_SMOOTH, /*!< Smooth time updating. Time error is gradually reduced using adjtime function. If the difference between SNTP response time and system time is large (more than 35 minutes) then update immediately. */ 53 } sntp_sync_mode_t; 54 55 /// SNTP sync status 56 typedef enum { 57 SNTP_SYNC_STATUS_RESET, // Reset status. 58 SNTP_SYNC_STATUS_COMPLETED, // Time is synchronized. 59 SNTP_SYNC_STATUS_IN_PROGRESS, // Smooth time sync in progress. 60 } sntp_sync_status_t; 61 62 /** 63 * @brief SNTP callback function for notifying about time sync event 64 * 65 * @param tv Time received from SNTP server. 66 */ 67 typedef void (*sntp_sync_time_cb_t) (struct timeval *tv); 68 69 /** 70 * @brief This function updates the system time. 71 * 72 * This is a weak-linked function. It is possible to replace all SNTP update functionality 73 * by placing a sntp_sync_time() function in the app firmware source. 74 * If the default implementation is used, calling sntp_set_sync_mode() allows 75 * the time synchronization mode to be changed to instant or smooth. 76 * If a callback function is registered via sntp_set_time_sync_notification_cb(), 77 * it will be called following time synchronization. 78 * 79 * @param tv Time received from SNTP server. 80 */ 81 void sntp_sync_time(struct timeval *tv); 82 83 /** 84 * @brief Set the sync mode 85 * 86 * Allowable two mode: SNTP_SYNC_MODE_IMMED and SNTP_SYNC_MODE_SMOOTH. 87 * @param sync_mode Sync mode. 88 */ 89 void sntp_set_sync_mode(sntp_sync_mode_t sync_mode); 90 91 /** 92 * @brief Get set sync mode 93 * 94 * @return SNTP_SYNC_MODE_IMMED: Update time immediately. 95 * SNTP_SYNC_MODE_SMOOTH: Smooth time updating. 96 */ 97 sntp_sync_mode_t sntp_get_sync_mode(void); 98 99 /** 100 * @brief Get status of time sync 101 * 102 * After the update is completed, the status will be returned as SNTP_SYNC_STATUS_COMPLETED. 103 * After that, the status will be reset to SNTP_SYNC_STATUS_RESET. 104 * If the update operation is not completed yet, the status will be SNTP_SYNC_STATUS_RESET. 105 * If a smooth mode was chosen and the synchronization is still continuing (adjtime works), then it will be SNTP_SYNC_STATUS_IN_PROGRESS. 106 * 107 * @return SNTP_SYNC_STATUS_RESET: Reset status. 108 * SNTP_SYNC_STATUS_COMPLETED: Time is synchronized. 109 * SNTP_SYNC_STATUS_IN_PROGRESS: Smooth time sync in progress. 110 */ 111 sntp_sync_status_t sntp_get_sync_status(void); 112 113 /** 114 * @brief Set status of time sync 115 * 116 * @param sync_status status of time sync (see sntp_sync_status_t) 117 */ 118 void sntp_set_sync_status(sntp_sync_status_t sync_status); 119 120 /** 121 * @brief Set a callback function for time synchronization notification 122 * 123 * @param callback a callback function 124 */ 125 void sntp_set_time_sync_notification_cb(sntp_sync_time_cb_t callback); 126 127 /** 128 * @brief Set the sync interval of SNTP operation 129 * 130 * Note: SNTPv4 RFC 4330 enforces a minimum sync interval of 15 seconds. 131 * This sync interval will be used in the next attempt update time throught SNTP. 132 * To apply the new sync interval call the sntp_restart() function, 133 * otherwise, it will be applied after the last interval expired. 134 * 135 * @param interval_ms The sync interval in ms. It cannot be lower than 15 seconds, otherwise 15 seconds will be set. 136 */ 137 void sntp_set_sync_interval(uint32_t interval_ms); 138 139 /** 140 * @brief Get the sync interval of SNTP operation 141 * 142 * @return the sync interval 143 */ 144 uint32_t sntp_get_sync_interval(void); 145 146 /** 147 * @brief Restart SNTP 148 * 149 * @return True - Restart 150 * False - SNTP was not initialized yet 151 */ 152 bool sntp_restart(void); 153 154 #ifdef __cplusplus 155 } 156 #endif 157 158 #endif // __ESP_SNTP_H__ 159
