le_hex.h

    1 /**
    2  * @page c_hex Hex string API
    3  *
    4  *
    5  * @ref le_hex.h "API Reference"
    6  *
    7  * <HR>
    8  *
    9  *
   10  * This API provides convertion tools to switch between:
   11  *  - @ref le_hex_StringToBinary  Hex-String to binary
   12  *  - @ref le_hex_BinaryToString  Binary to Hex-String
   13  *
   14  *
   15  * @section hex_conversion Conversion
   16  *
   17  * Code sample:
   18  *
   19  * @code
   20  * char     HexString[] = "136ABC";
   21  * uint8_t  binString[] = {0x13,0x6A,0xBC};
   22  * @endcode
   23  *
   24  * So @ref le_hex_StringToBinary will convert HexString to binString.
   25  *
   26  * and @ref le_hex_BinaryToString will convert binString to HexString.
   27  *
   28  *
   29  *
   30  * <HR>
   31  *
   32  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   33  */
   34 
   35 
   36 /** @file le_hex.h
   37  *
   38  * Legato @ref c_hex include file.
   39  *
   40  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   41  */
   42 
   43 #ifndef LEGATO_HEX_INCLUDE_GUARD
   44 #define LEGATO_HEX_INCLUDE_GUARD
   45 
   46 
   47 //--------------------------------------------------------------------------------------------------
   48 /**
   49  * Convert a string of valid hexadecimal characters [0-9a-fA-F] into a byte array where each
   50  * element of the byte array holds the value corresponding to a pair of hexadecimal characters.
   51  *
   52  * @return
   53  *      - number of bytes written into binaryPtr
   54  *      - -1 if the binarySize is too small or stringLength is odd or stringPtr contains an invalid
   55  *        character
   56  *
   57  * @note The input string is not required to be NULL terminated.
   58  */
   59 //--------------------------------------------------------------------------------------------------
   60 int32_t le_hex_StringToBinary
   61 (
   62     const char *stringPtr,     ///< [IN] string to convert
   63     uint32_t    stringLength,  ///< [IN] string length
   64     uint8_t    *binaryPtr,     ///< [OUT] binary result
   65     uint32_t    binarySize     ///< [IN] size of the binary table.  Must be >= stringLength / 2
   66 );
   67 
   68 //--------------------------------------------------------------------------------------------------
   69 /**
   70  * Convert a byte array into a string of uppercase hexadecimal characters.
   71  *
   72  * @return number of characters written to stringPtr or -1 if stringSize is too small for
   73  *         binarySize
   74  *
   75  * @note the string written to stringPtr will be NULL terminated.
   76  */
   77 //--------------------------------------------------------------------------------------------------
   78 int32_t le_hex_BinaryToString
   79 (
   80     const uint8_t *binaryPtr,  ///< [IN] binary array to convert
   81     uint32_t       binarySize, ///< [IN] size of binary array
   82     char          *stringPtr,  ///< [OUT] hex string array, terminated with '\0'.
   83     uint32_t       stringSize  ///< [IN] size of string array.  Must be >= (2 * binarySize) + 1
   84 );
   85 
   86 //--------------------------------------------------------------------------------------------------
   87 /**
   88  * Convert a NULL terminated string of valid hexadecimal characters [0-9a-fA-F] into an integer.
   89  *
   90  * @return
   91  *      - Positive integer corresponding to the hexadecimal input string
   92  *      - -1 if the input contains an invalid character or the value will not fit in an integer
   93  */
   94 //--------------------------------------------------------------------------------------------------
   95 int le_hex_HexaToInteger
   96 (
   97     const char *stringPtr ///< [IN] string of hex chars to convert into an int
   98 );
   99 
  100 #endif // LEGATO_HEX_INCLUDE_GUARD
le_hex_HexaToInteger
int le_hex_HexaToInteger(const char *stringPtr)
le_hex_BinaryToString
int32_t le_hex_BinaryToString(const uint8_t *binaryPtr, uint32_t binarySize, char *stringPtr, uint32_t stringSize)
le_hex_StringToBinary
int32_t le_hex_StringToBinary(const char *stringPtr, uint32_t stringLength, uint8_t *binaryPtr, uint32_t binarySize)