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
48extern "C" {
49#endif
50
51
52
53/**
54 * Within the core stack timeouts are specified in intervals of tenths of seconds
55 */
56
57typedef 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
91typedef 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 */
103OI_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
121OI_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
138OI_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
156OI_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
170OI_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