le_clock.h

Go to the documentation of this file.
    1 /**
    2  * @page c_clock System Clock API
    3  *
    4  * @subpage 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. Absolute time can be set by
   24  * unsandboxed applications using le_clk_SetAbsoluteTime().
   25  *
   26  * Relative time is a monotonic time from a fixed but unspecified starting point and is provided
   27  * by @ref le_clk_GetRelativeTime(). The relative time is independent of the absolute time.  The
   28  * starting point is fixed during system boot, and cannot be changed, but is reset on each system
   29  * boot. Since the relative time is monotonic, it is guaranteed to never go backwards. With these
   30  * characteristics, the relative time is useful for measuring the time between two or more events.
   31  * For example, at event 1, relative time A is stored, and at some later event 2, relative time B
   32  * is stored.  The relative time between these two events can always be calculated as B-A, and will
   33  * always be an accurate measure of the relative time between these two events.
   34  *
   35  *
   36  * @section clk_values Operations on Time Values
   37  *
   38  * These operations can be performed on time values:
   39  *  - @ref le_clk_Add
   40  *  - @ref le_clk_GreaterThan
   41  *  - @ref le_clk_Equal
   42  *  - @ref le_clk_Sub
   43  *  - @ref le_clk_Multiply
   44  *
   45  * The functions use these assumptions:
   46  *  - All input time values are normalized (i.e., the usec value is less than 1 sec).
   47  *    All time values returned are normalized.
   48  *  - All input time values or scale factors are positive; a negative time value will not be
   49  *    returned.
   50  *  - All input time values or scale factors are expected to have reasonable values
   51  *    (i.e., they will not be so large as to cause an overflow of the time value structure).
   52  *
   53  *
   54  * @section clk_convert Converting Time to/from Other Formats
   55  *
   56  * The current absolute time can be converted to a formatted string in either UTC time or local
   57  * time, using @ref le_clk_GetUTCDateTimeString() or @ref le_clk_GetLocalDateTimeString()
   58  * respectively. These functions use the format specification defined for strftime(), with the
   59  * following 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  * The absolute time can be set with a formatted string in UTC time, using
   64  * le_clk_SetUTCDateTimeString().
   65  *
   66  * @note The additional format specifications %%J and %%K are not supported by
   67  * le_clk_SetUTCDateTimeString().
   68  *
   69  * @todo
   70  *  - Add new formatting object to allow arbitrary time to be converted to a string, potentially
   71  *    with additional formatting options.
   72  *  - Add new objects and/or APIs to allow converting time to other formats, e.g. Linux broken down
   73  *    time in "struct tm" format.
   74  *
   75  * <HR>
   76  *
   77  * Copyright (C) Sierra Wireless Inc.
   78  *
   79  */
   80 
   81 //--------------------------------------------------------------------------------------------------
   82 /** @file le_clock.h
   83  *
   84  * Legato @ref c_clock include file.
   85  *
   86  * Copyright (C) Sierra Wireless Inc.
   87  */
   88 //--------------------------------------------------------------------------------------------------
   89 
   90 #ifndef LEGATO_CLK_INCLUDE_GUARD
   91 #define LEGATO_CLK_INCLUDE_GUARD
   92 
   93 //--------------------------------------------------------------------------------------------------
   94 /**
   95  * Represents time in seconds/microseconds.  Can be relative or absolute.
   96  */
   97 //--------------------------------------------------------------------------------------------------
   98 typedef struct
   99 {
  100     time_t sec;     ///< seconds
  101     long   usec;    ///< microseconds
  102 } le_clk_Time_t;
  103 
  104 
  105 //--------------------------------------------------------------------------------------------------
  106 /** @name String Formats
  107  *
  108  * Pre-defined formats for converting time to string format. These pre-defined formats use the
  109  * conversion specifiers from strftime().
  110  * @{
  111  */
  112 //--------------------------------------------------------------------------------------------------
  113 #define LE_CLK_STRING_FORMAT_DATE_TIME "%c"
  114     ///< Preferred date and time format for current locale, e.g. "Mon Jan 21 13:37:05 2013"
  115 #define LE_CLK_STRING_FORMAT_DATE     "%x"
  116     ///< Preferred date format for current locale, e.g. "01/21/13"
  117 #define LE_CLK_STRING_FORMAT_TIME     "%X"
  118     ///< Preferred time format for current locale, e.g. "13:37:05"
  119 // @}
  120 
  121 
  122 //--------------------------------------------------------------------------------------------------
  123 /**
  124  * Get relative time since a fixed but unspecified starting point.
  125  *
  126  * @return
  127  *      Relative time in seconds/microseconds
  128  *
  129  * @note
  130  *      Relative time includes any time that the processor is suspended.
  131  */
  132 //--------------------------------------------------------------------------------------------------
  133 le_clk_Time_t le_clk_GetRelativeTime(void);
  134 
  135 
  136 //--------------------------------------------------------------------------------------------------
  137 /**
  138  * Get absolute time since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
  139  *
  140  * @return
  141  *      Absolute time in seconds/microseconds
  142  *
  143  * @note
  144  *      Absolute time includes any time that the processor is suspended.
  145  */
  146 //--------------------------------------------------------------------------------------------------
  147 le_clk_Time_t le_clk_GetAbsoluteTime(void);
  148 
  149 
  150 //--------------------------------------------------------------------------------------------------
  151 /**
  152  * Add two time values together, and return the result.
  153  *
  154  * @return
  155  *      Sum of the two time values
  156  */
  157 //--------------------------------------------------------------------------------------------------
  158 le_clk_Time_t le_clk_Add
  159 (
  160     le_clk_Time_t timeA,
  161     le_clk_Time_t timeB
  162 );
  163 
  164 
  165 //--------------------------------------------------------------------------------------------------
  166 /**
  167  * Compare two time values.
  168  *
  169  * @return
  170  *      - TRUE if TimeA > TimeB
  171  *      - FALSE otherwise
  172  */
  173 //--------------------------------------------------------------------------------------------------
  174 bool le_clk_GreaterThan
  175 (
  176     le_clk_Time_t timeA,
  177     le_clk_Time_t timeB
  178 );
  179 
  180 
  181 //--------------------------------------------------------------------------------------------------
  182 /**
  183  * Compare two time values.
  184  *
  185  * @return
  186  *      - TRUE if TimeA == TimeB
  187  *      - FALSE otherwise
  188  */
  189 //--------------------------------------------------------------------------------------------------
  190 bool le_clk_Equal
  191 (
  192     le_clk_Time_t timeA,
  193     le_clk_Time_t timeB
  194 );
  195 
  196 
  197 //--------------------------------------------------------------------------------------------------
  198 /**
  199  * Subtract two time values, and return the result.
  200  *
  201  * @return
  202  *      Result of (timeA - timeB)
  203  */
  204 //--------------------------------------------------------------------------------------------------
  205 le_clk_Time_t le_clk_Sub
  206 (
  207     le_clk_Time_t timeA,
  208     le_clk_Time_t timeB
  209 );
  210 
  211 
  212 //--------------------------------------------------------------------------------------------------
  213 /**
  214  * Multiply the time by a scale factor, and return the result
  215  *
  216  * @return
  217  *      Time multiplied by scale factor
  218  */
  219 //--------------------------------------------------------------------------------------------------
  220 le_clk_Time_t le_clk_Multiply
  221 (
  222     le_clk_Time_t timeA,
  223     int scaleFactor
  224 );
  225 
  226 
  227 //--------------------------------------------------------------------------------------------------
  228 /**
  229  * Get the UTC date/time as a formatted string.
  230  *
  231  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  232  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  233  * will be returned in numBytesPtr.
  234  *
  235  * If the formatted date/time string does not fit in the destination buffer, the contents of
  236  * the destination buffer will be undefined and the value returned in numBytesPtr will be zero.
  237  *
  238  * @return
  239  *      - LE_OK if the formatted string was copied to destStrPtr
  240  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr
  241  *
  242  */
  243 //--------------------------------------------------------------------------------------------------
  244 le_result_t le_clk_GetUTCDateTimeString
  245 (
  246     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  247                                    ///        specifiers defined for strftime().
  248     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  249     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  250     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  251                                    ///        Parameter can be set to NULL if the number of
  252                                    ///        bytes copied is not needed.
  253 
  254 );
  255 
  256 
  257 //--------------------------------------------------------------------------------------------------
  258 /**
  259  * Get the Local date/time as a formatted string.
  260  *
  261  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  262  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  263  * will be returned in numBytesPtr.
  264  *
  265  * If the formatted date/time string does not fit in the destination buffer, then the contents of
  266  * the destination buffer will be undefined, and the value returned in numBytesPtr will be zero.
  267  *
  268  * @return
  269  *      - LE_OK if the formatted string was copied to destStrPtr.
  270  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr.
  271  *
  272  */
  273 //--------------------------------------------------------------------------------------------------
  274 le_result_t le_clk_GetLocalDateTimeString
  275 (
  276     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  277                                    ///        specifiers defined for strftime().
  278     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  279     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  280     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  281                                    ///        Parameter can be set to NULL if the number of
  282                                    ///        bytes copied is not needed.
  283 );
  284 
  285 
  286 //--------------------------------------------------------------------------------------------------
  287 /**
  288  * Generate a printable string representation of a given absolute date/time value as UTC time
  289  * (no timezone offset applied).
  290  *
  291  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  292  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  293  * will be returned in numBytesPtr.
  294  *
  295  * If the formatted date/time string does not fit in the destination buffer, the contents of
  296  * the destination buffer will be undefined and the value returned in numBytesPtr will be zero.
  297  *
  298  * @return
  299  *      - LE_OK if the formatted string was copied to destStrPtr
  300  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr
  301  *
  302  */
  303 //--------------------------------------------------------------------------------------------------
  304 le_result_t le_clk_ConvertToUTCString
  305 (
  306     le_clk_Time_t time,            ///< [IN]  date/time to convert
  307     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  308                                    ///        specifiers defined for strftime().
  309     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  310     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  311     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  312                                    ///        Parameter can be set to NULL if the number of
  313                                    ///        bytes copied is not needed.
  314 
  315 );
  316 
  317 
  318 //--------------------------------------------------------------------------------------------------
  319 /**
  320  * Generate a printable string representation of a given absolute date/time value as a local time
  321  * (with timezone offset applied).
  322  *
  323  * The formatted date/time string, including NULL-terminator, will be copied to the destination
  324  * buffer, provided it fits, and the number of bytes copied (not including the NULL-terminator)
  325  * will be returned in numBytesPtr.
  326  *
  327  * If the formatted date/time string does not fit in the destination buffer, then the contents of
  328  * the destination buffer are undefined, and the value returned in numBytesPtr is zero.
  329  *
  330  * @return
  331  *      - LE_OK if the formatted string was copied to destStrPtr
  332  *      - LE_OVERFLOW if the formatted string would not fit in destStrPtr
  333  */
  334 //--------------------------------------------------------------------------------------------------
  335 le_result_t le_clk_ConvertToLocalTimeString
  336 (
  337     le_clk_Time_t time,            ///< [IN]  date/time to convert
  338     const char* formatSpecStrPtr,  ///< [IN]  Format specifier string, using conversion
  339                                    ///        specifiers defined for strftime().
  340     char*   destStrPtr,            ///< [OUT] Destination for the formatted date/time string
  341     size_t  destSize,              ///< [IN]  Size of the destination buffer in bytes.
  342     size_t* numBytesPtr            ///< [OUT] Number of bytes copied, not including NULL-terminator.
  343                                    ///        Parameter can be set to NULL if the number of
  344                                    ///        bytes copied is not needed.
  345 
  346 );
  347 
  348 
  349 //--------------------------------------------------------------------------------------------------
  350 /**
  351  * Set absolute time since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
  352  *
  353  * @note Only unsandboxed application can set the date/time.
  354  *
  355  * @return
  356  *      - LE_OK if the function succeeded
  357  *      - LE_BAD_PARAMETER if an invalid parameter is provided
  358  *      - LE_NOT_PERMITTED if the operation is not permitted
  359  *      - LE_FAULT if an error occurred
  360  */
  361 //--------------------------------------------------------------------------------------------------
  362 le_result_t le_clk_SetAbsoluteTime
  363 (
  364     le_clk_Time_t absoluteTime  ///< [IN] Absolute time in seconds/microseconds
  365 );
  366 
  367 
  368 //--------------------------------------------------------------------------------------------------
  369 /**
  370  * Generate an absolute date/time value as UTC time representation of a given printable string
  371  * representation (no timezone offset applied).
  372  *
  373  * @return
  374  *      - LE_OK if the conversion was successful
  375  *      - LE_BAD_PARAMETER if an invalid parameter is provided
  376  *      - LE_FAULT if an error occurred
  377  */
  378 //--------------------------------------------------------------------------------------------------
  379 LE_FULL_API le_result_t le_clk_ConvertToTime
  380 (
  381     const char*    formatSpecStrPtr,    ///< [IN]  Format specifier string, using conversion
  382                                         ///        specifiers defined for strptime().
  383     const char*    srcStrPtr,           ///< [IN]  Formatted date/time string.
  384     le_clk_Time_t* timePtr              ///< [OUT] Converted date/time.
  385 );
  386 
  387 
  388 //--------------------------------------------------------------------------------------------------
  389 /**
  390  * Set the UTC date/time as a formatted string.
  391  *
  392  * @note Only unsandboxed application can set the date/time.
  393  *
  394  * @return
  395  *      - LE_OK if the time is correctly set
  396  *      - LE_BAD_PARAMETER if an invalid parameter is provided
  397  *      - LE_NOT_PERMITTED if the operation is not permitted
  398  *      - LE_FAULT if an error occurred
  399  */
  400 //--------------------------------------------------------------------------------------------------
  401 LE_FULL_API le_result_t le_clk_SetUTCDateTimeString
  402 (
  403     const char* formatSpecStrPtr,   ///< [IN] Format specifier string, using conversion
  404                                     ///       specifiers defined for strptime().
  405     const char* srcStrPtr           ///< [IN] Formatted date/time string.
  406 );
  407 
  408 //--------------------------------------------------------------------------------------------------
  409 /**
  410  * Set the timezone information
  411  *
  412  * @return
  413  *      - LE_OK if the time is correctly set
  414  *      - LE_FAULT if an error occurred
  415  *      - LE_UNSUPPORTED if the function is not supported
  416  */
  417 //--------------------------------------------------------------------------------------------------
  418 le_result_t le_clk_SetTimezoneFile
  419 (
  420     const int32_t timezoneOffsetSeconds, ///< [IN] Timezone offset in seconds
  421     const uint8_t dstOffsetHours         ///< [IN] Daylight savings adjustment in hours
  422 );
  423 
  424 #endif // LEGATO_CLK_INCLUDE_GUARD
le_clk_GetLocalDateTimeString
le_result_t le_clk_GetLocalDateTimeString(const char *formatSpecStrPtr, char *destStrPtr, size_t destSize, size_t *numBytesPtr)


le_clk_ConvertToTime
LE_FULL_API le_result_t le_clk_ConvertToTime(const char *formatSpecStrPtr, const char *srcStrPtr, le_clk_Time_t *timePtr)


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:46


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_SetAbsoluteTime
le_result_t le_clk_SetAbsoluteTime(le_clk_Time_t absoluteTime)


le_clk_Time_t
Definition: le_clock.h:98


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_SetUTCDateTimeString
LE_FULL_API le_result_t le_clk_SetUTCDateTimeString(const char *formatSpecStrPtr, const char *srcStrPtr)


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_Multiply
le_clk_Time_t le_clk_Multiply(le_clk_Time_t timeA, int scaleFactor)


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


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_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40


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)


le_clk_SetTimezoneFile
le_result_t le_clk_SetTimezoneFile(const int32_t timezoneOffsetSeconds, const uint8_t dstOffsetHours)


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