Diff: TimeInterface.h

Revision:

21:f3818e2e0370

Parent:

20:5ca2c94d46b8

Child:

24:45a9e7081499

--- a/TimeInterface.h	Mon Nov 20 17:09:48 2017 +0000
+++ b/TimeInterface.h	Tue Nov 21 17:04:12 2017 +0000
@@ -4,7 +4,7 @@
 #include "mbed.h"
 #include <ctime>
 
-#include "NTPClient.h"  // ver 9
+#include "NTPClient.h"
 
 // Special Registers and their usage:
 // GPREG0: 32 bits
@@ -15,10 +15,10 @@
 
 
 extern "C" {
-#include "time.h"
+#include "time.h"       // uses some std::time-functions
 }
 
-/// The tm_ex structure is patterened after the traditional tm struct, however
+/// The tm_ex structure is patterned after the traditional tm struct, however
 /// it adds an element - the time zone offset in minutes. From this, it is then
 /// readily able to create a "local time" instead of simply a UTC time.
 ///
@@ -55,7 +55,7 @@
 ///     but manages the time-zone offset as it does so.
 ///
 /// @code
-/// // TimeInterface Architecture
+/// // TimeInterface Architecture and APIs
 /// //
 /// // +--------+
 /// // | clock  |----> clock_t clock()
@@ -106,7 +106,8 @@
 /// //  | +- strftime(char * ptr, ..., tm_ex *) --> | buffer                   |
 /// //  +----strptime(char * buf, ..., tm_ex *) --- | Www Mmm dd hh:mm:ss yyyy |
 /// //                                              +--------------------------+
-/// //  double difftime(time_t end, time_t)
+/// //      double difftime(time_t end, time_t)
+/// //
 /// @endcode
 ///
 class TimeInterface
@@ -117,6 +118,18 @@
     /// @param[in] net is optional and provides the EthernetInterface which is
     ///             used if you want to sync to an NTP server
     ///
+    /// @code
+    /// EthernetInterface net;
+    /// TimeInterface ntp(&net);
+    /// ...
+    ///     ntp.set_tzo_min(-6 * 60);
+    ///     if (NTP_OK == ntp.setTime("time.nist.gov", 123, 10)) {
+    ///         time_t tNow = ntp.timelocal();
+    ///         printf("time is %s\r\n", ntp.ctime(&tNow));
+    ///     }
+    /// ...
+    /// @endcode
+    ///
     TimeInterface(EthernetInterface *m_net = NULL);
     
     /// Destructor, normally not used, because it is typically kept for the life
@@ -130,10 +143,12 @@
     ///
     /// @code
     /// clock_t tstart, tend;
-    /// tstart = clock();
-    /// // do something long
-    /// tend = clock();
-    /// printf("Elapsed time is %5.3f\r\n", (float)(tend - tstart)/CLOCKS_PER_SEC);
+    /// ...
+    ///     tstart = clock();
+    ///     // do something long
+    ///     tend = clock();
+    ///     printf("Elapsed time is %5.3f\r\n", (float)(tend - tstart)/CLOCKS_PER_SEC);
+    /// ...
     /// @endcode
     ///
     /// @returns elapsed tics.
@@ -147,11 +162,14 @@
     ///
     /// @code
     /// time_t t_ref1, t_ref2, t_ref3;
-    /// t_ref1 = time(NULL); t_ref2 = t.time(); t.time(&t_ref3);
+    /// t_ref1 = time(NULL); 
+    /// t_ref2 = t.time(); 
+    /// (void)t.time(&t_ref3);
     /// @endcode
     ///
-    /// @param[in,out] timer is an optional pointer to a time_t value that will be written. 
-    ///     This pointer is ignored when NULL.
+    /// @param[out] timer is an optional pointer to a time_t value that will 
+    ///             be written with the current time. This pointer is ignored 
+    ///             when NULL.
     /// @returns the UTC time value.
     ///
     time_t time(time_t * timer = NULL);
@@ -160,40 +178,45 @@
     /// to a provided buffer.
     ///
     /// This reads the real time clock and returns the current time, adjusted
-    /// for the local timezone and daylight savings time.
+    /// for the local time zone and daylight savings time.
     ///
     /// @code
     /// time_t t_ref2, t_ref3;
-    /// t_ref2 = t.time(); t.timelocal(&t_ref3);
+    /// t_ref2 = t.time(); 
+    /// t.timelocal(&t_ref3);
     /// @endcode
     ///
