decoder/include/oi_utils.h

/******************************************************************************
 *
 *  Copyright (C) 2014 The Android Open Source Project
 *  Copyright 2002 - 2004 Open Interface North America, Inc. All rights
 *                        reserved.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at:
 *
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 ******************************************************************************/
#ifndef _OI_UTILS_H
#define _OI_UTILS_H
/**
 * @file
 *
 * This file provides the interface for utility functions.
 * Among the utilities are strlen (string length), strcmp (string compare), and
 * other string manipulation functions. These are provided for those plaforms
 * where this functionality is not available in stdlib.
 */

/*******************************************************************************
  $Revision: #1 $
 ******************************************************************************/

#include <stdarg.h>
#include "oi_bt_spec.h"
#include "oi_common.h"
#include "oi_string.h"

/** \addtogroup Misc Miscellaneous APIs */
/**@{*/

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Opaque type for a callback function handle. See OI_ScheduleCallbackFunction()
 */
typedef uint32_t OI_CALLBACK_HANDLE;

/**
 * Function prototype for a timed procedure callback.
 *
 * @param arg   Value that was passed into the OI_ScheduleCallback() function
 *
 */
typedef void (*OI_SCHEDULED_CALLBACK)(void* arg);

/**
 * Registers a function to be called when a timeout expires. This API uses
 * BLUEmagic's internal function dispatch mechanism, so applications that make
 * extensive use of this facility may need to increase the value of
 * DispatchTableSize in the configuration block for the dispatcher (see
 * oi_bt_stack_config.h).
 *
 * @param callbackFunction    The function that will be called when the timeout
 *                            expires
 *
 * @param arg                 Value that will be returned as the parameter to
 *                            the callback function.
 *
 * @param timeout             A timeout expressed in OI_INTERVALs (tenths of
 *                            seconds). This can be zero in which case the
 *                            callback function will be called as soon as
 *                            possible.
 *
 * @param handle              NULL or a pointer receive the callback handle.
 *
 * @return                    OI_OK if the function was registered, or an error
 *                            status.
 */
OI_STATUS OI_ScheduleCallbackFunction(OI_SCHEDULED_CALLBACK callbackFunction,
                                      void* arg, OI_INTERVAL timeout,
                                      OI_CALLBACK_HANDLE* handle);

/**
 * Cancels a function registered with OI_ScheduleCallbackFunction() before its
 * timer expires.
 *
 * @param handle              handle returned by  OI_ScheduleCallbackFunction().
 *
 * @return                    OI_OK if the function was cancelled, or an error
 *                            status.
 */
OI_STATUS OI_CancelCallbackFunction(OI_CALLBACK_HANDLE handle);

/**
 * Registers a function to be called when a timeout expires. This version does
 * not return a handle so can only be canceled by calling OI_CancelCallback().
 *
 * @param callbackFunction    The function that will be called when the timeout
 *                            expires
 *
 * @param arg                 Value that will be returned as the parameter to
 *                            the callback function.
 *
 * @param timeout             A timeout expressed in OI_INTERVALs (tenths of
 *                            seconds). This can be zero in which case the
 *                            callback function will be called as soon as
 *                            possible.
 *
 * @return                    OI_OK if the function was reqistered, or an error
 *                            status.
 */
#define OI_ScheduleCallback(f, a, t) OI_ScheduleCallbackFunction(f, a, t, NULL);

/**
 * Cancels a function registered with OI_ScheduleCallback() before its timer
 * expires. This function will cancel the first entry matches the indicated
 * callback function pointer.
 *
 * @param callbackFunction    The function that was originally registered
 *
 * @return                    OI_OK if the function was cancelled, or an error
 *                            status.
 */
OI_STATUS OI_CancelCallback(OI_SCHEDULED_CALLBACK callbackFunction);

/**
 * Parse a Bluetooth device address from the specified string.
 *
 * @param str   the string to parse
 * @param addr  the parsed address, if successful
 *
 * @return true if an address was successfully parsed, false otherwise
 */

OI_BOOL OI_ParseBdAddr(const OI_CHAR* str, OI_BD_ADDR* addr);

