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