Diff: TimeInterface.h

Revision:

1:2ee90f546f54

Parent:

0:61112ca9193b

Child:

2:65e0a25c7551

--- a/TimeInterface.h	Sun Jun 08 00:18:43 2014 +0000
+++ b/TimeInterface.h	Sat Jun 14 12:34:53 2014 +0000
@@ -78,12 +78,29 @@
     /// t_ref1 = time(NULL); t_ref2 = t.time(); t.time(&t_ref3);
     /// @endcode
     ///
-    /// @param timer is an optional pointer to a time_t value that will be written. 
+    /// @param[inout] timer is an optional pointer to a time_t value that will be written. 
     ///     This pointer is ignored when NULL.
     /// @returns time value.
     ///
     time_t time(time_t * timer = NULL);
 
+    /// Gets the current local time as a time value, optionally writing it
+    /// to a provided buffer.
+    ///
+    /// This reads the real time clock and returns the current time, adjusted
+    /// for the local timezone.
+    ///
+    /// @code
+    /// time_t t_ref2, t_ref3;
+    /// t_ref2 = t.time(); t.timelocal(&t_ref3);
+    /// @endcode
+    ///
+    /// @param[inout] timer is an optional pointer to a time_t value that will be written. 
+    ///     This pointer is ignored when NULL.
+    /// @returns the time value adjusted for the local time zone.
+    ///
+    time_t timelocal(time_t * timer = NULL);
+
     /// 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
@@ -91,7 +108,7 @@
     /// @note Unlike the standard ctime function, this version DOES NOT append 
     ///     a newline character to the buffer.
     ///
-    /// @param timeptr is a pointer to a tm structure containing the time to convert.
+    /// @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);
@@ -103,15 +120,15 @@
     /// @note Unlike the standard ctime function, this version DOES NOT append 
     ///     a newline character to the buffer.
     ///
-    /// @param timeptr is a pointer to a tm structure containing the time to convert.
+    /// @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 * asctime(const struct tm_ex *timeptr);
 
     /// Compute the difference in seconds between two time values.
     ///
-    /// @param end is the end time to compare to the beginning time.
-    /// @param beginning time is compared to the end time.
+    /// @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);
@@ -121,7 +138,7 @@
     /// @note Watch out for race conditions as this returns a pointer to a
     ///     shared buffer.
     ///
-    /// @param timer is a pointer to a time_t structure to convert.
+    /// @param[in] timer is a pointer to a time_t structure to convert.
     /// @returns pointer to a tm structure.
     ///
     struct tm_ex * gmtime(const time_t * timer);
@@ -134,7 +151,7 @@
     /// @note Watch out for race conditions as this returns a pointer to a
     ///     shared buffer.
     ///
-    /// @param timer is a pointer to a time_t structure to convert.
+    /// @param[in] timer is a pointer to a time_t structure to convert.
     /// @returns pointer to a tm structure.
     ///
     struct tm_ex * localtime(const time_t * timer);
@@ -142,17 +159,17 @@
     /// Convert a tm_ex structure (an extended time structure) to a time_t
     /// value.
     ///
-    /// @param timeptr is a pointer to a tm_ex structure.
+    /// @param[in] timeptr is a pointer to a tm_ex structure.
     /// @returns the computed time_t value.
     ///
     time_t mktime(struct tm_ex * timeptr);
     
     /// Presents a time value in a user specified format, into a user specified buffer.
     ///
-    /// @param ptr is a pointer to the user buffer.
-    /// @param maxsize is the size of the user buffer.
-    /// @param format is a pointer to the special strftime format specification.
-    /// @param timeptr is a pointer to the tm_ex structure.
+    /// @param[out] ptr is a pointer to the user buffer.
+    /// @param[in] maxsize is the size of the user buffer.
+    /// @param[in] format is a pointer to the special strftime format specification.
+    /// @param[in] timeptr is a pointer to the tm_ex structure.
     /// @returns the total number of characters copied into the buffer.
     ///
     size_t strftime(char * ptr, size_t maxsize, const char * format, const struct tm_ex * timeptr);
@@ -163,10 +180,10 @@
     /// should be the UTC time, which then permits gmtime and 
     /// localtime to be used appropriately.
     ///
-    /// @param t is the UTC time value to set the clock to. If the available 
+    /// @param[in] t is the UTC time value to set the clock to. If the available 
     ///     time value is local time, the optional time zone offset can
     ///     be provided.
-    /// @param tzo is the optional time zone offset in minutes when it is in
+    /// @param[in] tzo is the optional time zone offset in minutes when it is in
     ///     the range of -720 to +720 (-12 hours to + 12 hours). Any
     ///     other value is illegal and no change will be made.
     ///
@@ -177,7 +194,7 @@
     /// This API should be used before any other methods that fetch
     /// the RTC info.
     ///
-    /// @param tzo is the time zone offset in minutes when it is in
+    /// @param[in] tzo is the time zone offset in minutes when it is in
     ///     the range of -720 to +720 (-12 hours to + 12 hours). Any
     ///     other value is illegal and no change will be made.
     ///
@@ -217,7 +234,7 @@
     /// application code. @See AdjustBySeconds for a user-friendly
     /// API.
     ///
-    /// @param calibration value to use ranging from -131071 to +131071
+    /// @param[in] calibration value to use ranging from -131071 to +131071
     /// @returns nothing
     ///
     void set_cal(int32_t calibration);
@@ -237,7 +254,7 @@
     /// @note The current version only works if the calibration value
     ///       is zero when this adjustment is made.
     /// 
-    /// @param adjustSeconds is the signed value by which to adjust the time to
+    /// @param[in] adjustSeconds is the signed value by which to adjust the time to
     ///        correct it to the current actual time.
     /// @returns true if the adjustment was made
     /// @returns false if the adjustment could not be made