/**
 * Printf function for platforms which have no stdio or printf available.
 * OI_Printf supports the basic formatting types, with the exception of
 * floating point types. Additionally, OI_Printf supports several formats
 * specific to BLUEmagic 3.0 software:
 *
 * \%!   prints the string for an #OI_STATUS value.
 *       @code OI_Printf("There was an error %!", status); @endcode
 *
 * \%@   prints a hex dump of a buffer.
 *       Requires a pointer to the buffer and a signed integer length
 *       (0 for default length). If the buffer is large, only an excerpt will
 *       be printed.
 *       @code OI_Printf("Contents of buffer %@", buffer, sizeof(buffer));
 *       @endcode
 *
 * \%:   prints a Bluetooth address in the form "HH:HH:HH:HH:HH:HH".
 *       Requires a pointer to an #OI_BD_ADDR.
 *       @code OI_Printf("Bluetooth address %:", &bdaddr); @endcode
 *
 * \%^   decodes and prints a data element as formatted XML.
 *       Requires a pointer to an #OI_DATAELEM.
 *       @code OI_Printf("Service attribute list is:\n%^", &attributes);
 *       @endcode
 *
 * \%/   prints the base file name of a path, that is, the final substring
 *       following a '/' or '\\' character. Requires a pointer to a null
 *       terminated string.
 *       @code OI_Printf("File %/", "c:\\dir1\\dir2\\file.txt"); @endcode
 *
 * \%~   prints a string, escaping characters as needed to display it in
 *       ASCII. Requires a pointer to an #OI_PSTR and an #OI_UNICODE_ENCODING
 *       parameter.
 *       @code OI_Printf("Identifier %~", &id, OI_UNICODE_UTF16_BE); @endcode
 *
 * \%[   inserts an ANSI color escape sequence. Requires a single character
 *       identifying the color to select. Colors are red (r/R), green (g/G),
 *       blue (b/B), yellow (y/Y), cyan (c/C), magenta (m/M), white (W),
 *       light-gray (l/L), dark-gray (d/D), and black (0). The lower case is
 *       dim, the upper case is bright (except in the case of light-gray and
 *       dark-gray, where bright and dim are identical). Any other value will
 *       select the default color.
 *       @code OI_Printf("%[red text %[black %[normal\n", 'r', '0', 0); @endcode
 *
 * \%a   same as \%s, except '\\r' and '\\n' are output as "<cr>" and "<lf>".
 *       \%?a is valid, but \%la is not.
 *
 * \%b   prints an integer in base 2.
 *       @code OI_Printf("Bits are %b", I); @endcode
 *
 * \%lb  prints a long integer in base 2.
 *
 * \%?b  prints the least significant N bits of an integer (or long integer)
 *       in base 2. Requires the integer and a length N.
 *       @code OI_Printf("Bottom 4 bits are: %?b", I, 4); @endcode
 *
 * \%B   prints an integer as boolean text, "TRUE" or "FALSE".
 *       @code OI_Printf("The value 0 is %B, the value 1 is %B", 0, 1); @endcode
 *
 * \%?s  prints a substring up to a specified maximum length.
 *       Requires a pointer to a string and a length parameter.
 *       @code OI_Printf("String prefix is %?s", str, 3); @endcode
 *
 * \%ls  same as \%S.
 *
 * \%S   prints a UTF16 string as UTF8 (plain ASCII, plus 8-bit char sequences
 *       where needed). Requires a pointer to #OI_CHAR16. \%?S is valid. The
 *       length parameter is in OI_CHAR16 characters.
 *
 * \%T   prints time, formatted as "secs.msecs".
 *       Requires pointer to #OI_TIME struct, NULL pointer prints current time.
 *       @code OI_Printf("The time now is %T", NULL); @endcode
 *
 *  @param format   The format string
 *
 */
void OI_Printf(const OI_CHAR* format, ...);

/**
 * Var-args version OI_Printf
 *
 * @param format   Same as for OI_Printf.
 *
 * @param argp     Var-args list.
 */
void OI_VPrintf(const OI_CHAR* format, va_list argp);

/**
 * Writes a formatted string to a buffer. This function supports the same format
 * specifiers as OI_Printf().
 *
 * @param buffer   Destination buffer for the formatted string.
 *
 * @param bufLen   The length of the destination buffer.
 *
 * @param format   The format string
 *
 * @return   Number of characters written or -1 in the case of an error.
 */
int32_t OI_SNPrintf(OI_CHAR* buffer, uint16_t bufLen, const OI_CHAR* format,
                    ...);

