le_clock.h

Go to the documentation of this file.
    1 /**
    2  * @page c_clock System Clock API
    3  *
    4  * @ref le_clock.h "API Reference"
    5  *
    6  * <HR>
    7  *
    8  * This module provides an API for getting/setting date and/or time values, and
    9  * performing conversions between these values.
   10  *
   11  * @todo This API is currently incomplete, as it only provides a subset of functions that will
   12  * eventually be supported.
   13  *
   14  *
   15  * @section clk_time Getting/Setting Time
   16  *
   17  * Time values can either be absolute or relative.  Time is expressed in seconds
   18  * plus microseconds, and does not stop when the system is suspended (i.e., the clock continues to
   19  * run even when the system is suspended).
   20  *
   21  * Absolute time is given as time since the Epoch, 1970-01-01 00:00:00 +0000 (UTC) and is provided
   22  * by @ref le_clk_GetAbsoluteTime().  By definition, it is UTC time. The absolute time may jump
   23  * forward or backward if a new value is set for the absolute time.
   24  *
   25  * Relative time is a monotonic time from a fixed but unspecified starting point and is provided
   26  * by @ref le_clk_GetRelativeTime(). The relative time is independent of the absolute time.  The
   27  * starting point is fixed during system boot, and cannot be changed, but is reset on each system
   28  * boot. Since the relative time is monotonic, it is guaranteed to never go backwards. With these
   29  * characteristics, the relative time is useful for measuring the time between two or more events.
   30  * For example, at event 1, relative time A is stored, and at some later event 2, relative time B
   31  * is stored.  The relative time between these two events can always be calculated as B-A, and will
   32  * always be an accurate measure of the relative time between these two events.
   33  *
   34  * @todo
   35  *  - Add API for setting absolute time.
   36  *
   37  *
   38  * @section clk_values Operations on Time Values
   39  *
   40  * These operations can be performed on time values:
   41  *  - @ref le_clk_Add
   42  *  - @ref le_clk_GreaterThan
   43  *  - @ref le_clk_Sub
   44  *  - @ref le_clk_Multiply
   45  *
   46  * The functions use these assumptions:
   47  *  - All input time values are normalized (i.e., the usec value is less than 1 sec). All time values
   48  *    returned are normalized.
   49  *  - All input time values or scale factors are positive; a negative time value will not be returned.
   50  *  - All input time values or scale factors are expected to have reasonable values (i.e., they will not
   51  *    be so large as to cause an overflow of the time value structure).
   52  *
   53  *
   54  * @section clk_convert Converting Time to Other Formats
   55  *
   56  * The current absolute time can be converted to a formatted string in either UTC time or local time,
   57  * using @ref le_clk_GetUTCDateTimeString() or @ref le_clk_GetLocalDateTimeString() respectively.
   58  * These functions use the format specification defined for strftime(), with the following
   59  * additional conversion specifications:
   60  *  - %%J : milliseconds, as a 3 digit zero-padded string, e.g. "015"
   61  *  - %%K : microseconds, as a 6 digit zero-padded string, e.g. "001015"
   62  *
   63  * @todo
   64  *  - Add new formatting object to allow arbitrary time to be converted to a string, potentially with
   65  *    additional formatting options.
   66  *  - Add new objects and/or APIs to allow converting time to other formats, e.g. Linux broken down
   67  *    time in "struct tm" format.
   68  *
   69  * <HR>
   70  *
   71  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   72  *
   73  */
   74 
   75 //--------------------------------------------------------------------------------------------------
   76 /** @file le_clock.h
   77  *
   78  * Legato @ref c_clock include file.
   79  *
   80  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   81  */
   82 //--------------------------------------------------------------------------------------------------
   83 
   84 #ifndef LEGATO_CLK_INCLUDE_GUARD
   85 #define LEGATO_CLK_INCLUDE_GUARD
   86 
   87 //--------------------------------------------------------------------------------------------------
   88 /**
   89  * Represents time in seconds/microseconds.  Can be relative or absolute.
   90  */
   91 //--------------------------------------------------------------------------------------------------
   92 typedef struct
   93 {
   94     time_t sec;     ///< seconds
   95     long   usec;    ///< microseconds
   96 } le_clk_Time_t;
   97 
   98 
   99 //--------------------------------------------------------------------------------------------------
  100 /** @name String Formats
  101  *
  102  * Pre-defined formats for converting time to string format. These pre-defined formats use the
  103  * conversion specifiers from strftime().
  104  * @{
  105  */
  106 //--------------------------------------------------------------------------------------------------
  107 #define LE_CLK_STRING_FORMAT_DATE_TIME "%c"
  108     ///< Preferred date and time format for current locale, e.g. "Mon Jan 21 13:37:05 2013"
  109 #define LE_CLK_STRING_FORMAT_DATE     "%x"
  110     ///< Preferred date format for current locale, e.g. "01/21/13"
  111 #define LE_CLK_STRING_FORMAT_TIME     "%X"
  112     ///< Preferred time format for current locale, e.g. "13:37:05"
  113 // @}
  114 
  115 
  116 //--------------------------------------------------------------------------------------------------
  117 /**
  118  * Get relative time since a fixed but unspecified starting point.
  119  *
  120  * @return
  121  *      Relative time in seconds/microseconds
  122  *
  123  * @note
  124  *      Relative time includes any time that the processor is suspended.
  125  */
  126 //--------------------------------------------------------------------------------------------------
  127 le_clk_Time_t le_clk_GetRelativeTime(void);
  128 
  129 
  130 //--------------------------------------------------------------------------------------------------
  131 /**
  132  * Get absolute time since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
  133  *
  134  * @return
  135  *      Absolute time in seconds/microseconds
  136  *
  137  * @note
  138  *      Absolute time includes any time that the processor is suspended.
  139  */
  140 //--------------------------------------------------------------------------------------------------
  141 le_clk_Time_t le_clk_GetAbsoluteTime(void);
  142 
  143 
  144 //--------------------------------------------------------------------------------------------------
  145 /**
  146  * Add two time values together, and return the result.
  147  *
  148  * @return
  149  *      Sum of the two time values
  150  */
  151 //--------------------------------------------------------------------------------------------------
  152 le_clk_Time_t le_clk_Add
  153 (
  154     le_clk_Time_t timeA,
  155     le_clk_Time_t timeB
  156 );
  157 
  158 
  159 //--------------------------------------------------------------------------------------------------
  160 /**
  161  * Compare two time values.
  162  *
  163  * @return
  164  *      - TRUE if TimeA > TimeB
  165  *      - FALSE otherwise
  166  */
  167 //--------------------------------------------------------------------------------------------------
  168 bool le_clk_GreaterThan
  169 (
  170     le_clk_Time_t timeA,
  171     le_clk_Time_t timeB
  172 );
  173 
  174 
  175 //--------------------------------------------------------------------------------------------------
  176 /**
  177  * Subtract two time values, and return the result.
  178  *
  179  * @return
  180  *      Result of (timeA - timeB)
  181  */
  182 //--------------------------------------------------------------------------------------------------
  183 le_clk_Time_t le_clk_Sub
  184 (
  185     le_clk_Time_t timeA,
  186     le_clk_Time_t timeB
  187 );
  188 
  189 
  190 //--------------------------------------------------------------------------------------------------
  191 /**
  192  * Multiply the time by a scale factor, and return the result
  193  *
  194  * @return
  195  *      Time multiplied by scale factor
  196  */
  197 //--------------------------------------------------------------------------------------------------
  198 le_clk_Time_t le_clk_Multiply
  199 (
  200     le_clk_Time_t timeA,
  201     int scaleFactor
  202 );
  203 
  204 
  205 //--------------------------------------------------------------------------------------------------
  206 /**
  207  * Get the UTC date/time as a formatted string.
  208  *
  209  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  210  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  211  * will be returned in numBytesPtr.
  212  *
  213  * If the formatted date/time string does not fit in the destination buffer, the contents of
  214  * the destination buffer will be undefined and the value returned in numBytesPtr will be zero.
  215  *
  216  * @return
  217  *      - LE_OK if the formatted string was copied to destStrPtr
  218  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr
  219  *
  220  */
  221 //--------------------------------------------------------------------------------------------------
  222 le_result_t le_clk_GetUTCDateTimeString
  223 (
  224     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  225                                    ///        specifiers defined for strftime().
  226     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  227     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  228     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  229                                    ///        Parameter can be set to NULL if the number of
  230                                    ///        bytes copied is not needed.
  231 
  232 );
  233 
  234 
  235 //--------------------------------------------------------------------------------------------------
  236 /**
  237  * Get the Local date/time as a formatted string.
  238  *
  239  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  240  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  241  * will be returned in numBytesPtr.
  242  *
  243  * If the formatted date/time string does not fit in the destination buffer, then the contents of
  244  * the destination buffer will be undefined, and the value returned in numBytesPtr will be zero.
  245  *
  246  * @return
  247  *      - LE_OK if the formatted string was copied to destStrPtr.
  248  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr.
  249  *
  250  */
  251 //--------------------------------------------------------------------------------------------------
  252 le_result_t le_clk_GetLocalDateTimeString
  253 (
  254     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  255                                    ///        specifiers defined for strftime().
  256     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  257     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  258     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  259                                    ///        Parameter can be set to NULL if the number of
  260                                    ///        bytes copied is not needed.
  261 );
  262 
  263 
  264 //--------------------------------------------------------------------------------------------------
  265 /**
  266  * Generate a printable string representation of a given absolute date/time value as UTC time
  267  * (no timezone offset applied).
  268  *
  269  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  270  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  271  * will be returned in numBytesPtr.
  272  *
  273  * If the formatted date/time string does not fit in the destination buffer, the contents of
  274  * the destination buffer will be undefined and the value returned in numBytesPtr will be zero.
  275  *
  276  * @return
  277  *      - LE_OK if the formatted string was copied to destStrPtr
  278  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr
  279  *
  280  */
  281 //--------------------------------------------------------------------------------------------------
  282 le_result_t le_clk_ConvertToUTCString
  283 (
  284     le_clk_Time_t time,            ///< [IN]  date/time to convert
  285     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  286                                    ///        specifiers defined for strftime().
  287     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  288     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  289     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  290                                    ///        Parameter can be set to NULL if the number of
  291                                    ///        bytes copied is not needed.
  292 
  293 );
  294 
  295 
  296 //--------------------------------------------------------------------------------------------------
  297 /**
  298  * Generate a printable string representation of a given absolute date/time value as a local time
  299  * (with timezone offset applied).
  300  *
  301  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  302  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  303  * will be returned in numBytesPtr.
  304  *
  305  * If the formatted date/time string does not fit in the destination buffer, then the contents of
  306  * the destination buffer are undefined, and the value returned in numBytesPtr is zero.
  307  *
  308  * @return
  309  *      - LE_OK if the formatted string was copied to destStrPtr
  310  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr
  311  */
  312 //--------------------------------------------------------------------------------------------------
  313 le_result_t le_clk_ConvertToLocalTimeString
  314 (
  315     le_clk_Time_t time,            ///< [IN]  date/time to convert
  316     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  317                                    ///        specifiers defined for strftime().
  318     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  319     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  320     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  321                                    ///        Parameter can be set to NULL if the number of
  322                                    ///        bytes copied is not needed.
  323 
  324 );
  325 
  326 #endif // LEGATO_CLK_INCLUDE_GUARD
  327 
