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
44extern "C" {
45#endif
46
47/**
48 * Opaque type for a callback function handle. See OI_ScheduleCallbackFunction()
49 */
50typedef 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 */
58typedef 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 */
83OI_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 */
96OI_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 */
128OI_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 */
202void 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 */
211void 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 */
225int32_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 */
241int32_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 */
252OI_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 */
269const 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 */
286const 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 */
299const 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 */
317const 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