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. 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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 #endif // LEGATO_CLK_INCLUDE_GUARD
le_result_t le_clk_GetLocalDateTimeString(const char *formatSpecStrPtr, char *destStrPtr, size_t destSize, size_t *numBytesPtr)
bool le_clk_GreaterThan(le_clk_Time_t timeA, le_clk_Time_t timeB)
le_result_t
Definition: le_basics.h:35
le_result_t le_clk_GetUTCDateTimeString(const char *formatSpecStrPtr, char *destStrPtr, size_t destSize, size_t *numBytesPtr)
le_result_t le_clk_SetUTCDateTimeString(const char *formatSpecStrPtr, const char *srcStrPtr)
bool le_clk_Equal(le_clk_Time_t timeA, le_clk_Time_t timeB)
le_result_t le_clk_SetAbsoluteTime(le_clk_Time_t absoluteTime)
long usec
microseconds
Definition: le_clock.h:101
time_t sec
seconds
Definition: le_clock.h:100
le_clk_Time_t le_clk_Sub(le_clk_Time_t timeA, le_clk_Time_t timeB)
le_clk_Time_t le_clk_GetAbsoluteTime(void)
le_result_t le_clk_ConvertToUTCString(le_clk_Time_t time, const char *formatSpecStrPtr, char *destStrPtr, size_t destSize, size_t *numBytesPtr)
Definition: le_clock.h:98
le_clk_Time_t le_clk_Multiply(le_clk_Time_t timeA, int scaleFactor)
le_result_t le_clk_ConvertToLocalTimeString(le_clk_Time_t time, const char *formatSpecStrPtr, char *destStrPtr, size_t destSize, size_t *numBytesPtr)
le_clk_Time_t le_clk_Add(le_clk_Time_t timeA, le_clk_Time_t timeB)
le_result_t le_clk_ConvertToTime(const char *formatSpecStrPtr, const char *srcStrPtr, le_clk_Time_t *timePtr)
le_clk_Time_t le_clk_GetRelativeTime(void)