A time interface class. This class replicates the normal time functions, but goes a couple of steps further. mbed library 82 and prior has a defective gmtime function. Also, this class enables access to setting the time, and adjusting the accuracy of the RTC.
Dependents: CI-data-logger-server WattEye X10Svr SSDP_Server
TimeInterface.h@30:2740e128a809, 2019-04-03 (annotated)
- Committer:
- WiredHome
- Date:
- Wed Apr 03 22:26:47 2019 +0000
- Revision:
- 30:2740e128a809
- Parent:
- 26:9ee3fac64626
Modify asctime to include the dst flag in its processing, in addition to the tzo.
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
WiredHome | 0:61112ca9193b | 1 | |
WiredHome | 0:61112ca9193b | 2 | #ifndef TIMEINTERFACE_H |
WiredHome | 0:61112ca9193b | 3 | #define TIMEINTERFACE_H |
WiredHome | 0:61112ca9193b | 4 | #include "mbed.h" |
WiredHome | 4:9cae2da8215e | 5 | #include <ctime> |
WiredHome | 0:61112ca9193b | 6 | |
WiredHome | 21:f3818e2e0370 | 7 | #include "NTPClient.h" |
WiredHome | 2:65e0a25c7551 | 8 | |
WiredHome | 0:61112ca9193b | 9 | // Special Registers and their usage: |
WiredHome | 0:61112ca9193b | 10 | // GPREG0: 32 bits |
WiredHome | 0:61112ca9193b | 11 | // low word: time zone offset (-720 to +720) |
WiredHome | 0:61112ca9193b | 12 | // high word: 2's complement of low word for integrity checking |
WiredHome | 0:61112ca9193b | 13 | // GPREG1: 32 bits |
WiredHome | 0:61112ca9193b | 14 | // time_t value when the clock was last set |
WiredHome | 0:61112ca9193b | 15 | |
WiredHome | 0:61112ca9193b | 16 | |
WiredHome | 0:61112ca9193b | 17 | extern "C" { |
WiredHome | 21:f3818e2e0370 | 18 | #include "time.h" // uses some std::time-functions |
WiredHome | 0:61112ca9193b | 19 | } |
WiredHome | 0:61112ca9193b | 20 | |
WiredHome | 21:f3818e2e0370 | 21 | /// The tm_ex structure is patterned after the traditional tm struct, however |
WiredHome | 20:5ca2c94d46b8 | 22 | /// it adds an element - the time zone offset in minutes. From this, it is then |
WiredHome | 20:5ca2c94d46b8 | 23 | /// readily able to create a "local time" instead of simply a UTC time. |
WiredHome | 20:5ca2c94d46b8 | 24 | /// |
WiredHome | 0:61112ca9193b | 25 | struct tm_ex |
WiredHome | 0:61112ca9193b | 26 | { |
WiredHome | 0:61112ca9193b | 27 | int tm_sec; ///<! seconds, 0 to 59. |
WiredHome | 0:61112ca9193b | 28 | int tm_min; ///<! minutes, 0 to 59. |
WiredHome | 0:61112ca9193b | 29 | int tm_hour; ///<! hours, 0 to 23. |
WiredHome | 0:61112ca9193b | 30 | int tm_mday; ///<! monthday 1 to 31. |
WiredHome | 0:61112ca9193b | 31 | int tm_mon; ///<! month 0 to 11. |
WiredHome | 0:61112ca9193b | 32 | int tm_year; ///<! years since 1900. |
WiredHome | 0:61112ca9193b | 33 | int tm_wday; ///<! days since sunday 0 to 6. |
WiredHome | 0:61112ca9193b | 34 | int tm_yday; ///<! days since 1 Jan 0 to 365. |
WiredHome | 0:61112ca9193b | 35 | int tm_isdst; ///<! is daylight savings time. |
WiredHome | 20:5ca2c94d46b8 | 36 | int tm_tzo_min; ///<! localtime zone offset in minutes (_ex element) |
WiredHome | 0:61112ca9193b | 37 | }; |
WiredHome | 0:61112ca9193b | 38 | |
WiredHome | 11:1d880a50da8a | 39 | /// TimeInterface class is much like the normal c-style time.h interface, but |
WiredHome | 11:1d880a50da8a | 40 | /// is extended with time-zone support, and clock-adjustment support (which |
WiredHome | 11:1d880a50da8a | 41 | /// permits tuning the clock) for more accuracy. |
WiredHome | 11:1d880a50da8a | 42 | /// |
WiredHome | 11:1d880a50da8a | 43 | /// Additionally, strptime was integrated, which can extract the time from |
WiredHome | 11:1d880a50da8a | 44 | /// a text string. A formatter is used, so it cannot parse an arbitrary string. |
WiredHome | 0:61112ca9193b | 45 | /// |
WiredHome | 0:61112ca9193b | 46 | /// Within this class are the normal time.h methods, simply |
WiredHome | 0:61112ca9193b | 47 | /// exposed here for one consistent interface. |
WiredHome | 0:61112ca9193b | 48 | /// |
WiredHome | 0:61112ca9193b | 49 | /// @note This class uses the special battery backed registers |
WiredHome | 0:61112ca9193b | 50 | /// GPREG0 and GPREG1 for TimeInterface data. |
WiredHome | 0:61112ca9193b | 51 | /// |
WiredHome | 0:61112ca9193b | 52 | /// @note In mbed library ver 84, the gmtime method is defective, |
WiredHome | 0:61112ca9193b | 53 | /// and calls to this function return junk data. The |
WiredHome | 0:61112ca9193b | 54 | /// gmtime method in this library actually uses localtime, |
WiredHome | 0:61112ca9193b | 55 | /// but manages the time-zone offset as it does so. |
WiredHome | 0:61112ca9193b | 56 | /// |
WiredHome | 11:1d880a50da8a | 57 | /// @code |
WiredHome | 21:f3818e2e0370 | 58 | /// // TimeInterface Architecture and APIs |
WiredHome | 11:1d880a50da8a | 59 | /// // |
WiredHome | 11:1d880a50da8a | 60 | /// // +--------+ |
WiredHome | 11:1d880a50da8a | 61 | /// // | clock |----> clock_t clock() |
WiredHome | 11:1d880a50da8a | 62 | /// // +--------+ |
WiredHome | 11:1d880a50da8a | 63 | /// // |
WiredHome | 11:1d880a50da8a | 64 | /// // +--------+ |
WiredHome | 24:45a9e7081499 | 65 | /// // | |<------------ setTime(char * server, uint16_t port, uint32_t timeout) |
WiredHome | 24:45a9e7081499 | 66 | /// // | NTP |<-----------> Ethernet |
WiredHome | 24:45a9e7081499 | 67 | /// // | |----+ |
WiredHome | 24:45a9e7081499 | 68 | /// // +--------+ | |
WiredHome | 24:45a9e7081499 | 69 | /// // | |
WiredHome | 24:45a9e7081499 | 70 | /// // +--------+ | |
WiredHome | 24:45a9e7081499 | 71 | /// // | RTC |<---+-------- set_time(time_t t, int16_t tzo) |
WiredHome | 24:45a9e7081499 | 72 | /// // | |<------------ adjust_sec(int32_t) |
WiredHome | 24:45a9e7081499 | 73 | /// // | |<------------ set_cal(int32_t) |
WiredHome | 24:45a9e7081499 | 74 | /// // | |------------> int32_t get_cal() |
WiredHome | 24:45a9e7081499 | 75 | /// // | |------------> time_t time(time_t *) |
WiredHome | 17:45dae5a72679 | 76 | /// // | |------+ |
WiredHome | 17:45dae5a72679 | 77 | /// // +--------+ | |
WiredHome | 24:45a9e7081499 | 78 | /// // | |
WiredHome | 24:45a9e7081499 | 79 | /// // +--------+ | |
WiredHome | 24:45a9e7081499 | 80 | /// // | |<---- | <---- set_dst(bool dst) |
WiredHome | 24:45a9e7081499 | 81 | /// // | |<---- | <---- set_dst(char * start_dst, char * end_dst) |
WiredHome | 24:45a9e7081499 | 82 | /// // | |----- | ----> bool get_dst() |
WiredHome | 24:45a9e7081499 | 83 | /// // |dst_pair|---+ | +----------+ |
WiredHome | 24:45a9e7081499 | 84 | /// // +--------+ | | | | |
WiredHome | 24:45a9e7081499 | 85 | /// // | +->| | |
WiredHome | 24:45a9e7081499 | 86 | /// // +--------+ +---->|time_local|--------> time_t timelocal(time_t *) |
WiredHome | 24:45a9e7081499 | 87 | /// // | tzo |<--------| | |
WiredHome | 24:45a9e7081499 | 88 | /// // | | +----------+ |
WiredHome | 24:45a9e7081499 | 89 | /// // | |<------------ set_tzo_min(int16_t) |
WiredHome | 24:45a9e7081499 | 90 | /// // | |------------> int16_t get_tzo_min() |
WiredHome | 11:1d880a50da8a | 91 | /// // +--------+ |
WiredHome | 11:1d880a50da8a | 92 | /// // |
WiredHome | 11:1d880a50da8a | 93 | /// // +--------+ +--------------------------+ |
WiredHome | 11:1d880a50da8a | 94 | /// // | time_t | ---> char * ctime(time_t *) ----> | buffer | |
WiredHome | 11:1d880a50da8a | 95 | /// // | value | | Www Mmm dd hh:mm:ss yyyy | |
WiredHome | 11:1d880a50da8a | 96 | /// // +--------+ +- char * asctime(tm_ex *) -> +--------------------------+ |
WiredHome | 11:1d880a50da8a | 97 | /// // ^ | | |
WiredHome | 11:1d880a50da8a | 98 | /// // | | | +-----------------+ |
WiredHome | 20:5ca2c94d46b8 | 99 | /// // | | +-------------------------------- | tm_ex | |
WiredHome | 11:1d880a50da8a | 100 | /// // | | | .tm_sec | |
WiredHome | 11:1d880a50da8a | 101 | /// // | +- tm_ex * gmtime(const time_t *) -----> | .tm_min | |
WiredHome | 11:1d880a50da8a | 102 | /// // | | | .tm_hour | |
WiredHome | 11:1d880a50da8a | 103 | /// // | +- tm_ex * localtime(const time_t *) --> | .tm_mday | |
WiredHome | 11:1d880a50da8a | 104 | /// // | | .tm_mon | |
WiredHome | 11:1d880a50da8a | 105 | /// // +---- time_t mktime(struct tm_ex *) ------- | .tm_year | |
WiredHome | 11:1d880a50da8a | 106 | /// // | .tm_wday | |
WiredHome | 11:1d880a50da8a | 107 | /// // | .tm_yday | |
WiredHome | 20:5ca2c94d46b8 | 108 | /// // +---------------------------------------------> | .tm_isdst | |
WiredHome | 20:5ca2c94d46b8 | 109 | /// // | +-------------------------------------------- | .tm_tzo_min | |
WiredHome | 20:5ca2c94d46b8 | 110 | /// // | | +-----------------+ |
WiredHome | 20:5ca2c94d46b8 | 111 | /// // | | +--------------------------+ |
WiredHome | 20:5ca2c94d46b8 | 112 | /// // | +- strftime(char * ptr, ..., tm_ex *) --> | buffer | |
WiredHome | 20:5ca2c94d46b8 | 113 | /// // +----strptime(char * buf, ..., tm_ex *) --- | Www Mmm dd hh:mm:ss yyyy | |
WiredHome | 11:1d880a50da8a | 114 | /// // +--------------------------+ |
WiredHome | 21:f3818e2e0370 | 115 | /// // double difftime(time_t end, time_t) |
WiredHome | 21:f3818e2e0370 | 116 | /// // |
WiredHome | 11:1d880a50da8a | 117 | /// @endcode |
WiredHome | 11:1d880a50da8a | 118 | /// |
WiredHome | 0:61112ca9193b | 119 | class TimeInterface |
WiredHome | 0:61112ca9193b | 120 | { |
WiredHome | 0:61112ca9193b | 121 | public: |
WiredHome | 11:1d880a50da8a | 122 | /// Constructor for the TimeInterface class, which does minimal initialization. |
WiredHome | 11:1d880a50da8a | 123 | /// |
WiredHome | 20:5ca2c94d46b8 | 124 | /// @param[in] net is optional and provides the EthernetInterface which is |
WiredHome | 20:5ca2c94d46b8 | 125 | /// used if you want to sync to an NTP server |
WiredHome | 20:5ca2c94d46b8 | 126 | /// |
WiredHome | 21:f3818e2e0370 | 127 | /// @code |
WiredHome | 21:f3818e2e0370 | 128 | /// EthernetInterface net; |
WiredHome | 21:f3818e2e0370 | 129 | /// TimeInterface ntp(&net); |
WiredHome | 21:f3818e2e0370 | 130 | /// ... |
WiredHome | 21:f3818e2e0370 | 131 | /// ntp.set_tzo_min(-6 * 60); |
WiredHome | 21:f3818e2e0370 | 132 | /// if (NTP_OK == ntp.setTime("time.nist.gov", 123, 10)) { |
WiredHome | 21:f3818e2e0370 | 133 | /// time_t tNow = ntp.timelocal(); |
WiredHome | 21:f3818e2e0370 | 134 | /// printf("time is %s\r\n", ntp.ctime(&tNow)); |
WiredHome | 21:f3818e2e0370 | 135 | /// } |
WiredHome | 21:f3818e2e0370 | 136 | /// ... |
WiredHome | 21:f3818e2e0370 | 137 | /// @endcode |
WiredHome | 21:f3818e2e0370 | 138 | /// |
WiredHome | 20:5ca2c94d46b8 | 139 | TimeInterface(EthernetInterface *m_net = NULL); |
WiredHome | 0:61112ca9193b | 140 | |
WiredHome | 11:1d880a50da8a | 141 | /// Destructor, normally not used, because it is typically kept for the life |
WiredHome | 11:1d880a50da8a | 142 | /// of the program. |
WiredHome | 11:1d880a50da8a | 143 | /// |
WiredHome | 0:61112ca9193b | 144 | ~TimeInterface(); |
WiredHome | 0:61112ca9193b | 145 | |
WiredHome | 0:61112ca9193b | 146 | /// Gets the system elapsed time in CLOCKS_PER_SEC tics. |
WiredHome | 0:61112ca9193b | 147 | /// |
WiredHome | 0:61112ca9193b | 148 | /// Divide the returned value by CLOCKS_PER_SEC to get time in seconds. |
WiredHome | 0:61112ca9193b | 149 | /// |
WiredHome | 0:61112ca9193b | 150 | /// @code |
WiredHome | 0:61112ca9193b | 151 | /// clock_t tstart, tend; |
WiredHome | 21:f3818e2e0370 | 152 | /// ... |
WiredHome | 21:f3818e2e0370 | 153 | /// tstart = clock(); |
WiredHome | 21:f3818e2e0370 | 154 | /// // do something long |
WiredHome | 21:f3818e2e0370 | 155 | /// tend = clock(); |
WiredHome | 21:f3818e2e0370 | 156 | /// printf("Elapsed time is %5.3f\r\n", (float)(tend - tstart)/CLOCKS_PER_SEC); |
WiredHome | 21:f3818e2e0370 | 157 | /// ... |
WiredHome | 0:61112ca9193b | 158 | /// @endcode |
WiredHome | 0:61112ca9193b | 159 | /// |
WiredHome | 0:61112ca9193b | 160 | /// @returns elapsed tics. |
WiredHome | 0:61112ca9193b | 161 | /// |
WiredHome | 0:61112ca9193b | 162 | clock_t clock(void); |
WiredHome | 0:61112ca9193b | 163 | |
WiredHome | 8:18489e877b0b | 164 | /// Gets the current time as a UTC time value, optionally writing it |
WiredHome | 0:61112ca9193b | 165 | /// to a provided buffer. |
WiredHome | 0:61112ca9193b | 166 | /// |
WiredHome | 8:18489e877b0b | 167 | /// This reads the real time clock and returns the current UTC time. |
WiredHome | 0:61112ca9193b | 168 | /// |
WiredHome | 0:61112ca9193b | 169 | /// @code |
WiredHome | 0:61112ca9193b | 170 | /// time_t t_ref1, t_ref2, t_ref3; |
WiredHome | 21:f3818e2e0370 | 171 | /// t_ref1 = time(NULL); |
WiredHome | 21:f3818e2e0370 | 172 | /// t_ref2 = t.time(); |
WiredHome | 21:f3818e2e0370 | 173 | /// (void)t.time(&t_ref3); |
WiredHome | 0:61112ca9193b | 174 | /// @endcode |
WiredHome | 0:61112ca9193b | 175 | /// |
WiredHome | 21:f3818e2e0370 | 176 | /// @param[out] timer is an optional pointer to a time_t value that will |
WiredHome | 21:f3818e2e0370 | 177 | /// be written with the current time. This pointer is ignored |
WiredHome | 21:f3818e2e0370 | 178 | /// when NULL. |
WiredHome | 8:18489e877b0b | 179 | /// @returns the UTC time value. |
WiredHome | 0:61112ca9193b | 180 | /// |
WiredHome | 0:61112ca9193b | 181 | time_t time(time_t * timer = NULL); |
WiredHome | 0:61112ca9193b | 182 | |
WiredHome | 8:18489e877b0b | 183 | /// Gets the current time as a LOCAL time value, optionally writing it |
WiredHome | 1:2ee90f546f54 | 184 | /// to a provided buffer. |
WiredHome | 1:2ee90f546f54 | 185 | /// |
WiredHome | 1:2ee90f546f54 | 186 | /// This reads the real time clock and returns the current time, adjusted |
WiredHome | 21:f3818e2e0370 | 187 | /// for the local time zone and daylight savings time. |
WiredHome | 1:2ee90f546f54 | 188 | /// |
WiredHome | 1:2ee90f546f54 | 189 | /// @code |
WiredHome | 1:2ee90f546f54 | 190 | /// time_t t_ref2, t_ref3; |
WiredHome | 21:f3818e2e0370 | 191 | /// t_ref2 = t.time(); |
WiredHome | 21:f3818e2e0370 | 192 | /// t.timelocal(&t_ref3); |
WiredHome | 1:2ee90f546f54 | 193 | /// @endcode |
WiredHome | 1:2ee90f546f54 | 194 | /// |
WiredHome | 21:f3818e2e0370 | 195 | /// @param[out] timer is an optional pointer to a time_t value that will |
WiredHome | 21:f3818e2e0370 | 196 | /// be written. This pointer is ignored when NULL. |
WiredHome | 21:f3818e2e0370 | 197 | /// @returns the LOCAL time value (UTC adjusted for the LOCAL time zone and dst). |
WiredHome | 1:2ee90f546f54 | 198 | /// |
WiredHome | 1:2ee90f546f54 | 199 | time_t timelocal(time_t * timer = NULL); |
WiredHome | 1:2ee90f546f54 | 200 | |
WiredHome | 21:f3818e2e0370 | 201 | /// Convert a time value structure into an ASCII printable time "Www Mmm dd hh:mm:ss yyyy" |
WiredHome | 21:f3818e2e0370 | 202 | /// |
WiredHome | 21:f3818e2e0370 | 203 | /// @note Watch out for race conditions as this returns a pointer to a |
WiredHome | 21:f3818e2e0370 | 204 | /// shared buffer. |
WiredHome | 21:f3818e2e0370 | 205 | /// @note Unlike the standard ctime function, this version DOES NOT append |
WiredHome | 21:f3818e2e0370 | 206 | /// a newline character to the buffer. |
WiredHome | 21:f3818e2e0370 | 207 | /// |
WiredHome | 21:f3818e2e0370 | 208 | /// @code |
WiredHome | 21:f3818e2e0370 | 209 | /// time_t tNow = timelocal(); |
WiredHome | 21:f3818e2e0370 | 210 | /// printf("time is %s\r\n", ctime(tNow)); |
WiredHome | 21:f3818e2e0370 | 211 | /// @endcode |
WiredHome | 21:f3818e2e0370 | 212 | /// |
WiredHome | 21:f3818e2e0370 | 213 | /// @param[in] timer is a pointer to a time_t value containing the time to convert. |
WiredHome | 21:f3818e2e0370 | 214 | /// @returns a pointer to a buffer containing the string. |
WiredHome | 21:f3818e2e0370 | 215 | /// |
WiredHome | 21:f3818e2e0370 | 216 | char * ctime(const time_t * timer); |
WiredHome | 21:f3818e2e0370 | 217 | |
WiredHome | 21:f3818e2e0370 | 218 | /// Convert a tm_ex structure into an ASCII printable "time Www Mmm dd hh:mm:ss yyyy" |
WiredHome | 21:f3818e2e0370 | 219 | /// |
WiredHome | 21:f3818e2e0370 | 220 | /// @note Unlike the standard asctime, this takes a pointer to a tm_ex, which |
WiredHome | 30:2740e128a809 | 221 | /// has daylight savings time flag and a time zone offset element. |
WiredHome | 0:61112ca9193b | 222 | /// |
WiredHome | 0:61112ca9193b | 223 | /// @note Watch out for race conditions as this returns a pointer to a |
WiredHome | 0:61112ca9193b | 224 | /// shared buffer. |
WiredHome | 0:61112ca9193b | 225 | /// |
WiredHome | 0:61112ca9193b | 226 | /// @note Unlike the standard ctime function, this version DOES NOT append |
WiredHome | 0:61112ca9193b | 227 | /// a newline character to the buffer. |
WiredHome | 0:61112ca9193b | 228 | /// |
WiredHome | 14:b5c01a52bff4 | 229 | /// @code |
WiredHome | 14:b5c01a52bff4 | 230 | /// time_t tNow = timelocal(); |
WiredHome | 14:b5c01a52bff4 | 231 | /// tm_ex * tEx = localtime(&tNow); |
WiredHome | 14:b5c01a52bff4 | 232 | /// printf("Time is %s\r\n", asctime(tEx)); |
WiredHome | 14:b5c01a52bff4 | 233 | /// @endcode |
WiredHome | 14:b5c01a52bff4 | 234 | /// |
WiredHome | 21:f3818e2e0370 | 235 | /// @param[in] timeptr is a pointer to a tm_ex structure containing the time to convert. |
WiredHome | 0:61112ca9193b | 236 | /// @returns a pointer to a private buffer containing the string. |
WiredHome | 0:61112ca9193b | 237 | /// |
WiredHome | 0:61112ca9193b | 238 | char * asctime(const struct tm_ex *timeptr); |
WiredHome | 0:61112ca9193b | 239 | |
WiredHome | 0:61112ca9193b | 240 | /// Compute the difference in seconds between two time values. |
WiredHome | 0:61112ca9193b | 241 | /// |
WiredHome | 21:f3818e2e0370 | 242 | /// @code |
WiredHome | 21:f3818e2e0370 | 243 | /// time_t tstart, tend; |
WiredHome | 21:f3818e2e0370 | 244 | /// ... |
WiredHome | 21:f3818e2e0370 | 245 | /// tstart = time(); |
WiredHome | 21:f3818e2e0370 | 246 | /// // do some long process now |
WiredHome | 21:f3818e2e0370 | 247 | /// tend = time(); |
WiredHome | 21:f3818e2e0370 | 248 | /// printf("Elapsed time is %5.3f\r\n", tend - tstart); |
WiredHome | 21:f3818e2e0370 | 249 | /// ... |
WiredHome | 21:f3818e2e0370 | 250 | /// @endcode |
WiredHome | 21:f3818e2e0370 | 251 | /// |
WiredHome | 1:2ee90f546f54 | 252 | /// @param[in] end is the end time to compare to the beginning time. |
WiredHome | 1:2ee90f546f54 | 253 | /// @param[in] beginning time is compared to the end time. |
WiredHome | 0:61112ca9193b | 254 | /// @return the difference in seconds, as a double. |
WiredHome | 0:61112ca9193b | 255 | /// |
WiredHome | 0:61112ca9193b | 256 | double difftime(time_t end, time_t beginning); |
WiredHome | 0:61112ca9193b | 257 | |
WiredHome | 21:f3818e2e0370 | 258 | /// Convert the referenced time_t value to a tm_ex structure in UTC/GMT format. |
WiredHome | 21:f3818e2e0370 | 259 | /// |
WiredHome | 21:f3818e2e0370 | 260 | /// @note Unlike the standard asctime, this return a pointer to a tm_ex, which |
WiredHome | 21:f3818e2e0370 | 261 | /// has a time zone offset element. |
WiredHome | 0:61112ca9193b | 262 | /// |
WiredHome | 0:61112ca9193b | 263 | /// @note Watch out for race conditions as this returns a pointer to a |
WiredHome | 0:61112ca9193b | 264 | /// shared buffer. |
WiredHome | 0:61112ca9193b | 265 | /// |
WiredHome | 1:2ee90f546f54 | 266 | /// @param[in] timer is a pointer to a time_t structure to convert. |
WiredHome | 21:f3818e2e0370 | 267 | /// @returns pointer to a tm_ex structure. |
WiredHome | 0:61112ca9193b | 268 | /// |
WiredHome | 0:61112ca9193b | 269 | struct tm_ex * gmtime(const time_t * timer); |
WiredHome | 0:61112ca9193b | 270 | |
WiredHome | 0:61112ca9193b | 271 | |
WiredHome | 0:61112ca9193b | 272 | /// Convert the referenced time_t value to a tm structure in local format. |
WiredHome | 0:61112ca9193b | 273 | /// |
WiredHome | 6:c79cfe750416 | 274 | /// This method leverages the time zone offset applied with @see set_tzo() |
WiredHome | 6:c79cfe750416 | 275 | /// and the daylight savings time flag applied with @see set_dst(). |
WiredHome | 0:61112ca9193b | 276 | /// |
WiredHome | 0:61112ca9193b | 277 | /// @note Watch out for race conditions as this returns a pointer to a |
WiredHome | 0:61112ca9193b | 278 | /// shared buffer. |
WiredHome | 0:61112ca9193b | 279 | /// |
WiredHome | 14:b5c01a52bff4 | 280 | /// @code |
WiredHome | 14:b5c01a52bff4 | 281 | /// time_t tNow = timelocal(); |
WiredHome | 14:b5c01a52bff4 | 282 | /// tm_ex * tEx = localtime(&tNow); |
WiredHome | 14:b5c01a52bff4 | 283 | /// @endcode |
WiredHome | 14:b5c01a52bff4 | 284 | /// |
WiredHome | 1:2ee90f546f54 | 285 | /// @param[in] timer is a pointer to a time_t structure to convert. |
WiredHome | 0:61112ca9193b | 286 | /// @returns pointer to a tm structure. |
WiredHome | 0:61112ca9193b | 287 | /// |
WiredHome | 0:61112ca9193b | 288 | struct tm_ex * localtime(const time_t * timer); |
WiredHome | 0:61112ca9193b | 289 | |
WiredHome | 0:61112ca9193b | 290 | /// Convert a tm_ex structure (an extended time structure) to a time_t |
WiredHome | 0:61112ca9193b | 291 | /// value. |
WiredHome | 0:61112ca9193b | 292 | /// |
WiredHome | 26:9ee3fac64626 | 293 | /// This function also sets the tzo_min element of the tm_ex structure |
WiredHome | 26:9ee3fac64626 | 294 | /// from the previously set tzo_min. |
WiredHome | 26:9ee3fac64626 | 295 | /// |
WiredHome | 1:2ee90f546f54 | 296 | /// @param[in] timeptr is a pointer to a tm_ex structure. |
WiredHome | 0:61112ca9193b | 297 | /// @returns the computed time_t value. |
WiredHome | 0:61112ca9193b | 298 | /// |
WiredHome | 0:61112ca9193b | 299 | time_t mktime(struct tm_ex * timeptr); |
WiredHome | 0:61112ca9193b | 300 | |
WiredHome | 0:61112ca9193b | 301 | /// Presents a time value in a user specified format, into a user specified buffer. |
WiredHome | 0:61112ca9193b | 302 | /// |
WiredHome | 1:2ee90f546f54 | 303 | /// @param[out] ptr is a pointer to the user buffer. |
WiredHome | 1:2ee90f546f54 | 304 | /// @param[in] maxsize is the size of the user buffer. |
WiredHome | 1:2ee90f546f54 | 305 | /// @param[in] format is a pointer to the special strftime format specification. |
WiredHome | 15:82bd8fc6f317 | 306 | /// see format options. |
WiredHome | 1:2ee90f546f54 | 307 | /// @param[in] timeptr is a pointer to the tm_ex structure. |
WiredHome | 0:61112ca9193b | 308 | /// @returns the total number of characters copied into the buffer. |
WiredHome | 0:61112ca9193b | 309 | /// |
WiredHome | 15:82bd8fc6f317 | 310 | /// format options: |
WiredHome | 15:82bd8fc6f317 | 311 | /// - %%a Abbreviated weekday name e.g. Thu |
WiredHome | 15:82bd8fc6f317 | 312 | /// - %%A Full weekday name e.g. Thursday |
WiredHome | 15:82bd8fc6f317 | 313 | /// - %%b Abbreviated month name e.g. Aug |
WiredHome | 15:82bd8fc6f317 | 314 | /// - %%B Full month name e.g. August |
WiredHome | 15:82bd8fc6f317 | 315 | /// - %%c Date and time representation e.g. Thu Aug 23 14:55:02 2001 |
WiredHome | 15:82bd8fc6f317 | 316 | /// - %%C Year divided by 100 and truncated to integer (00-99) e.g. 20 |
WiredHome | 15:82bd8fc6f317 | 317 | /// - %%d Day of the month, zero-padded (01-31) e.g. 23 |
WiredHome | 15:82bd8fc6f317 | 318 | /// - %%D Short MM/DD/YY date, equivalent to %%m/%%d/%%y e.g. 08/23/01 |
WiredHome | 15:82bd8fc6f317 | 319 | /// - %%e Day of the month, space-padded ( 1-31) e.g. 23 |
WiredHome | 15:82bd8fc6f317 | 320 | /// - %%F Short YYYY-MM-DD date, equivalent to %%Y-%%m-%%d e.g. 2001-08-23 |
WiredHome | 15:82bd8fc6f317 | 321 | /// - %%g Week-based year, last two digits (00-99) e.g. 01 |
WiredHome | 15:82bd8fc6f317 | 322 | /// - %%G Week-based year e.g. 2001 |
WiredHome | 15:82bd8fc6f317 | 323 | /// - %%h Abbreviated month name * (same as %%b) e.g. Aug |
WiredHome | 15:82bd8fc6f317 | 324 | /// - %%H Hour in 24h format (00-23) e.g. 14 |
WiredHome | 15:82bd8fc6f317 | 325 | /// - %%I Hour in 12h format (01-12) e.g. 02 |
WiredHome | 15:82bd8fc6f317 | 326 | /// - %%j Day of the year (001-366) e.g. 235 |
WiredHome | 15:82bd8fc6f317 | 327 | /// - %%m Month as a decimal number (01-12) e.g. 08 |
WiredHome | 15:82bd8fc6f317 | 328 | /// - %%M Minute (00-59) e.g. 55 |
WiredHome | 15:82bd8fc6f317 | 329 | /// - %%n New-line character ('\\n') |
WiredHome | 15:82bd8fc6f317 | 330 | /// - %%p AM or PM designation e.g. PM |
WiredHome | 15:82bd8fc6f317 | 331 | /// - %%r 12-hour clock time e.g. 02:55:02 pm |
WiredHome | 15:82bd8fc6f317 | 332 | /// - %%R 24-hour HH:MM time, equivalent to %%H:%%M e.g. 14:55 |
WiredHome | 15:82bd8fc6f317 | 333 | /// - %%S Second (00-61) e.g. 02 |
WiredHome | 15:82bd8fc6f317 | 334 | /// - %%t Horizontal-tab character ('\t') |
WiredHome | 15:82bd8fc6f317 | 335 | /// - %%T ISO 8601 time format (HH:MM:SS), equivalent to %%H:%%M:%%S e.g. 14:55:02 |
WiredHome | 15:82bd8fc6f317 | 336 | /// - %%u ISO 8601 weekday as number with Monday as 1 (1-7) e.g. 4 |
WiredHome | 15:82bd8fc6f317 | 337 | /// - %%U Week number with the first Sunday as the first day of week one (00-53) e.g. 33 |
WiredHome | 15:82bd8fc6f317 | 338 | /// - %%V ISO 8601 week number (00-53) e.g. 34 |
WiredHome | 15:82bd8fc6f317 | 339 | /// - %%w Weekday as a decimal number with Sunday as 0 (0-6) e.g. 4 |
WiredHome | 15:82bd8fc6f317 | 340 | /// - %%W Week number with the first Monday as the first day of week one (00-53) e.g. 34 |
WiredHome | 15:82bd8fc6f317 | 341 | /// - %%x Date representation e.g. 08/23/01 |
WiredHome | 15:82bd8fc6f317 | 342 | /// - %%X Time representation e.g. 14:55:02 |
WiredHome | 15:82bd8fc6f317 | 343 | /// - %%y Year, last two digits (00-99) e.g. 01 |
WiredHome | 15:82bd8fc6f317 | 344 | /// - %%Y Year e.g. 2001 |
WiredHome | 15:82bd8fc6f317 | 345 | /// - %%z ISO 8601 offset from UTC in timezone (1 minute=1, 1 hour=100) (e.g. +100) |
WiredHome | 15:82bd8fc6f317 | 346 | /// If timezone cannot be determined, no characters |
WiredHome | 15:82bd8fc6f317 | 347 | /// - %%Z Timezone name or abbreviation (e.g. CDT) |
WiredHome | 15:82bd8fc6f317 | 348 | /// If timezone cannot be determined, no characters |
WiredHome | 15:82bd8fc6f317 | 349 | /// - % A % sign |
WiredHome | 15:82bd8fc6f317 | 350 | /// |
WiredHome | 0:61112ca9193b | 351 | size_t strftime(char * ptr, size_t maxsize, const char * format, const struct tm_ex * timeptr); |
WiredHome | 0:61112ca9193b | 352 | |
WiredHome | 10:5734dbc2f5cc | 353 | |
WiredHome | 10:5734dbc2f5cc | 354 | /// Convert a string, in a defined format, to a time value in a tm_ex structure. |
WiredHome | 10:5734dbc2f5cc | 355 | /// |
WiredHome | 10:5734dbc2f5cc | 356 | /// Most format details leveraged from The Open Group Base Specifications Issue 6 |
WiredHome | 10:5734dbc2f5cc | 357 | /// IEEE Std 1003.1, 2004 Edition |
WiredHome | 10:5734dbc2f5cc | 358 | /// Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved. |
WiredHome | 10:5734dbc2f5cc | 359 | /// |
WiredHome | 10:5734dbc2f5cc | 360 | /// Modifications for mbed, and addition of the timezone format option by D. Smart |
WiredHome | 10:5734dbc2f5cc | 361 | /// |
WiredHome | 10:5734dbc2f5cc | 362 | /// @code |
WiredHome | 10:5734dbc2f5cc | 363 | /// char timesample[] = "Jan 22 2017 01:32:48 UTC"; |
WiredHome | 10:5734dbc2f5cc | 364 | /// tm_ex tm; |
WiredHome | 10:5734dbc2f5cc | 365 | /// strptime(timesample, "%b %d %Y %H:%M:%S %Z", &tm); |
WiredHome | 10:5734dbc2f5cc | 366 | /// @endcode |
WiredHome | 10:5734dbc2f5cc | 367 | /// |
WiredHome | 10:5734dbc2f5cc | 368 | /// @param[in] buf is a pointer to the string to be parsed. |
WiredHome | 10:5734dbc2f5cc | 369 | /// @param[in] format is a pointer to a format string. See the format options. |
WiredHome | 10:5734dbc2f5cc | 370 | /// @param[out] tm is a pointer to a tm_ex struct. |
WiredHome | 10:5734dbc2f5cc | 371 | /// @returns a pointer to the character following the last one parsed, or null on failure |
WiredHome | 10:5734dbc2f5cc | 372 | /// |
WiredHome | 10:5734dbc2f5cc | 373 | /// format options: |
WiredHome | 10:5734dbc2f5cc | 374 | /// - %%a The day of the week, using the locale's weekday names; either the abbreviated or |
WiredHome | 10:5734dbc2f5cc | 375 | /// full name may be specified. |
WiredHome | 10:5734dbc2f5cc | 376 | /// - %%A Equivalent to %%a. |
WiredHome | 10:5734dbc2f5cc | 377 | /// - %%b The month, using the locale's month names; either the abbreviated or full name |
WiredHome | 10:5734dbc2f5cc | 378 | /// may be specified. |
WiredHome | 10:5734dbc2f5cc | 379 | /// - %%B Equivalent to %%b. |
WiredHome | 10:5734dbc2f5cc | 380 | /// - %%c Replaced by the locale's appropriate date and time representation. |
WiredHome | 10:5734dbc2f5cc | 381 | /// - %%C The century number [00,99]; leading zeros are permitted but not required. |
WiredHome | 10:5734dbc2f5cc | 382 | /// - %%d The day of the month [01,31]; leading zeros are permitted but not required. |
WiredHome | 10:5734dbc2f5cc | 383 | /// - %%D The date as %%m / %%d / %%y. |
WiredHome | 10:5734dbc2f5cc | 384 | /// - %%e Equivalent to %%d. |
WiredHome | 10:5734dbc2f5cc | 385 | /// - %%h Equivalent to %%b. |
WiredHome | 10:5734dbc2f5cc | 386 | /// - %%H The hour (24-hour clock) [00,23]; leading zeros are permitted but not required. |
WiredHome | 10:5734dbc2f5cc | 387 | /// - %%I The hour (12-hour clock) [01,12]; leading zeros are permitted but not required. |
WiredHome | 10:5734dbc2f5cc | 388 | /// - %%j The day number of the year [001,366]; leading zeros are permitted but not required. |
WiredHome | 10:5734dbc2f5cc | 389 | /// - %%m The month number [01,12]; leading zeros are permitted but not required. |
WiredHome | 10:5734dbc2f5cc | 390 | /// - %%M The minute [00,59]; leading zeros are permitted but not required. |
WiredHome | 10:5734dbc2f5cc | 391 | /// - %%n Any white space. |
WiredHome | 10:5734dbc2f5cc | 392 | /// - %%p The locale's equivalent of a.m or p.m. |
WiredHome | 10:5734dbc2f5cc | 393 | /// - %%r 12-hour clock time using the AM/PM notation if t_fmt_ampm is not an empty string |
WiredHome | 10:5734dbc2f5cc | 394 | /// in the LC_TIME portion of the current locale; in the POSIX locale, this shall be |
WiredHome | 10:5734dbc2f5cc | 395 | /// equivalent to %%I : %%M : %%S %%p. |
WiredHome | 10:5734dbc2f5cc | 396 | /// - %%R The time as %%H : %%M. |
WiredHome | 10:5734dbc2f5cc | 397 | /// - %%S The seconds [00,60]; leading zeros are permitted but not required. |
WiredHome | 10:5734dbc2f5cc | 398 | /// - %%t Any white space. |
WiredHome | 10:5734dbc2f5cc | 399 | /// - %%T The time as %%H : %%M : %%S. |
WiredHome | 10:5734dbc2f5cc | 400 | /// - %%U The week number of the year (Sunday as the first day of the week) as a decimal |
WiredHome | 10:5734dbc2f5cc | 401 | /// number [00,53]; leading zeros are permitted but not required. |
WiredHome | 10:5734dbc2f5cc | 402 | /// - %%w The weekday as a decimal number [0,6], with 0 representing Sunday; leading zeros |
WiredHome | 10:5734dbc2f5cc | 403 | /// are permitted but not required. |
WiredHome | 10:5734dbc2f5cc | 404 | /// - %%W The week number of the year (Monday as the first day of the week) as a decimal |
WiredHome | 10:5734dbc2f5cc | 405 | /// number [00,53]; leading zeros are permitted but not required. |
WiredHome | 10:5734dbc2f5cc | 406 | /// - %%x The date, using the locale's date format. |
WiredHome | 10:5734dbc2f5cc | 407 | /// - %%X The time, using the locale's time format. |
WiredHome | 10:5734dbc2f5cc | 408 | /// - %%y The year within century. When a century is not otherwise specified, values in |
WiredHome | 10:5734dbc2f5cc | 409 | /// the range [69,99] shall refer to years 1969 to 1999 inclusive, and values in the |
WiredHome | 10:5734dbc2f5cc | 410 | /// range [00,68] shall refer to years 2000 to 2068 inclusive; leading zeros shall be |
WiredHome | 10:5734dbc2f5cc | 411 | /// permitted but shall not be required. |
WiredHome | 10:5734dbc2f5cc | 412 | /// Note: It is expected that in a future version of IEEE Std 1003.1-2001 |
WiredHome | 10:5734dbc2f5cc | 413 | /// the default century inferred from a 2-digit year will change. |
WiredHome | 10:5734dbc2f5cc | 414 | /// (This would apply to all commands accepting a 2-digit year as input.) |
WiredHome | 10:5734dbc2f5cc | 415 | /// - %%Y The year, including the century (for example, 1988). |
WiredHome | 10:5734dbc2f5cc | 416 | /// - %%Z The timezone offset, as a 3-letter sequence. Only a few whole-hour offsets |
WiredHome | 10:5734dbc2f5cc | 417 | /// have been defined. |
WiredHome | 11:1d880a50da8a | 418 | /// - %% Replaced by %. |
WiredHome | 10:5734dbc2f5cc | 419 | /// |
WiredHome | 10:5734dbc2f5cc | 420 | const char * strptime(const char *buf, char *fmt, struct tm_ex *tm); |
WiredHome | 10:5734dbc2f5cc | 421 | |
WiredHome | 10:5734dbc2f5cc | 422 | |
WiredHome | 0:61112ca9193b | 423 | // time zone functions |
WiredHome | 0:61112ca9193b | 424 | |
WiredHome | 8:18489e877b0b | 425 | /// Set the internal RTC (clock) to the time value. |
WiredHome | 8:18489e877b0b | 426 | /// |
WiredHome | 8:18489e877b0b | 427 | /// The time valueshould be UTC time along with an offset of zero, |
WiredHome | 8:18489e877b0b | 428 | /// which then permits gmtime and localtime to be used appropriately. |
WiredHome | 8:18489e877b0b | 429 | /// Alternately, the time can be in localtime, and the offset is then |
WiredHome | 8:18489e877b0b | 430 | /// used to compute UTC to set the clock. |
WiredHome | 0:61112ca9193b | 431 | /// |
WiredHome | 2:65e0a25c7551 | 432 | /// @param[in] t should be the UTC time value to set the clock to. If the available |
WiredHome | 0:61112ca9193b | 433 | /// time value is local time, the optional time zone offset can |
WiredHome | 2:65e0a25c7551 | 434 | /// be provided so the system clock is UTC. |
WiredHome | 1:2ee90f546f54 | 435 | /// @param[in] tzo is the optional time zone offset in minutes when it is in |
WiredHome | 0:61112ca9193b | 436 | /// the range of -720 to +720 (-12 hours to + 12 hours). Any |
WiredHome | 0:61112ca9193b | 437 | /// other value is illegal and no change will be made. |
WiredHome | 0:61112ca9193b | 438 | /// |
WiredHome | 0:61112ca9193b | 439 | void set_time(time_t t, int16_t tzo_min = 0); |
WiredHome | 0:61112ca9193b | 440 | |
WiredHome | 0:61112ca9193b | 441 | /// Set the time zone offset in minutes. |
WiredHome | 0:61112ca9193b | 442 | /// |
WiredHome | 0:61112ca9193b | 443 | /// This API should be used before any other methods that fetch |
WiredHome | 0:61112ca9193b | 444 | /// the RTC info. |
WiredHome | 0:61112ca9193b | 445 | /// |
WiredHome | 1:2ee90f546f54 | 446 | /// @param[in] tzo is the time zone offset in minutes when it is in |
WiredHome | 0:61112ca9193b | 447 | /// the range of -720 to +720 (-12 hours to + 12 hours). Any |
WiredHome | 0:61112ca9193b | 448 | /// other value is illegal and no change will be made. |
WiredHome | 0:61112ca9193b | 449 | /// |
WiredHome | 0:61112ca9193b | 450 | void set_tzo_min(int16_t tzo_min); |
WiredHome | 0:61112ca9193b | 451 | |
WiredHome | 0:61112ca9193b | 452 | /// Get the time zone offset in minutes. |
WiredHome | 0:61112ca9193b | 453 | /// |
WiredHome | 0:61112ca9193b | 454 | /// @returns the time zone offset value in minutes. If the tzo was |
WiredHome | 0:61112ca9193b | 455 | /// never initialized, this returns zero. |
WiredHome | 0:61112ca9193b | 456 | /// |
WiredHome | 0:61112ca9193b | 457 | int16_t get_tzo_min(void); |
WiredHome | 0:61112ca9193b | 458 | |
WiredHome | 3:49f36b489b64 | 459 | /// Set the clock for local time to report whether the current |
WiredHome | 3:49f36b489b64 | 460 | /// mode is standard or daylight savings time. |
WiredHome | 3:49f36b489b64 | 461 | /// |
WiredHome | 3:49f36b489b64 | 462 | /// return values for localtime will then be adjusted not only |
WiredHome | 3:49f36b489b64 | 463 | /// for the time zone offset, but for dst. |
WiredHome | 3:49f36b489b64 | 464 | /// |
WiredHome | 3:49f36b489b64 | 465 | /// @param[in] dst is a boolean that should be set when dst is |
WiredHome | 3:49f36b489b64 | 466 | /// the active mode. |
WiredHome | 6:c79cfe750416 | 467 | /// @returns true, always. |
WiredHome | 3:49f36b489b64 | 468 | /// |
WiredHome | 6:c79cfe750416 | 469 | bool set_dst(bool dst); |
WiredHome | 6:c79cfe750416 | 470 | |
WiredHome | 6:c79cfe750416 | 471 | /// Set the clock for auto-adjust local time based on |
WiredHome | 6:c79cfe750416 | 472 | /// changing to standard or daylight savings time. |
WiredHome | 6:c79cfe750416 | 473 | /// |
WiredHome | 6:c79cfe750416 | 474 | /// return values for localtime will then be adjusted not only |
WiredHome | 6:c79cfe750416 | 475 | /// for the time zone offset, but for dst. |
WiredHome | 6:c79cfe750416 | 476 | /// |
WiredHome | 6:c79cfe750416 | 477 | /// @param[in] dstStart is a string of the form "mm/dd,hh:mm" |
WiredHome | 6:c79cfe750416 | 478 | /// representing when DST starts. |
WiredHome | 6:c79cfe750416 | 479 | /// @param[in] dstStop is a string of the form "mm/dd,hh:mm" |
WiredHome | 6:c79cfe750416 | 480 | /// representing when DST stops. |
WiredHome | 6:c79cfe750416 | 481 | /// @returns true if the start and stop pair could be successfully |
WiredHome | 6:c79cfe750416 | 482 | /// parsed. |
WiredHome | 6:c79cfe750416 | 483 | /// |
WiredHome | 6:c79cfe750416 | 484 | bool set_dst(const char * dstStart, const char * dstStop); |
WiredHome | 3:49f36b489b64 | 485 | |
WiredHome | 3:49f36b489b64 | 486 | /// Get the current clock mode for daylight savings time. |
WiredHome | 3:49f36b489b64 | 487 | /// |
WiredHome | 3:49f36b489b64 | 488 | /// @returns true if clock is in dst mode. |
WiredHome | 3:49f36b489b64 | 489 | /// |
WiredHome | 3:49f36b489b64 | 490 | bool get_dst(void); |
WiredHome | 3:49f36b489b64 | 491 | |
WiredHome | 0:61112ca9193b | 492 | /// Get the time value when the clock was last set. This is most |
WiredHome | 0:61112ca9193b | 493 | /// often used in calibration of the clock. |
WiredHome | 0:61112ca9193b | 494 | /// |
WiredHome | 0:61112ca9193b | 495 | /// @returns time last set as a UTC time value. |
WiredHome | 0:61112ca9193b | 496 | /// |
WiredHome | 0:61112ca9193b | 497 | time_t get_timelastset(void); |
WiredHome | 0:61112ca9193b | 498 | |
WiredHome | 0:61112ca9193b | 499 | /// get_cal will return the calibration register value |
WiredHome | 0:61112ca9193b | 500 | /// |
WiredHome | 0:61112ca9193b | 501 | /// This is the raw register value as a signed 32-bit value (even though |
WiredHome | 0:61112ca9193b | 502 | /// it is actually a 17-bit unsigned value with an additional 'direction' flag). |
WiredHome | 0:61112ca9193b | 503 | /// |
WiredHome | 0:61112ca9193b | 504 | /// @returns calibration settings ranging from -131071 to +131071 |
WiredHome | 0:61112ca9193b | 505 | /// |
WiredHome | 0:61112ca9193b | 506 | int32_t get_cal(); |
WiredHome | 0:61112ca9193b | 507 | |
WiredHome | 0:61112ca9193b | 508 | /// set_cal will set the calibration register value |
WiredHome | 0:61112ca9193b | 509 | /// |
WiredHome | 0:61112ca9193b | 510 | /// This accepts a signed value to be used to set the calibration |
WiredHome | 0:61112ca9193b | 511 | /// registers. Setting the calibration value to zero disables the |
WiredHome | 0:61112ca9193b | 512 | /// calibration function. |
WiredHome | 0:61112ca9193b | 513 | /// |
WiredHome | 0:61112ca9193b | 514 | /// It is important to know the register function in order to use |
WiredHome | 0:61112ca9193b | 515 | /// this command, and this API is normally not used by external |
WiredHome | 0:61112ca9193b | 516 | /// application code. @See AdjustBySeconds for a user-friendly |
WiredHome | 0:61112ca9193b | 517 | /// API. |
WiredHome | 0:61112ca9193b | 518 | /// |
WiredHome | 1:2ee90f546f54 | 519 | /// @param[in] calibration value to use ranging from -131071 to +131071 |
WiredHome | 0:61112ca9193b | 520 | /// @returns nothing |
WiredHome | 0:61112ca9193b | 521 | /// |
WiredHome | 0:61112ca9193b | 522 | void set_cal(int32_t calibration); |
WiredHome | 0:61112ca9193b | 523 | |
WiredHome | 0:61112ca9193b | 524 | /// adjust_sec adjusts both the time and the calibration by seconds |
WiredHome | 0:61112ca9193b | 525 | /// |
WiredHome | 0:61112ca9193b | 526 | /// This will take a signed value, which is the current adjustment in seconds |
WiredHome | 0:61112ca9193b | 527 | /// to put the clock on the correct time. So, if the clock is behind by |
WiredHome | 0:61112ca9193b | 528 | /// 3 seconds, the value should be +3 to advance the clock accordingly. |
WiredHome | 0:61112ca9193b | 529 | /// It will then adjust the time, and it will attempt to adjust the |
WiredHome | 0:61112ca9193b | 530 | /// calibration factor to make the time more accurate. |
WiredHome | 0:61112ca9193b | 531 | /// |
WiredHome | 0:61112ca9193b | 532 | /// The adjustment can only be made if it has retained when the clock was |
WiredHome | 0:61112ca9193b | 533 | /// last set, in order to know by how much to adjust it. It is also most |
WiredHome | 0:61112ca9193b | 534 | /// accurate if several days have elapsed since the time was set. |
WiredHome | 0:61112ca9193b | 535 | /// |
WiredHome | 0:61112ca9193b | 536 | /// @note The current version only works if the calibration value |
WiredHome | 0:61112ca9193b | 537 | /// is zero when this adjustment is made. |
WiredHome | 0:61112ca9193b | 538 | /// |
WiredHome | 1:2ee90f546f54 | 539 | /// @param[in] adjustSeconds is the signed value by which to adjust the time to |
WiredHome | 0:61112ca9193b | 540 | /// correct it to the current actual time. |
WiredHome | 0:61112ca9193b | 541 | /// @returns true if the adjustment was made |
WiredHome | 0:61112ca9193b | 542 | /// @returns false if the adjustment could not be made |
WiredHome | 0:61112ca9193b | 543 | /// |
WiredHome | 0:61112ca9193b | 544 | bool adjust_sec(int32_t adjustSeconds); |
WiredHome | 0:61112ca9193b | 545 | |
WiredHome | 2:65e0a25c7551 | 546 | /// Set the clock from an internet source (blocking) |
WiredHome | 2:65e0a25c7551 | 547 | /// |
WiredHome | 2:65e0a25c7551 | 548 | /// This function is the interface to NTPClient. |
WiredHome | 2:65e0a25c7551 | 549 | /// Blocks until completion |
WiredHome | 2:65e0a25c7551 | 550 | /// |
WiredHome | 2:65e0a25c7551 | 551 | /// @param[in] host NTP server IPv4 address or hostname (will be resolved via DNS) |
WiredHome | 2:65e0a25c7551 | 552 | /// @param[in] port port to use; defaults to 123 |
WiredHome | 2:65e0a25c7551 | 553 | /// @param[in] timeout waiting timeout in ms (osWaitForever for blocking function, not recommended) |
WiredHome | 21:f3818e2e0370 | 554 | /// @returns NTP_OK on success, |
WiredHome | 21:f3818e2e0370 | 555 | /// @returns NTP_CONN if no network interface |
WiredHome | 21:f3818e2e0370 | 556 | /// @returns other NTP error code (<0) on failure |
WiredHome | 2:65e0a25c7551 | 557 | /// |
WiredHome | 2:65e0a25c7551 | 558 | NTPResult setTime(const char* host, uint16_t port = NTP_DEFAULT_PORT, uint32_t timeout = NTP_DEFAULT_TIMEOUT); |
WiredHome | 2:65e0a25c7551 | 559 | |
WiredHome | 2:65e0a25c7551 | 560 | // ntp interface functions |
WiredHome | 0:61112ca9193b | 561 | private: |
WiredHome | 20:5ca2c94d46b8 | 562 | EthernetInterface * m_net; |
WiredHome | 20:5ca2c94d46b8 | 563 | |
WiredHome | 6:c79cfe750416 | 564 | typedef struct { |
WiredHome | 6:c79cfe750416 | 565 | uint8_t MM; |
WiredHome | 6:c79cfe750416 | 566 | uint8_t DD; |
WiredHome | 6:c79cfe750416 | 567 | uint8_t hh; |
WiredHome | 6:c79cfe750416 | 568 | uint8_t mm; |
WiredHome | 6:c79cfe750416 | 569 | } dst_event_t; |
WiredHome | 6:c79cfe750416 | 570 | typedef struct { |
WiredHome | 6:c79cfe750416 | 571 | dst_event_t dst_start; |
WiredHome | 6:c79cfe750416 | 572 | dst_event_t dst_stop; |
WiredHome | 6:c79cfe750416 | 573 | } dst_event_pair_t; |
WiredHome | 6:c79cfe750416 | 574 | |
WiredHome | 6:c79cfe750416 | 575 | bool parseDSTstring(dst_event_t * result, const char * dstr); |
WiredHome | 6:c79cfe750416 | 576 | |
WiredHome | 6:c79cfe750416 | 577 | /// Performs a "simple" computation of two dates into minutes. |
WiredHome | 6:c79cfe750416 | 578 | /// |
WiredHome | 6:c79cfe750416 | 579 | /// Does not account for leap years or which month it is. Is |
WiredHome | 6:c79cfe750416 | 580 | /// useful only for comparing which date/time came first, not for |
WiredHome | 6:c79cfe750416 | 581 | /// computing the difference between them. |
WiredHome | 6:c79cfe750416 | 582 | /// |
WiredHome | 6:c79cfe750416 | 583 | /// @return "normalized" minutes since Jan 1 00:00. |
WiredHome | 6:c79cfe750416 | 584 | /// |
WiredHome | 6:c79cfe750416 | 585 | uint32_t minutesSinceJan(int mon, int day, int hr, int min); |
WiredHome | 6:c79cfe750416 | 586 | |
WiredHome | 6:c79cfe750416 | 587 | dst_event_pair_t dst_pair; |
WiredHome | 6:c79cfe750416 | 588 | bool dst; // true in dst mode |
WiredHome | 0:61112ca9193b | 589 | char result[30]; // holds the converted to text time string |
WiredHome | 0:61112ca9193b | 590 | time_t tresult; // holds the converted time structure. |
WiredHome | 0:61112ca9193b | 591 | struct tm_ex tm_ext; |
WiredHome | 0:61112ca9193b | 592 | }; |
WiredHome | 0:61112ca9193b | 593 | |
WiredHome | 11:1d880a50da8a | 594 | #endif // TIMEINTERFACE_H |