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) ((OI_INTERVAL)(((n) + MSECS_PER_OI_INTERVAL - 1) / MSECS_PER_OI_INTERVAL)) 74 75 /** 76 * Macro to convert minutes to OI_INTERVAL time units 77 */ 78 79 #define OI_MINUTES(n) ((OI_INTERVAL)((n) * OI_SECONDS(60))) 80 81 /** Convert an OI_INTERVAL to milliseconds. */ 82 #define OI_INTERVAL_TO_MILLISECONDS(i) ((i) * MSECS_PER_OI_INTERVAL) 83 84 /** 85 * The stack depends on relative not absolute time. Any mapping between the 86 * stack's real-time clock and absolute time and date is 87 * implementation-dependent. 88 */ 89 90 typedef struct { 91 int32_t seconds; 92 int16_t mseconds; 93 } OI_TIME; 94 95 /** 96 * Convert an OI_TIME to milliseconds. 97 * 98 * @param t the time to convert 99 * 100 * @return the time in milliseconds 101 */ 102 uint32_t OI_Time_ToMS(OI_TIME* t); 103 104 /** 105 * This function compares two time values. 106 * 107 * @param T1 first time to compare. 108 * 109 * @param T2 second time to compare. 110 * 111 * @return 112 @verbatim 113 -1 if t1 < t2 114 0 if t1 = t2 115 +1 if t1 > t2 116 @endverbatim 117 */ 118 119 int16_t OI_Time_Compare(OI_TIME* T1, OI_TIME* T2); 120 121 /** 122 * This function returns the interval between two times to a granularity of 0.1 123 * seconds. 124 * 125 * @param Sooner a time value more recent that Later 126 * 127 * @param Later a time value later than Sooner 128 * 129 * @note The result is an OI_INTERVAL value so this function only works for time 130 * intervals that are less than about 71 minutes. 131 * 132 * @return the time interval between the two times = (Later - Sooner) 133 */ 134 135 OI_INTERVAL OI_Time_Interval(OI_TIME* Sooner, OI_TIME* Later); 136 137 /** 138 * This function returns the interval between two times to a granularity of 139 * milliseconds. 140 * 141 * @param Sooner a time value more recent that Later 142 * 143 * @param Later a time value later than Sooner 144 * 145 * @note The result is an uint32_t value so this function only works for time 146 * intervals that are less than about 50 days. 147 * 148 * @return the time interval between the two times = (Later - Sooner) 149 */ 150 151 uint32_t OI_Time_IntervalMsecs(OI_TIME* Sooner, OI_TIME* Later); 152 153 /** 154 * This function answers this question: 155 * "Have we reached or gone past the target time?" 156 * 157 * @param pTargetTime target time 158 * 159 * @return true means time now is at or past target time 160 * false means target time is still some time in the future 161 */ 162 163 OI_BOOL OI_Time_NowReachedTime(OI_TIME* pTargetTime); 164 165 /** 166 * Convert seconds to the Link Manager 1.28-second units 167 * Approximate by using 1.25 conversion factor. 168 */ 169 170 #define OI_SECONDS_TO_LM_TIME_UNITS(lmUnits) \ 171 ((lmUnits) < 4 ? (lmUnits) : (lmUnits) - ((lmUnits) >> 2)) 172 173 /** 174 * Convert Link Manager 1.28-second units to seconds. 175 * Approximate by using 1.25 conversion factor. 176 */ 177 178 #define OI_LM_TIME_UNITS_TO_SECONDS(lmUnits) ((lmUnits) + ((lmUnits) >> 2)) 179 180 #ifdef __cplusplus 181 } 182 #endif 183 184 /**@}*/ 185 186 /* Include for OI_Time_Now() prototype 187 * Must be included at end to obtain OI_TIME typedef 188 */ 189 #include "oi_osinterface.h" 190 191 /*****************************************************************************/ 192 #endif /* _OI_TIME_H */ 193