1 /******************************************************************************
2  *
3  *  Copyright 2014 The Android Open Source Project
4  *  Copyright 2002 - 2004 Open Interface North America, Inc. All rights
5  *                        reserved.
6  *
7  *  Licensed under the Apache License, Version 2.0 (the "License");
8  *  you may not use this file except in compliance with the License.
9  *  You may obtain a copy of the License at:
10  *
11  *  http://www.apache.org/licenses/LICENSE-2.0
12  *
13  *  Unless required by applicable law or agreed to in writing, software
14  *  distributed under the License is distributed on an "AS IS" BASIS,
15  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  *  See the License for the specific language governing permissions and
17  *  limitations under the License.
18  *
19  ******************************************************************************/
20 #ifndef _OI_TIME_H
21 #define _OI_TIME_H
22 /** @file
23  *
24  * This file provides time type definitions and time-related functions.
25  *
26  * The stack maintains a 64-bit real-time millisecond clock. The choice of
27  * milliseconds is for convenience, not accuracy.
28  *
29  * Timeouts are specified as tenths of seconds in a 32-bit value. Timeout values
30  * specified by the Bluetooth specification are usually muliple seconds, so
31  * accuracy to a tenth of a second is more than adequate.
32  *
33  * This file also contains macros to convert between seconds and the Link
34  * Manager's 1.28-second units.
35  *
36  */
37 
38 /*******************************************************************************
39   $Revision: #1 $
40  ******************************************************************************/
41 
42 #include "oi_stddefs.h"
43 
44 /** \addtogroup Misc Miscellaneous APIs */
45 /**@{*/
46 
47 #ifdef __cplusplus
48 extern "C" {
49 #endif
50 
51 /**
52  * Within the core stack, timeouts are specified in intervals of tenths of
53  * seconds.
54  */
55 
56 typedef uint16_t OI_INTERVAL;
57 #define OI_INTERVALS_PER_SECOND 10
58 #define MSECS_PER_OI_INTERVAL (1000 / OI_INTERVALS_PER_SECOND)
59 
60 /** maximum interval (54 min 36.7 sec) */
61 #define OI_MAX_INTERVAL 0x7fff
62 
63 /**
64  * Macro to convert seconds to OI_INTERVAL time units
65  */
66 
67 #define OI_SECONDS(n) ((OI_INTERVAL)((n)*OI_INTERVALS_PER_SECOND))
68 
69 /**
70  * Macro to convert milliseconds to OI_INTERVAL time units (Rounded Up)
71  */
72 
73 #define OI_MSECONDS(n) \
74   ((OI_INTERVAL)(((n) + MSECS_PER_OI_INTERVAL - 1) / MSECS_PER_OI_INTERVAL))
75 
76 /**
77  * Macro to convert minutes to OI_INTERVAL time units
78  */
79 
80 #define OI_MINUTES(n) ((OI_INTERVAL)((n)*OI_SECONDS(60)))
81 
82 /** Convert an OI_INTERVAL to milliseconds. */
83 #define OI_INTERVAL_TO_MILLISECONDS(i) ((i)*MSECS_PER_OI_INTERVAL)
84 
85 /**
86  * The stack depends on relative not absolute time. Any mapping between the
87  * stack's real-time clock and absolute time and date is
88  * implementation-dependent.
89  */
90 
91 typedef struct {
92   int32_t seconds;
93   int16_t mseconds;
94 } OI_TIME;
95 
96 /**
97  * Convert an OI_TIME to milliseconds.
98  *
99  * @param t  the time to convert
100  *
101  * @return the time in milliseconds
102  */
103 uint32_t OI_Time_ToMS(OI_TIME* t);
104 
105 /**
106  * This function compares two time values.
107  *
108  * @param T1 first time to compare.
109  *
110  * @param T2 second time to compare.
111  *
112  * @return
113  @verbatim
114      -1 if t1 < t2
115       0 if t1 = t2
116      +1 if t1 > t2
117  @endverbatim
118  */
119 
120 int16_t OI_Time_Compare(OI_TIME* T1, OI_TIME* T2);
121 
122 /**
123  * This function returns the interval between two times to a granularity of 0.1
124  * seconds.
125  *
126  * @param Sooner a time value more recent that Later
127  *
128  * @param Later a time value later than Sooner
129  *
130  * @note The result is an OI_INTERVAL value so this function only works for time
131  * intervals that are less than about 71 minutes.
132  *
133  * @return the time interval between the two times = (Later - Sooner)
134  */
135 
136 OI_INTERVAL OI_Time_Interval(OI_TIME* Sooner, OI_TIME* Later);
137 
138 /**
139  * This function returns the interval between two times to a granularity of
140  * milliseconds.
141  *
142  * @param Sooner a time value more recent that Later
143  *
144  * @param Later a time value later than Sooner
145  *
146  * @note The result is an uint32_t value so this function only works for time
147  * intervals that are less than about 50 days.
148  *
149  * @return the time interval between the two times = (Later - Sooner)
150  */
151 
152 uint32_t OI_Time_IntervalMsecs(OI_TIME* Sooner, OI_TIME* Later);
153 
154 /**
155  * This function answers this question:
156  *   "Have we reached or gone past the target time?"
157  *
158  * @param pTargetTime   target time
159  *
160  * @return  true means time now is at or past target time
161  *          false means target time is still some time in the future
162  */
163 
164 OI_BOOL OI_Time_NowReachedTime(OI_TIME* pTargetTime);
165 
166 /**
167  *  Convert seconds to the Link Manager 1.28-second units
168  *  Approximate by using 1.25 conversion factor.
169  */
170 
171 #define OI_SECONDS_TO_LM_TIME_UNITS(lmUnits) \
172   ((lmUnits) < 4 ? (lmUnits) : (lmUnits) - ((lmUnits) >> 2))
173 
174 /**
175  *  Convert Link Manager 1.28-second units to seconds.
176  *  Approximate by using 1.25 conversion factor.
177  */
178 
179 #define OI_LM_TIME_UNITS_TO_SECONDS(lmUnits) ((lmUnits) + ((lmUnits) >> 2))
180 
181 #ifdef __cplusplus
182 }
183 #endif
184 
185 /**@}*/
186 
187 /* Include for OI_Time_Now() prototype
188  * Must be included at end to obtain OI_TIME typedef
189  */
190 #include "oi_osinterface.h"
191 
192 /*****************************************************************************/
193 #endif /* _OI_TIME_H */
194