le_clock.h

    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_Equal
   44  *  - @ref le_clk_Sub
   45  *  - @ref le_clk_Multiply
   46  *
   47  * The functions use these assumptions:
   48  *  - All input time values are normalized (i.e., the usec value is less than 1 sec). All time values
   49  *    returned are normalized.
   50  *  - All input time values or scale factors are positive; a negative time value will not be returned.
   51  *  - All input time values or scale factors are expected to have reasonable values (i.e., they will not
   52  *    be so large as to cause an overflow of the time value structure).
   53  *
   54  *
   55  * @section clk_convert Converting Time to Other Formats
   56  *
   57  * The current absolute time can be converted to a formatted string in either UTC time or local time,
   58  * using @ref le_clk_GetUTCDateTimeString() or @ref le_clk_GetLocalDateTimeString() respectively.
   59  * These functions use the format specification defined for strftime(), with the following
   60  * additional conversion specifications:
   61  *  - %%J : milliseconds, as a 3 digit zero-padded string, e.g. "015"
   62  *  - %%K : microseconds, as a 6 digit zero-padded string, e.g. "001015"
   63  *
   64  * @todo
   65  *  - Add new formatting object to allow arbitrary time to be converted to a string, potentially with
   66  *    additional formatting options.
   67  *  - Add new objects and/or APIs to allow converting time to other formats, e.g. Linux broken down
   68  *    time in "struct tm" format.
   69  *
   70  * <HR>
   71  *
   72  * Copyright (C) Sierra Wireless Inc.
   73  *
   74  */
   75 
   76 //--------------------------------------------------------------------------------------------------
   77 /** @file le_clock.h
   78  *
   79  * Legato @ref c_clock include file.
   80  *
   81  * Copyright (C) Sierra Wireless Inc.
   82  */
   83 //--------------------------------------------------------------------------------------------------
   84 
   85 #ifndef LEGATO_CLK_INCLUDE_GUARD
   86 #define LEGATO_CLK_INCLUDE_GUARD
   87 
   88 //--------------------------------------------------------------------------------------------------
   89 /**
   90  * Represents time in seconds/microseconds.  Can be relative or absolute.
   91  */
   92 //--------------------------------------------------------------------------------------------------
   93 typedef struct
   94 {
   95     time_t sec;     ///< seconds
   96     long   usec;    ///< microseconds
   97 } le_clk_Time_t;
   98 
   99 
  100 //--------------------------------------------------------------------------------------------------
  101 /** @name String Formats
  102  *
  103  * Pre-defined formats for converting time to string format. These pre-defined formats use the
  104  * conversion specifiers from strftime().
  105  * @{
  106  */
  107 //--------------------------------------------------------------------------------------------------
  108 #define LE_CLK_STRING_FORMAT_DATE_TIME "%c"
  109     ///< Preferred date and time format for current locale, e.g. "Mon Jan 21 13:37:05 2013"
  110 #define LE_CLK_STRING_FORMAT_DATE     "%x"
  111     ///< Preferred date format for current locale, e.g. "01/21/13"
  112 #define LE_CLK_STRING_FORMAT_TIME     "%X"
  113     ///< Preferred time format for current locale, e.g. "13:37:05"
  114 // @}
  115 
  116 
  117 //--------------------------------------------------------------------------------------------------
  118 /**
  119  * Get relative time since a fixed but unspecified starting point.
  120  *
  121  * @return
  122  *      Relative time in seconds/microseconds
  123  *
  124  * @note
  125  *      Relative time includes any time that the processor is suspended.
  126  */
  127 //--------------------------------------------------------------------------------------------------
  128 le_clk_Time_t le_clk_GetRelativeTime(void);
  129 
  130 
  131 //--------------------------------------------------------------------------------------------------
  132 /**
  133  * Get absolute time since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
  134  *
  135  * @return
  136  *      Absolute time in seconds/microseconds
  137  *
  138  * @note
  139  *      Absolute time includes any time that the processor is suspended.
  140  */
  141 //--------------------------------------------------------------------------------------------------
  142 le_clk_Time_t le_clk_GetAbsoluteTime(void);
  143 
  144 
  145 //--------------------------------------------------------------------------------------------------
  146 /**
  147  * Add two time values together, and return the result.
  148  *
  149  * @return
  150  *      Sum of the two time values
  151  */
  152 //--------------------------------------------------------------------------------------------------
  153 le_clk_Time_t le_clk_Add
  154 (
  155     le_clk_Time_t timeA,
  156     le_clk_Time_t timeB
  157 );
  158 
  159 
  160 //--------------------------------------------------------------------------------------------------
  161 /**
  162  * Compare two time values.
  163  *
  164  * @return
  165  *      - TRUE if TimeA > TimeB
  166  *      - FALSE otherwise
  167  */
  168 //--------------------------------------------------------------------------------------------------
  169 bool le_clk_GreaterThan
  170 (
  171     le_clk_Time_t timeA,
  172     le_clk_Time_t timeB
  173 );
  174 
  175 
  176 //--------------------------------------------------------------------------------------------------
  177 /**
  178  * Compare two time values.
  179  *
  180  * @return
  181  *      - TRUE if TimeA == TimeB
  182  *      - FALSE otherwise
  183  */
  184 //--------------------------------------------------------------------------------------------------
  185 bool le_clk_Equal
  186 (
  187     le_clk_Time_t timeA,
  188     le_clk_Time_t timeB
  189 );
  190 
  191 
  192 //--------------------------------------------------------------------------------------------------
  193 /**
  194  * Subtract two time values, and return the result.
  195  *
  196  * @return
  197  *      Result of (timeA - timeB)
  198  */
  199 //--------------------------------------------------------------------------------------------------
  200 le_clk_Time_t le_clk_Sub
  201 (
  202     le_clk_Time_t timeA,
  203     le_clk_Time_t timeB
  204 );
  205 
  206 
  207 //--------------------------------------------------------------------------------------------------
  208 /**
  209  * Multiply the time by a scale factor, and return the result
  210  *
  211  * @return
  212  *      Time multiplied by scale factor
  213  */
  214 //--------------------------------------------------------------------------------------------------
  215 le_clk_Time_t le_clk_Multiply
  216 (
  217     le_clk_Time_t timeA,
  218     int scaleFactor
  219 );
  220 
  221 
  222 //--------------------------------------------------------------------------------------------------
  223 /**
  224  * Get the UTC date/time as a formatted string.
  225  *
  226  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  227  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  228  * will be returned in numBytesPtr.
  229  *
  230  * If the formatted date/time string does not fit in the destination buffer, the contents of
  231  * the destination buffer will be undefined and the value returned in numBytesPtr will be zero.
  232  *
  233  * @return
  234  *      - LE_OK if the formatted string was copied to destStrPtr
  235  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr
  236  *
  237  */
  238 //--------------------------------------------------------------------------------------------------
  239 le_result_t le_clk_GetUTCDateTimeString
  240 (
  241     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  242                                    ///        specifiers defined for strftime().
  243     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  244     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  245     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  246                                    ///        Parameter can be set to NULL if the number of
  247                                    ///        bytes copied is not needed.
  248 
  249 );
  250 
  251 
  252 //--------------------------------------------------------------------------------------------------
  253 /**
  254  * Get the Local date/time as a formatted string.
  255  *
  256  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  257  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  258  * will be returned in numBytesPtr.
  259  *
  260  * If the formatted date/time string does not fit in the destination buffer, then the contents of
  261  * the destination buffer will be undefined, and the value returned in numBytesPtr will be zero.
  262  *
  263  * @return
  264  *      - LE_OK if the formatted string was copied to destStrPtr.
  265  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr.
  266  *
  267  */
  268 //--------------------------------------------------------------------------------------------------
  269 le_result_t le_clk_GetLocalDateTimeString
  270 (
  271     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  272                                    ///        specifiers defined for strftime().
  273     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  274     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  275     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  276                                    ///        Parameter can be set to NULL if the number of
  277                                    ///        bytes copied is not needed.
  278 );
  279 
  280 
  281 //--------------------------------------------------------------------------------------------------
  282 /**
  283  * Generate a printable string representation of a given absolute date/time value as UTC time
  284  * (no timezone offset applied).
  285  *
  286  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  287  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  288  * will be returned in numBytesPtr.
  289  *
  290  * If the formatted date/time string does not fit in the destination buffer, the contents of
  291  * the destination buffer will be undefined and the value returned in numBytesPtr will be zero.
  292  *
  293  * @return
  294  *      - LE_OK if the formatted string was copied to destStrPtr
  295  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr
  296  *
  297  */
  298 //--------------------------------------------------------------------------------------------------
  299 le_result_t le_clk_ConvertToUTCString
  300 (
  301     le_clk_Time_t time,            ///< [IN]  date/time to convert
  302     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  303                                    ///        specifiers defined for strftime().
  304     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  305     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  306     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  307                                    ///        Parameter can be set to NULL if the number of
  308                                    ///        bytes copied is not needed.
  309 
  310 );
  311 
  312 
  313 //--------------------------------------------------------------------------------------------------
  314 /**
  315  * Generate a printable string representation of a given absolute date/time value as a local time
  316  * (with timezone offset applied).
  317  *
  318  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  319  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  320  * will be returned in numBytesPtr.
  321  *
  322  * If the formatted date/time string does not fit in the destination buffer, then the contents of
  323  * the destination buffer are undefined, and the value returned in numBytesPtr is zero.
  324  *
  325  * @return
  326  *      - LE_OK if the formatted string was copied to destStrPtr
  327  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr
  328  */
  329 //--------------------------------------------------------------------------------------------------
  330 le_result_t le_clk_ConvertToLocalTimeString
  331 (
  332     le_clk_Time_t time,            ///< [IN]  date/time to convert
  333     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  334                                    ///        specifiers defined for strftime().
  335     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  336     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  337     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  338                                    ///        Parameter can be set to NULL if the number of
  339                                    ///        bytes copied is not needed.
  340 
  341 );
  342 
  343 #endif // LEGATO_CLK_INCLUDE_GUARD
  344 
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_Equal
bool le_clk_Equal(le_clk_Time_t timeA, le_clk_Time_t timeB)
le_clk_Time_t::usec
long usec
microseconds 
Definition: le_clock.h:96
le_clk_Time_t::sec
time_t sec
seconds 
Definition: le_clock.h:95
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:93
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)