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_UTILS_H 20 #define _OI_UTILS_H 21 /** 22 * @file 23 * 24 * This file provides the interface for utility functions. 25 * Among the utilities are strlen (string length), strcmp (string compare), and 26 * other string manipulation functions. These are provided for those plaforms 27 * where this functionality is not available in stdlib. 28 */ 29 30 /********************************************************************************** 31 $Revision: #1 $ 32 ***********************************************************************************/ 33 34 #include <stdarg.h> 35 #include "oi_common.h" 36 #include "oi_string.h" 37 #include "oi_bt_spec.h" 38 39 /** \addtogroup Misc Miscellaneous APIs */ 40 /**@{*/ 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * Opaque type for a callback function handle. See OI_ScheduleCallbackFunction() 48 */ 49 typedef OI_UINT32 OI_CALLBACK_HANDLE; 50 51 52 /** 53 * Function prototype for a timed procedure callback. 54 * 55 * @param arg Value that was passed into the OI_ScheduleCallback() function 56 * 57 */ 58 typedef void (*OI_SCHEDULED_CALLBACK)(void *arg); 59 60 61 /** 62 * Registers a function to be called when a timeout expires. This API uses BLUEmagic's internal 63 * function dispatch mechanism, so applications that make extensive use of this facility may need to 64 * increase the value of DispatchTableSize in the configuration block for the dispatcher (see 65 * oi_bt_stack_config.h). 66 * 67 * @param callbackFunction The function that will be called when the timeout expires 68 * 69 * @param arg Value that will be returned as the parameter to the callback function. 70 * 71 * @param timeout A timeout expressed in OI_INTERVALs (tenths of seconds). This can be 72 * zero in which case the callback function will be called as soon as 73 * possible. 74 * 75 * @param handle NULL or a pointer receive the callback handle. 76 * 77 * @return OI_OK if the function was reqistered, or an error status. 78 */ 79 OI_STATUS OI_ScheduleCallbackFunction(OI_SCHEDULED_CALLBACK callbackFunction, 80 void *arg, 81 OI_INTERVAL timeout, 82 OI_CALLBACK_HANDLE *handle); 83 84 85 /** 86 * Cancels a function registered with OI_ScheduleCallbackFunction() before its timer expires. 87 * 88 * @param handle handle returned by OI_ScheduleCallbackFunction(). 89 * 90 * @return OI_OK if the function was cancelled, or an error status. 91 */ 92 OI_STATUS OI_CancelCallbackFunction(OI_CALLBACK_HANDLE handle); 93 94 95 /** 96 * Registers a function to be called when a timeout expires. This version does not return a handle 97 * so can only be canceled by calling OI_CancelCallback(). 98 * 99 * @param callbackFunction The function that will be called when the timeout expires 100 * 101 * @param arg Value that will be returned as the parameter to the callback function. 102 * 103 * @param timeout A timeout expressed in OI_INTERVALs (tenths of seconds). This can be 104 * zero in which case the callback function will be called as soon as 105 * possible. 106 * 107 * @return OI_OK if the function was reqistered, or an error status. 108 */ 109 #define OI_ScheduleCallback(f, a, t) OI_ScheduleCallbackFunction(f, a, t, NULL); 110 111 112 /** 113 * Cancels a function registered with OI_ScheduleCallback() before its timer expires. This 114 * function will cancel the first entry matches the indicated callback function pointer. 115 * 116 * @param callbackFunction The function that was originally registered 117 * 118 * @return OI_OK if the function was cancelled, or an error status. 119 */ 120 OI_STATUS OI_CancelCallback(OI_SCHEDULED_CALLBACK callbackFunction); 121 122 123 /** 124 * Parse a Bluetooth device address from the specified string. 125 * 126 * @param str the string to parse 127 * @param addr the parsed address, if successful 128 * 129 * @return TRUE if an address was successfully parsed, FALSE otherwise 130 */ 131 132 OI_BOOL OI_ParseBdAddr(const OI_CHAR *str, 133 OI_BD_ADDR *addr) ; 134 135 /** 136 * Printf function for platforms which have no stdio or printf available. 137 * OI_Printf supports the basic formatting types, with the exception of 138 * floating point types. Additionally, OI_Printf supports several formats 139 * specific to BLUEmagic 3.0 software: 140 * 141 * \%! prints the string for an #OI_STATUS value. 142 * @code OI_Printf("There was an error %!", status); @endcode 143 * 144 * \%@ prints a hex dump of a buffer. 145 * Requires a pointer to the buffer and a signed integer length 146 * (0 for default length). If the buffer is large, only an excerpt will 147 * be printed. 148 * @code OI_Printf("Contents of buffer %@", buffer, sizeof(buffer)); @endcode 149 * 150 * \%: prints a Bluetooth address in the form "HH:HH:HH:HH:HH:HH". 151 * Requires a pointer to an #OI_BD_ADDR. 152 * @code OI_Printf("Bluetooth address %:", &bdaddr); @endcode 153 * 154 * \%^ decodes and prints a data element as formatted XML. 155 * Requires a pointer to an #OI_DATAELEM. 156 * @code OI_Printf("Service attribute list is:\n%^", &attributes); @endcode 157 * 158 * \%/ prints the base file name of a path, that is, the final substring 159 * following a '/' or '\\' character. Requires a pointer to a null 160 * terminated string. 161 * @code OI_Printf("File %/", "c:\\dir1\\dir2\\file.txt"); @endcode 162 * 163 * \%~ prints a string, escaping characters as needed to display it in 164 * ASCII. Requires a pointer to an #OI_PSTR and an #OI_UNICODE_ENCODING 165 * parameter. 166 * @code OI_Printf("Identifier %~", &id, OI_UNICODE_UTF16_BE); @endcode 167 * 168 * \%[ inserts an ANSI color escape sequence. Requires a single character 169 * identifying the color to select. Colors are red (r/R), green (g/G), 170 * blue (b/B), yellow (y/Y), cyan (c/C), magenta (m/M), white (W), 171 * light-gray (l/L), dark-gray (d/D), and black (0). The lower case is 172 * dim, the upper case is bright (except in the case of light-gray and 173 * dark-gray, where bright and dim are identical). Any other value will 174 * select the default color. 175 * @code OI_Printf("%[red text %[black %[normal\n", 'r', '0', 0); @endcode 176 * 177 * \%a same as \%s, except '\\r' and '\\n' are output as "<cr>" and "<lf>". 178 * \%?a is valid, but \%la is not. 179 * 180 * \%b prints an integer in base 2. 181 * @code OI_Printf("Bits are %b", I); @endcode 182 * 183 * \%lb prints a long integer in base 2. 184 * 185 * \%?b prints the least significant N bits of an integer (or long integer) 186 * in base 2. Requires the integer and a length N. 187 * @code OI_Printf("Bottom 4 bits are: %?b", I, 4); @endcode 188 * 189 * \%B prints an integer as boolean text, "TRUE" or "FALSE". 190 * @code OI_Printf("The value 0 is %B, the value 1 is %B", 0, 1); @endcode 191 * 192 * \%?s prints a substring up to a specified maximum length. 193 * Requires a pointer to a string and a length parameter. 194 * @code OI_Printf("String prefix is %?s", str, 3); @endcode 195 * 196 * \%ls same as \%S. 197 * 198 * \%S prints a UTF16 string as UTF8 (plain ASCII, plus 8-bit char sequences 199 * where needed). Requires a pointer to #OI_CHAR16. \%?S is valid. The 200 * length parameter is in OI_CHAR16 characters. 201 * 202 * \%T prints time, formatted as "secs.msecs". 203 * Requires pointer to #OI_TIME struct, NULL pointer prints current time. 204 * @code OI_Printf("The time now is %T", NULL); @endcode 205 * 206 * @param format The format string 207 * 208 */ 209 void OI_Printf(const OI_CHAR *format, ...); 210 211 212 /** 213 * Var-args version OI_Printf 214 * 215 * @param format Same as for OI_Printf. 216 * 217 * @param argp Var-args list. 218 */ 219 void OI_VPrintf(const OI_CHAR *format, va_list argp); 220 221 222 /** 223 * Writes a formatted string to a buffer. This function supports the same format specifiers as 224 * OI_Printf(). 225 * 226 * @param buffer Destination buffer for the formatted string. 227 * 228 * @param bufLen The length of the destination buffer. 229 * 230 * @param format The format string 231 * 232 * @return Number of characters written or -1 in the case of an error. 233 */ 234 OI_INT32 OI_SNPrintf(OI_CHAR *buffer, 235 OI_UINT16 bufLen, 236 const OI_CHAR* format, ...); 237 238 239 /** 240 * Var-args version OI_SNPrintf 241 * 242 * @param buffer Destination buffer for the formatted string. 243 * 244 * @param bufLen The length of the destination buffer. 245 * 246 * @param format The format string 247 * 248 * @param argp Var-args list. 249 * 250 * @return Number of characters written or -1 in the case of an error. 251 */ 252 OI_INT32 OI_VSNPrintf(OI_CHAR *buffer, 253 OI_UINT16 bufLen, 254 const OI_CHAR *format, va_list argp); 255 256 257 /** 258 * Convert a string to an integer. 259 * 260 * @param str the string to parse 261 * 262 * @return the integer value of the string or 0 if the string could not be parsed 263 */ 264 OI_INT OI_atoi(const OI_CHAR *str); 265 266 267 /** 268 * Parse a signed integer in a string. 269 * 270 * Skips leading whitespace (space and tabs only) and parses a decimal or hex string. Hex string 271 * must be prefixed by "0x". Returns pointer to first character following the integer. Returns the 272 * pointer passed in if the string does not describe an integer. 273 * 274 * @param str String to parse. 275 * 276 * @param val Pointer to receive the parsed integer value. 277 * 278 * @return A pointer to the first character following the integer or the pointer passed in. 279 */ 280 const OI_CHAR* OI_ScanInt(const OI_CHAR *str, 281 OI_INT32 *val); 282 283 284 /** 285 * Parse an unsigned integer in a string. 286 * 287 * Skips leading whitespace (space and tabs only) and parses a decimal or hex string. Hex string 288 * must be prefixed by "0x". Returns pointer to first character following the integer. Returns the 289 * pointer passed in if the string does not describe an integer. 290 * 291 * @param str String to parse. 292 * 293 * @param val Pointer to receive the parsed unsigned integer value. 294 * 295 * @return A pointer to the first character following the unsigned integer or the pointer passed in. 296 */ 297 const OI_CHAR* OI_ScanUInt(const OI_CHAR *str, 298 OI_UINT32 *val); 299 300 /** 301 * Parse a whitespace delimited substring out of a string. 302 * 303 * @param str Input string to parse. 304 * @param outStr Buffer to return the substring 305 * @param len Length of outStr 306 * 307 * 308 * @return A pointer to the first character following the substring or the pointer passed in. 309 */ 310 const OI_CHAR* OI_ScanStr(const OI_CHAR *str, 311 OI_CHAR *outStr, 312 OI_UINT16 len); 313 314 315 /** 316 * Parse a string for one of a set of alternative value. Skips leading whitespace (space and tabs 317 * only) and parses text matching one of the alternative strings. Returns pointer to first character 318 * following the matched text. 319 * 320 * @param str String to parse. 321 * 322 * @param alts Alternative matching strings separated by '|' 323 * 324 * @param index Pointer to receive the index of the matching alternative, return value is -1 if 325 * there is no match. 326 * 327 * @return A pointer to the first character following the matched value or the pointer passed in 328 * if there was no matching text. 329 */ 330 const OI_CHAR* OI_ScanAlt(const OI_CHAR *str, 331 const OI_CHAR *alts, 332 OI_INT *index); 333 334 /** 335 * Parse a string for a BD Addr. Skips leading whitespace (space and tabs only) and parses a 336 * Bluetooth device address with nibbles optionally separated by colons. Return pointet to first 337 * character following the BD Addr. 338 * 339 * @param str String to parse. 340 * 341 * @param addr Pointer to receive the Bluetooth device address 342 * 343 * @return A pointer to the first character following the BD Addr or the pointer passed in. 344 */ 345 const OI_CHAR* OI_ScanBdAddr(const OI_CHAR *str, 346 OI_BD_ADDR *addr); 347 348 349 /** Get a character from a digit integer value (0 - 9). */ 350 #define OI_DigitToChar(d) ((d) + '0') 351 352 /** 353 * Determine Maximum and Minimum between two arguments. 354 * 355 * @param a 1st value 356 * @param b 2nd value 357 * 358 * @return the max or min value between a & b 359 */ 360 #define OI_MAX(a, b) (((a) < (b)) ? (b) : (a) ) 361 #define OI_MIN(a, b) (((a) > (b)) ? (b) : (a) ) 362 363 /** 364 * Compare two BD_ADDRs 365 * SAME_BD_ADDR - Boolean: TRUE if they are the same address 366 */ 367 368 #define SAME_BD_ADDR(x, y) (0 == OI_MemCmp((x),(y),OI_BD_ADDR_BYTE_SIZE) ) 369 370 #ifdef __cplusplus 371 } 372 #endif 373 374 /**@}*/ 375 376 #endif /* _OI_UTILS_H */ 377 378