le_clk_GetLocalDateTimeString
le_result_t le_clk_GetLocalDateTimeString(const char *formatSpecStrPtr, char *destStrPtr, size_t destSize, size_t *numBytesPtr)


le_clk_GreaterThan
bool le_clk_GreaterThan(le_clk_Time_t timeA, le_clk_Time_t timeB)


le_result_t
le_result_t
Definition: le_basics.h:35


le_clk_GetUTCDateTimeString
le_result_t le_clk_GetUTCDateTimeString(const char *formatSpecStrPtr, char *destStrPtr, size_t destSize, size_t *numBytesPtr)


le_clk_Time_t::usec
long usec
microseconds 
Definition: le_clock.h:95


le_clk_Time_t::sec
time_t sec
seconds 
Definition: le_clock.h:94


le_clk_Sub
le_clk_Time_t le_clk_Sub(le_clk_Time_t timeA, le_clk_Time_t timeB)


le_clk_GetAbsoluteTime
le_clk_Time_t le_clk_GetAbsoluteTime(void)


le_clk_ConvertToUTCString
le_result_t le_clk_ConvertToUTCString(le_clk_Time_t time, const char *formatSpecStrPtr, char *destStrPtr, size_t destSize, size_t *numBytesPtr)


le_clk_Time_t
Definition: le_clock.h:92


le_clk_Multiply
le_clk_Time_t le_clk_Multiply(le_clk_Time_t timeA, int scaleFactor)


le_clk_ConvertToLocalTimeString
le_result_t le_clk_ConvertToLocalTimeString(le_clk_Time_t time, const char *formatSpecStrPtr, char *destStrPtr, size_t destSize, size_t *numBytesPtr)


le_clk_Add
le_clk_Time_t le_clk_Add(le_clk_Time_t timeA, le_clk_Time_t timeB)


le_clk_GetRelativeTime
le_clk_Time_t le_clk_GetRelativeTime(void)