/**
 * Var-args version OI_SNPrintf
 *
 * @param buffer   Destination buffer for the formatted string.
 *
 * @param bufLen   The length of the destination buffer.
 *
 * @param format   The format string
 *
 * @param argp     Var-args list.
 *
 * @return   Number of characters written or -1 in the case of an error.
 */
int32_t OI_VSNPrintf(OI_CHAR* buffer, uint16_t bufLen, const OI_CHAR* format,
                     va_list argp);

/**
 * Convert a string to an integer.
 *
 * @param str  the string to parse
 *
 * @return the integer value of the string or 0 if the string could not be
 *         parsed
 */
OI_INT OI_atoi(const OI_CHAR* str);

/**
 * Parse a signed integer in a string.
 *
 * Skips leading whitespace (space and tabs only) and parses a decimal or hex
 * string. Hex string must be prefixed by "0x". Returns pointer to first
 * character following the integer. Returns the pointer passed in if the string
 * does not describe an integer.
 *
 * @param str    String to parse.
 *
 * @param val    Pointer to receive the parsed integer value.
 *
 * @return       A pointer to the first character following the integer or the
 *               pointer passed in.
 */
const OI_CHAR* OI_ScanInt(const OI_CHAR* str, int32_t* val);

/**
 * Parse an unsigned integer in a string.
 *
 * Skips leading whitespace (space and tabs only) and parses a decimal or hex
 * string. Hex string must be prefixed by "0x". Returns pointer to first
 * character following the integer. Returns the pointer passed in if the
 * string does not describe an integer.
 *
 * @param str    String to parse.
 *
 * @param val    Pointer to receive the parsed unsigned integer value.
 *
 * @return       A pointer to the first character following the unsigned
 *               integer or the pointer passed in.
 */
const OI_CHAR* OI_ScanUInt(const OI_CHAR* str, uint32_t* val);

/**
 * Parse a whitespace delimited substring out of a string.
 *
 * @param str     Input string to parse.
 * @param outStr  Buffer to return the substring
 * @param len     Length of outStr
 *
 *
 * @return       A pointer to the first character following the substring or
 *               the pointer passed in.
 */
const OI_CHAR* OI_ScanStr(const OI_CHAR* str, OI_CHAR* outStr, uint16_t len);

/**
 * Parse a string for one of a set of alternative value. Skips leading
 * whitespace (space and tabs only) and parses text matching one of the
 * alternative strings. Returns pointer to first character following the
 * matched text.
 *
 * @param str    String to parse.
 *
 * @param alts   Alternative matching strings separated by '|'
 *
 * @param index  Pointer to receive the index of the matching alternative,
 *               return value is -1 if there is no match.
 *
 * @return       A pointer to the first character following the matched value or
 *               the pointer passed in if there was no matching text.
 */
const OI_CHAR* OI_ScanAlt(const OI_CHAR* str, const OI_CHAR* alts,
                          OI_INT* index);

/**
 * Parse a string for a BD Addr. Skips leading whitespace (space and tabs only)
 * and parses a Bluetooth device address with nibbles optionally separated by
 * colons. Return pointet to first character following the BD Addr.
 *
 * @param str    String to parse.
 *
 * @param addr   Pointer to receive the Bluetooth device address
 *
 * @return       A pointer to the first character following the BD Addr or the
 *               pointer passed in.
 */
const OI_CHAR* OI_ScanBdAddr(const OI_CHAR* str, OI_BD_ADDR* addr);

/** Get a character from a digit integer value (0 - 9). */
#define OI_DigitToChar(d) ((d) + '0')

/**
 * Determine Maximum and Minimum between two arguments.
 *
 * @param a  1st value
 * @param b  2nd value
 *
 * @return the max or min value between a & b
 */
#define OI_MAX(a, b) (((a) < (b)) ? (b) : (a))
#define OI_MIN(a, b) (((a) > (b)) ? (b) : (a))

/**
 * Compare two BD_ADDRs
 * SAME_BD_ADDR - Boolean: true if they are the same address
 */

#define SAME_BD_ADDR(x, y) (0 == OI_MemCmp((x), (y), OI_BD_ADDR_BYTE_SIZE))

#ifdef __cplusplus
}
#endif

/**@}*/

#endif /* _OI_UTILS_H */