le_hex.h

    1 /**
    2  * @page c_hex Hex string API
    3  *
    4  *
    5  * @subpage 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.
   33  */
   34 
   35 
   36 /** @file le_hex.h
   37  *
   38  * Legato @ref c_hex include file.
   39  *
   40  * Copyright (C) Sierra Wireless Inc.
   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  * Function that takes binary data and creates 'hex dump' that is
   89  * stored into user provided ASCII buffer and is null terminated
   90  * Total length of one line will be 74 characters:
   91  * 9 + (16 * 3) + 17
   92  * 0x000000: 2e 2f 68 65 78 64 75 6d 0 00 53 53 48 5f 41 47 ./hexdump.SSH_AG
   93  */
   94 //--------------------------------------------------------------------------------------------------
   95 void le_hex_Dump
   96 (
   97     char     *asciiBufferPtr,
   98     size_t    asciiBufferSize,
   99     char     *binaryDataPtr,
  100     size_t    binaryDataLen
  101 );
  102 
  103 //--------------------------------------------------------------------------------------------------
  104 /**
  105  * Convert a NULL terminated string of valid hexadecimal characters [0-9a-fA-F] into an integer.
  106  *
  107  * @return
  108  *      - Positive integer corresponding to the hexadecimal input string
  109  *      - -1 if the input contains an invalid character or the value will not fit in an integer
  110  */
  111 //--------------------------------------------------------------------------------------------------
  112 int le_hex_HexaToInteger
  113 (
  114     const char *stringPtr ///< [IN] string of hex chars to convert into an int
  115 );
  116 
  117 #endif // LEGATO_HEX_INCLUDE_GUARD
le_hex_HexaToInteger
int le_hex_HexaToInteger(const char *stringPtr)
le_hex_Dump
void le_hex_Dump(char *asciiBufferPtr, size_t asciiBufferSize, char *binaryDataPtr, size_t binaryDataLen)
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)