RTI Connext DDS Micro  Version 2.4.6
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
osapi_time.h
Go to the documentation of this file.
1 /*
2  * FILE: osapi_time.h - Definition of Time API
3  *
4  * Copyright 2005-2015 Real-Time Innovations, Inc.
5  *
6  * No duplications, whole or partial, manual or electronic, may be made
7  * without express written permission. Any such copies, or
8  * revisions thereof, must display this notice unaltered.
9  * This code contains trade secrets of Real-Time Innovations, Inc.
10  *
11  * Modification History
12  * --------------------
13  * 29may2015,tk MICRO-1329/PR#15063 Moved implementation comments from
14  * to Time.c. API documentation is kept here.
15  * 16mar2015,tk MICRO-1084 Changed comment for to/from_ntp_time to state
16  * resolution is at least 1ns.
17  * 20mar2013,tk Updated
18  * 06dec2005,rh Created
19  */
20 /*e \file
21  * \brief Time API definition
22  *
23  * \details
24  * This file implements function to convert between the NtpTime format and
25  * other formats.
26  */
27 #ifndef osapi_time_h
28 #define osapi_time_h
29 
30 #include "osapi/osapi_dll.h"
31 #ifndef osapi_types_h
32 #include "osapi/osapi_types.h"
33 #endif
34 
35 #ifdef __cplusplus
36 extern "C"
37 {
38 #endif
39 
40 /*e \defgroup OSAPITimeClass OSAPI Time
41  * \ingroup OSAPIModule
42  */
43 
44 /*e \ingroup OSAPITimeClass
45  *
46  * \brief NtpTime API.
47  */
48 /* ================================================================= */
49 /* Definition: Time */
50 /* ----------------------------------------------------------------- */
51 
52 /*e \ingroup OSAPITimeClass
53  *
54  * @brief NTP Time representation.
55  *
56  * Expresses time in NTP format. The second field is simply an integer
57  * expressing seconds. The fraction field expresses 1/2^32 of a second.
58  * We strongly urge customers to use our provided macros to convert this
59  * format to and from human readable form.
60  *
61  * \b Example:
62  *
63  * The following is a simple example on how to prepare a struct OSAPI_NtpTime
64  * structure to be 1.5 seconds.
65  *
66  * \verbatim
67  * struct OSAPI_NtpTime ntpTime;
68  *
69  * OSAPI_NtpTime_from_millisec(ntpTime, 1, 500);
70  * \endverbatim
71  */
72 typedef struct OSAPI_NtpTime
73 {
74  /* e Seconds.* */
75  RTI_INT32 sec;
76  /* e fraction of a second in 1/2^32 form. */
77  RTI_UINT32 frac;
79 
80 /*e \ingroup OSAPITimeClass
81  * The maximum number of seconds that can be represented using NTP time.
82  */
83 #define OSAPI_NTP_TIME_SEC_MAX ((RTI_INT32)0x7fffffff)
84 
85 /*e \ingroup OSAPITimeClass
86  * The largest possible value of the fraction field in NTP time.
87  */
88 #define OSAPI_NTP_TIME_FRAC_MAX ((RTI_UINT32)0xffffffff)
89 
90 
91 /*e \ingroup OSAPITimeClass
92  *
93  * @brief Macro to convert from seconds and milliseconds to struct OSAPI_NtpTime format.
94  *
95  * \details
96  * This macro assumes that msec < 1000. It is the caller's responsibility
97  * to ensure this.
98  *
99  * @param time Contains the answer.
100  * @param s Seconds to convert.
101  * @param msec Milliseconds to convert.
102  *
103  * @see struct OSAPI_NtpTime OSAPI_NtpTime_to_millisec
104  */
105 OSAPIDllExport void
106 OSAPI_NtpTime_from_millisec(struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 msec);
107 
108 /*e \ingroup OSAPITimeClass
109  *
110  * @brief Macro to convert from struct OSAPI_NtpTime to seconds and milliseconds.
111  *
112  * \details
113  * This macro does not check for overflow, so for a near-infinite time value,
114  * the conversion result may end up being negative. It is the responsibility
115  * of the user to avoid passing these large time values.
116  *
117  * @param s Holds the seconds answer.
118  * @param msec Holds the millisecond answer.
119  * @param time The time to convert to second(s) and millisecond(s).
120  *
121  * @see struct OSAPI_NtpTime OSAPI_NtpTime_from_millisec
122  */
123 OSAPIDllExport void
124 OSAPI_NtpTime_to_millisec(RTI_INT32 *const s, RTI_UINT32 *const msec,
125  const struct OSAPI_NtpTime *const time);
126 
127 /*e \ingroup OSAPITimeClass
128  *
129  * @brief Macro to convert from seconds and microseconds to struct OSAPI_NtpTime format.
130  *
131  * @details
132  * This macro does not check for overflow, so for a near-infinite time value,
133  * the conversion result may end up being negative. It is the caller's
134  * responsibility to avoid passing these large time values.
135  *
136  * @param time Contains the answer.
137  * @param s Seconds to covert.
138  * @param usec Microseconds to convert.
139  *
140  * @see struct OSAPI_NtpTime OSAPI_NtpTime_to_millisec
141  */
142 OSAPIDllExport void
143 OSAPI_NtpTime_from_microsec(struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 usec);
144 
145 /*e \ingroup OSAPITimeClass
146  *
147  * @brief Macro to convert from struct OSAPI_NtpTime to seconds and microseconds.
148  *
149  * @param s Holds the second portion.
150  * @param usec Holds the microsecond fraction.
151  * @param time The time to convert to second(s) and microsecond(s)
152  *
153  * This macro does not check for overflow, so for a near-infinite time value,
154  * the conversion result may end up being negative. It is the caller's
155  * responsibility to avoid passing these large time values.
156  *
157  * @see struct OSAPI_NtpTime OSAPI_NtpTime_from_millisec
158  */
159 OSAPIDllExport void
160 OSAPI_NtpTime_to_microsec(RTI_INT32 *const s, RTI_UINT32 *const usec,
161  const struct OSAPI_NtpTime *const time);
162 
163 /*e \ingroup OSAPITimeClass
164  *
165  * @brief Macro to convert from seconds and nanoseconds to struct OSAPI_NtpTime format.
166  *
167  * @details
168  * This macro assumes that nsec < 1000000000. It is the caller's responsibility
169  * to ensure this. The accuracy of this conversion over the whole range of
170  * nanosecond values is at least 1 nanosecond.
171  *
172  * @param time Holds the answer.
173  * @param s Seconds to convert.
174  * @param nsec Nanoseconds to convert.
175  *
176  * @see struct OSAPI_NtpTime OSAPI_NtpTime_to_nanosec
177  */
178 OSAPIDllExport void
179 OSAPI_NtpTime_from_nanosec(struct OSAPI_NtpTime *const time, RTI_INT32 s, RTI_UINT32 nsec);
180 
181 
182 /*e \ingroup OSAPITimeClass
183  *
184  * @brief Macro to convert from struct OSAPI_NtpTime to seconds and nanoseconds.
185  *
186  * @details
187  * The accuracy of this conversion over the whole range of
188  * struct OSAPI_NtpTime values is at least 1 nanosecond.
189  *
190  * @param s Holds the second portion.
191  * @param nsec Holds the nanosecond portion.
192  * @param time Time to convert to second(s) and nanosecond(s).
193  *
194  * @see struct OSAPI_NtpTime OSAPI_NtpTime_from_nanosec
195  */
196 OSAPIDllExport void
197 OSAPI_NtpTime_to_nanosec(RTI_INT32 *const s, RTI_UINT32 *const nsec,
198  const struct OSAPI_NtpTime *const time);
199 
200 /*e \ingroup OSAPITimeClass
201  *
202  * A NULL struct OSAPI_NtpTime pointer is considered infinity. This is consistent
203  * with the concept of infinite time on UNIX systems.
204  *
205  * In addition, if the seconds field equals OSAPI_NTP_TIME_SEC_MAX, the
206  * time value is also considered infinite.
207  *
208  * @param time Pointer to RTITime.
209  *
210  * @return RTI_TRUE if time is infinite, RTI_FALSE otherwise.
211 */
212 OSAPIDllExport RTI_BOOL
213 OSAPI_NtpTime_is_infinite(const struct OSAPI_NtpTime *const time);
214 
215 /*e \ingroup OSAPITimeClass
216  *
217  * @brief answer = t1 - t2.
218  *
219  * @param answer struct OSAPI_NtpTime
220  * @param t1 struct OSAPI_NtpTime`
221  * @param t2 struct OSAPI_NtpTime
222  */
223 OSAPIDllExport void
224 OSAPI_NtpTime_subtract(struct OSAPI_NtpTime *const answer,
225  const struct OSAPI_NtpTime *const t1,
226  const struct OSAPI_NtpTime *const t2);
227 
228 /*e \ingroup OSAPITimeClass
229  *
230  * @brief answer += time.
231  *
232  * This macro does not check for overflow.
233  *
234  * @param answer struct OSAPI_NtpTime
235  * @param time struct OSAPI_NtpTime
236  */
237 #define OSAPI_NtpTime_increment(answer, time) \
238 { \
239  register RTI_UINT32 currentFrac = (answer)->frac; \
240  (answer)->sec += (time)->sec; \
241  (answer)->frac += (time)->frac; \
242  if (((answer)->frac < (time)->frac) || ((answer)->frac < currentFrac)) { \
243  (answer)->sec++; \
244  } \
245 }
246 
247 /*e \ingroup OSAPITimeClass
248  *
249  * @brief Decrement one struct OSAPI_NtpTime value by another struct OSAPI_NtpTime value.
250  *
251  * Precondition:
252  * Postcondition: answer -= time.
253  *
254  * @param answer struct OSAPI_NtpTime
255  * @param time struct OSAPI_NtpTime
256  *
257  */
258 #define OSAPI_NtpTime_decrement(answer, time) \
259 { \
260  register RTI_UINT32 currentFrac = (answer)->frac; \
261  (answer)->sec -= (time)->sec; \
262  (answer)->frac -= (time)->frac; \
263  if (((answer)->frac > currentFrac)) { (answer)->sec--; } \
264 }
265 
266 /*e \ingroup OSAPITimeClass
267  *
268  * @brief Zero time.
269  *
270  * This global variable is for convenience. It allows you to see if a
271  * RTITime variable is negative or positive by comparing against this.
272  *
273  * @see RtiTimeCompare
274  */
275 #define OSAPI_NTP_TIME_ZERO {0,0}
276 
277 /*e \ingroup OSAPITimeClass
278  *
279  * Represents the maximum timevalue that can be represented using the
280  * NTP time format. For all practical purposes, it can be considered
281  * equivalent to infinity.
282  */
283 #define OSAPI_NTP_TIME_MAX {OSAPI_NTP_TIME_SEC_MAX,OSAPI_NTP_TIME_FRAC_MAX}
284 
285 /*e \ingroup OSAPITimeClass
286  * The number of nanoseconds per second. 1e9.
287  * @see RtiTimePack RtiTimeUnpack
288  */
289 #define OSAPI_NTP_TIME_NSEC_PER_SEC (1000000000)
290 
291 /*e \ingroup OSAPITimeClass
292  * The number of microseconds per second. 1e6.
293  * @see RtiTimePack RtiTimeUnpack
294  */
295 #define OSAPI_NTP_TIME_USEC_PER_SEC (1000000)
296 
297 /*e \ingroup OSAPITimeClass
298  * The number of milliseconds per second. 1e3.
299  * @see RtiTimePack RtiTimeUnpack
300  */
301 #define OSAPI_NTP_TIME_MSEC_PER_SEC (1000)
302 
303 /*e \ingroup OSAPITimeClass
304  * The number of microseconds per milliseconds. 1e3.
305  * @see RtiTimePack RtiTimeUnpack
306  */
307 #define OSAPI_NTP_TIME_NSEC_PER_USEC (1000)
308 
309 /*e \ingroup OSAPITimeClass
310  * The number of microseconds per milliseconds. 1e3.
311  * @see RtiTimePack RtiTimeUnpack
312  */
313 #define OSAPI_NTP_TIME_USEC_PER_MSEC (1000)
314 
315 /*e \ingroup OSAPITimeClass
316  * The number of seconds per second. 1.
317  * @see RtiTimePack RtiTimeUnpack
318  */
319 #define OSAPI_NTP_TIME_SEC_PER_SEC (1)
320 
321 /*e \ingroup OSAPITimeClass
322  * The number of nano seconds per milli second. 1e6.
323  * @see RtiTimePack RtiTimeUnpack
324  */
325 #define OSAPI_NTP_TIME_NSEC_PER_MSEC (1000000)
326 
327 #ifdef __cplusplus
328 } /* extern "C" */
329 #endif
330 
331 #endif /* osapi_time_h */

RTI Connext DDS Micro Version 2.4.6 Copyright © Mon Jan 25 2016 Real-Time Innovations, Inc