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