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