le_hex.h

Go to the documentation of this file.
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
113 (
114  const char *stringPtr ///< [IN] string of hex chars to convert into an int
115 );
116 
117 #endif // LEGATO_HEX_INCLUDE_GUARD
int le_hex_HexaToInteger(const char *stringPtr)
void le_hex_Dump(char *asciiBufferPtr, size_t asciiBufferSize, char *binaryDataPtr, size_t binaryDataLen)
int32_t le_hex_BinaryToString(const uint8_t *binaryPtr, uint32_t binarySize, char *stringPtr, uint32_t stringSize)
int32_t le_hex_StringToBinary(const char *stringPtr, uint32_t stringLength, uint8_t *binaryPtr, uint32_t binarySize)