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 37 #include "oi_bt_spec.h" 38 #include "oi_common.h" 39 #include "oi_string.h" 40 41 /** \addtogroup Misc Miscellaneous APIs */ 42 /**@{*/ 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * Opaque type for a callback function handle. See OI_ScheduleCallbackFunction() 50 */ 51 typedef uint32_t OI_CALLBACK_HANDLE; 52 53 /** 54 * Function prototype for a timed procedure callback. 55 * 56 * @param arg Value that was passed into the OI_ScheduleCallback() function 57 * 58 */ 59 typedef void (*OI_SCHEDULED_CALLBACK)(void* arg); 60 61 /** 62 * Registers a function to be called when a timeout expires. This API uses 63 * BLUEmagic's internal function dispatch mechanism, so applications that make 64 * extensive use of this facility may need to increase the value of 65 * DispatchTableSize in the configuration block for the dispatcher (see 66 * oi_bt_stack_config.h). 67 * 68 * @param callbackFunction The function that will be called when the timeout 69 * expires 70 * 71 * @param arg Value that will be returned as the parameter to 72 * the callback function. 73 * 74 * @param timeout A timeout expressed in OI_INTERVALs (tenths of 75 * seconds). This can be zero in which case the 76 * callback function will be called as soon as 77 * possible. 78 * 79 * @param handle NULL or a pointer receive the callback handle. 80 * 81 * @return OI_OK if the function was registered, or an error 82 * status. 83 */ 84 OI_STATUS OI_ScheduleCallbackFunction(OI_SCHEDULED_CALLBACK callbackFunction, void* arg, 85 OI_INTERVAL timeout, 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 * Var-args version OI_SNPrintf 229 * 230 * @param buffer Destination buffer for the formatted string. 231 * 232 * @param bufLen The length of the destination buffer. 233 * 234 * @param format The format string 235 * 236 * @param argp Var-args list. 237 * 238 * @return Number of characters written or -1 in the case of an error. 239 */ 240 int32_t OI_VSNPrintf(OI_CHAR* buffer, uint16_t bufLen, const OI_CHAR* format, va_list argp); 241 242 /** 243 * Convert a string to an integer. 244 * 245 * @param str the string to parse 246 * 247 * @return the integer value of the string or 0 if the string could not be 248 * parsed 249 */ 250 OI_INT OI_atoi(const OI_CHAR* str); 251 252 /** 253 * Parse a signed integer in a string. 254 * 255 * Skips leading whitespace (space and tabs only) and parses a decimal or hex 256 * string. Hex string must be prefixed by "0x". Returns pointer to first 257 * character following the integer. Returns the pointer passed in if the string 258 * does not describe an integer. 259 * 260 * @param str String to parse. 261 * 262 * @param val Pointer to receive the parsed integer value. 263 * 264 * @return A pointer to the first character following the integer or the 265 * pointer passed in. 266 */ 267 const OI_CHAR* OI_ScanInt(const OI_CHAR* str, int32_t* val); 268 269 /** 270 * Parse an unsigned integer in a string. 271 * 272 * Skips leading whitespace (space and tabs only) and parses a decimal or hex 273 * string. Hex string must be prefixed by "0x". Returns pointer to first 274 * character following the integer. Returns the pointer passed in if the 275 * string does not describe an integer. 276 * 277 * @param str String to parse. 278 * 279 * @param val Pointer to receive the parsed unsigned integer value. 280 * 281 * @return A pointer to the first character following the unsigned 282 * integer or the pointer passed in. 283 */ 284 const OI_CHAR* OI_ScanUInt(const OI_CHAR* str, uint32_t* val); 285 286 /** 287 * Parse a whitespace delimited substring out of a string. 288 * 289 * @param str Input string to parse. 290 * @param outStr Buffer to return the substring 291 * @param len Length of outStr 292 * 293 * 294 * @return A pointer to the first character following the substring or 295 * the pointer passed in. 296 */ 297 const OI_CHAR* OI_ScanStr(const OI_CHAR* str, OI_CHAR* outStr, uint16_t len); 298 299 /** 300 * Parse a string for one of a set of alternative value. Skips leading 301 * whitespace (space and tabs only) and parses text matching one of the 302 * alternative strings. Returns pointer to first character following the 303 * matched text. 304 * 305 * @param str String to parse. 306 * 307 * @param alts Alternative matching strings separated by '|' 308 * 309 * @param index Pointer to receive the index of the matching alternative, 310 * return value is -1 if there is no match. 311 * 312 * @return A pointer to the first character following the matched value or 313 * the pointer passed in if there was no matching text. 314 */ 315 const OI_CHAR* OI_ScanAlt(const OI_CHAR* str, const OI_CHAR* alts, OI_INT* index); 316 317 /** Get a character from a digit integer value (0 - 9). */ 318 #define OI_DigitToChar(d) ((d) + '0') 319 320 /** 321 * Determine Maximum and Minimum between two arguments. 322 * 323 * @param a 1st value 324 * @param b 2nd value 325 * 326 * @return the max or min value between a & b 327 */ 328 #define OI_MAX(a, b) (((a) < (b)) ? (b) : (a)) 329 #define OI_MIN(a, b) (((a) > (b)) ? (b) : (a)) 330 331 #ifdef __cplusplus 332 } 333 #endif 334 335 /**@}*/ 336 337 #endif /* _OI_UTILS_H */ 338