-    /// @param[in,out] timer is an optional pointer to a time_t value that will be written. 
-    ///     This pointer is ignored when NULL.
-    /// @returns the LOCAL time value (UTC adjusted for the LOCAL time zone).
+    /// @param[out] timer is an optional pointer to a time_t value that will 
+    ///     be written. This pointer is ignored when NULL.
+    /// @returns the LOCAL time value (UTC adjusted for the LOCAL time zone and dst).
     ///
     time_t timelocal(time_t * timer = NULL);
 
-    /// Convert a time value structure into an ASCII printable time Www Mmm dd hh:mm:ss yyyy
+    /// Convert a time value structure into an ASCII printable time "Www Mmm dd hh:mm:ss yyyy"
+    ///
+    /// @note Watch out for race conditions as this returns a pointer to a
+    ///         shared buffer.
+    /// @note Unlike the standard ctime function, this version DOES NOT append 
+    ///         a newline character to the buffer.
+    ///
+    /// @code
+    /// time_t tNow = timelocal();
+    /// printf("time is %s\r\n", ctime(tNow));
+    /// @endcode
+    ///
+    /// @param[in] timer is a pointer to a time_t value containing the time to convert.
+    /// @returns a pointer to a buffer containing the string.
+    ///
+    char * ctime(const time_t * timer);
+
+    /// Convert a tm_ex structure into an ASCII printable "time Www Mmm dd hh:mm:ss yyyy"
+    ///
+    /// @note Unlike the standard asctime, this takes a pointer to a tm_ex, which 
+    ///         has a time zone offset element.
     ///
     /// @note Watch out for race conditions as this returns a pointer to a
     ///     shared buffer.
-    /// @note Unlike the standard ctime function, this version DOES NOT append 
-    ///     a newline character to the buffer.
     ///
-    /// @code
-    /// time_t tsample = timelocal();
-    /// printf("time is %s\r\n", ctime(tsample));
-    /// @endcode
-    ///
-    /// @param[in] timeptr is a pointer to a tm structure containing the time to convert.
-    /// @returns a pointer to a private buffer containing the string.
-    ///
-    char * ctime(const time_t * timer);
-
-    /// Convert a tm structure into an ASCII printable time Www Mmm dd hh:mm:ss yyyy
-    ///
-    /// @note Watch out for race conditions as this returns a pointer to a
-    ///     shared buffer.
     /// @note Unlike the standard ctime function, this version DOES NOT append 
     ///     a newline character to the buffer.
     ///
@@ -203,26 +226,39 @@
     /// printf("Time is %s\r\n", asctime(tEx));
     /// @endcode
     ///
-    /// @param[in] timeptr is a pointer to a tm structure containing the time to convert.
+    /// @param[in] timeptr is a pointer to a tm_ex structure containing the time to convert.
     /// @returns a pointer to a private buffer containing the string.
     ///
     char * asctime(const struct tm_ex *timeptr);
 
     /// Compute the difference in seconds between two time values.
     ///
+    /// @code
+    /// time_t tstart, tend;
+    /// ...
+    ///     tstart = time();
+    ///     // do some long process now
+    ///     tend = time();
+    ///     printf("Elapsed time is %5.3f\r\n", tend - tstart);
+    /// ...
+    /// @endcode
+    ///
     /// @param[in] end is the end time to compare to the beginning time.
     /// @param[in] beginning time is compared to the end time.
     /// @return the difference in seconds, as a double.
     ///
     double difftime(time_t end, time_t beginning);
     
-    /// Convert the referenced time_t value to a tm structure in UTC/GMT format.
+    /// Convert the referenced time_t value to a tm_ex structure in UTC/GMT format.
+    ///
+    /// @note Unlike the standard asctime, this return a pointer to a tm_ex, which 
+    ///         has a time zone offset element.
     ///
     /// @note Watch out for race conditions as this returns a pointer to a
     ///     shared buffer.
     ///
     /// @param[in] timer is a pointer to a time_t structure to convert.
-    /// @returns pointer to a tm structure.
+    /// @returns pointer to a tm_ex structure.
     ///
     struct tm_ex * gmtime(const time_t * timer);
     
@@ -506,7 +542,9 @@
     /// @param[in] host NTP server IPv4 address or hostname (will be resolved via DNS)
     /// @param[in] port port to use; defaults to 123
     /// @param[in] timeout waiting timeout in ms (osWaitForever for blocking function, not recommended)
-    /// @return 0 on success, NTP error code (<0) on failure
+    /// @returns NTP_OK on success, 
+    /// @returns NTP_CONN if no network interface
+    /// @returns other NTP error code (<0) on failure
     ///
     NTPResult setTime(const char* host, uint16_t port = NTP_DEFAULT_PORT, uint32_t timeout = NTP_DEFAULT_TIMEOUT);