1 /******************************************************************************
2  *
3  *  Copyright (C) 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  * Parse a Bluetooth device address from the specified string.
132  *
133  * @param str   the string to parse
134  * @param addr  the parsed address, if successful
135  *
136  * @return true if an address was successfully parsed, false otherwise
137  */
138 
139 OI_BOOL OI_ParseBdAddr(const OI_CHAR* str, OI_BD_ADDR* addr);
140 
141 /**
142  * Printf function for platforms which have no stdio or printf available.
143  * OI_Printf supports the basic formatting types, with the exception of
144  * floating point types. Additionally, OI_Printf supports several formats
145  * specific to BLUEmagic 3.0 software:
146  *
147  * \%!   prints the string for an #OI_STATUS value.
148  *       @code OI_Printf("There was an error %!", status); @endcode
149  *
150  * \%@   prints a hex dump of a buffer.
151  *       Requires a pointer to the buffer and a signed integer length
152  *       (0 for default length). If the buffer is large, only an excerpt will
153  *       be printed.
154  *       @code OI_Printf("Contents of buffer %@", buffer, sizeof(buffer));
155  *       @endcode
156  *
157  * \%:   prints a Bluetooth address in the form "HH:HH:HH:HH:HH:HH".
158  *       Requires a pointer to an #OI_BD_ADDR.
159  *       @code OI_Printf("Bluetooth address %:", &bdaddr); @endcode
160  *
161  * \%^   decodes and prints a data element as formatted XML.
162  *       Requires a pointer to an #OI_DATAELEM.
163  *       @code OI_Printf("Service attribute list is:\n%^", &attributes);
164  *       @endcode
165  *
166  * \%/   prints the base file name of a path, that is, the final substring
167  *       following a '/' or '\\' character. Requires a pointer to a null
168  *       terminated string.
169  *       @code OI_Printf("File %/", "c:\\dir1\\dir2\\file.txt"); @endcode
170  *
171  * \%~   prints a string, escaping characters as needed to display it in
172  *       ASCII. Requires a pointer to an #OI_PSTR and an #OI_UNICODE_ENCODING
173  *       parameter.
174  *       @code OI_Printf("Identifier %~", &id, OI_UNICODE_UTF16_BE); @endcode
175  *
176  * \%[   inserts an ANSI color escape sequence. Requires a single character
177  *       identifying the color to select. Colors are red (r/R), green (g/G),
178  *       blue (b/B), yellow (y/Y), cyan (c/C), magenta (m/M), white (W),
179  *       light-gray (l/L), dark-gray (d/D), and black (0). The lower case is
180  *       dim, the upper case is bright (except in the case of light-gray and
181  *       dark-gray, where bright and dim are identical). Any other value will
182  *       select the default color.
183  *       @code OI_Printf("%[red text %[black %[normal\n", 'r', '0', 0); @endcode
184  *
185  * \%a   same as \%s, except '\\r' and '\\n' are output as "<cr>" and "<lf>".
186  *       \%?a is valid, but \%la is not.
187  *
188  * \%b   prints an integer in base 2.
189  *       @code OI_Printf("Bits are %b", I); @endcode
190  *
191  * \%lb  prints a long integer in base 2.
192  *
193  * \%?b  prints the least significant N bits of an integer (or long integer)
194  *       in base 2. Requires the integer and a length N.
195  *       @code OI_Printf("Bottom 4 bits are: %?b", I, 4); @endcode
196  *
197  * \%B   prints an integer as boolean text, "TRUE" or "FALSE".
198  *       @code OI_Printf("The value 0 is %B, the value 1 is %B", 0, 1); @endcode
199  *
200  * \%?s  prints a substring up to a specified maximum length.
201  *       Requires a pointer to a string and a length parameter.
202  *       @code OI_Printf("String prefix is %?s", str, 3); @endcode
203  *
204  * \%ls  same as \%S.
205  *
206  * \%S   prints a UTF16 string as UTF8 (plain ASCII, plus 8-bit char sequences
207  *       where needed). Requires a pointer to #OI_CHAR16. \%?S is valid. The
208  *       length parameter is in OI_CHAR16 characters.
209  *
210  * \%T   prints time, formatted as "secs.msecs".
211  *       Requires pointer to #OI_TIME struct, NULL pointer prints current time.
212  *       @code OI_Printf("The time now is %T", NULL); @endcode
213  *
214  *  @param format   The format string
215  *
216  */
217 void OI_Printf(const OI_CHAR* format, ...);
218 
219 /**
220  * Var-args version OI_Printf
221  *
222  * @param format   Same as for OI_Printf.
223  *
224  * @param argp     Var-args list.
225  */
226 void OI_VPrintf(const OI_CHAR* format, va_list argp);
227 
228 /**
229  * Writes a formatted string to a buffer. This function supports the same format
230  * specifiers as OI_Printf().
231  *
232  * @param buffer   Destination buffer for the formatted string.
233  *
234  * @param bufLen   The length of the destination buffer.
235  *
236  * @param format   The format string
237  *
238  * @return   Number of characters written or -1 in the case of an error.
239  */
240 int32_t OI_SNPrintf(OI_CHAR* buffer, uint16_t bufLen, const OI_CHAR* format,
241                     ...);
242 
243 /**
244  * Var-args version OI_SNPrintf
245  *
246  * @param buffer   Destination buffer for the formatted string.
247  *
248  * @param bufLen   The length of the destination buffer.
249  *
250  * @param format   The format string
251  *
252  * @param argp     Var-args list.
253  *
254  * @return   Number of characters written or -1 in the case of an error.
255  */
256 int32_t OI_VSNPrintf(OI_CHAR* buffer, uint16_t bufLen, const OI_CHAR* format,
257                      va_list argp);
258 
259 /**
260  * Convert a string to an integer.
261  *
262  * @param str  the string to parse
263  *
264  * @return the integer value of the string or 0 if the string could not be
265  *         parsed
266  */
267 OI_INT OI_atoi(const OI_CHAR* str);
268 
269 /**
270  * Parse a signed 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 string
275  * does not describe an integer.
276  *
277  * @param str    String to parse.
278  *
279  * @param val    Pointer to receive the parsed integer value.
280  *
281  * @return       A pointer to the first character following the integer or the
282  *               pointer passed in.
283  */
284 const OI_CHAR* OI_ScanInt(const OI_CHAR* str, int32_t* val);
285 
286 /**
287  * Parse an unsigned integer in a string.
288  *
289  * Skips leading whitespace (space and tabs only) and parses a decimal or hex
290  * string. Hex string must be prefixed by "0x". Returns pointer to first
291  * character following the integer. Returns the pointer passed in if the
292  * string does not describe an integer.
293  *
294  * @param str    String to parse.
295  *
296  * @param val    Pointer to receive the parsed unsigned integer value.
297  *
298  * @return       A pointer to the first character following the unsigned
299  *               integer or the pointer passed in.
300  */
301 const OI_CHAR* OI_ScanUInt(const OI_CHAR* str, uint32_t* val);
302 
303 /**
304  * Parse a whitespace delimited substring out of a string.
305  *
306  * @param str     Input string to parse.
307  * @param outStr  Buffer to return the substring
308  * @param len     Length of outStr
309  *
310  *
311  * @return       A pointer to the first character following the substring or
312  *               the pointer passed in.
313  */
314 const OI_CHAR* OI_ScanStr(const OI_CHAR* str, OI_CHAR* outStr, uint16_t len);
315 
316 /**
317  * Parse a string for one of a set of alternative value. Skips leading
318  * whitespace (space and tabs only) and parses text matching one of the
319  * alternative strings. Returns pointer to first character following the
320  * matched text.
321  *
322  * @param str    String to parse.
323  *
324  * @param alts   Alternative matching strings separated by '|'
325  *
326  * @param index  Pointer to receive the index of the matching alternative,
327  *               return value is -1 if there is no match.
328  *
329  * @return       A pointer to the first character following the matched value or
330  *               the pointer passed in if there was no matching text.
331  */
332 const OI_CHAR* OI_ScanAlt(const OI_CHAR* str, const OI_CHAR* alts,
333                           OI_INT* index);
334 
335 /**
336  * Parse a string for a BD Addr. Skips leading whitespace (space and tabs only)
337  * and parses a Bluetooth device address with nibbles optionally separated by
338  * colons. Return pointet to first character following the BD Addr.
339  *
340  * @param str    String to parse.
341  *
342  * @param addr   Pointer to receive the Bluetooth device address
343  *
344  * @return       A pointer to the first character following the BD Addr or the
345  *               pointer passed in.
346  */
347 const OI_CHAR* OI_ScanBdAddr(const OI_CHAR* str, OI_BD_ADDR* addr);
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