le_base64.h

Go to the documentation of this file.
1 /**
2  * @page c_base64 Base64 encoding/decoding API
3  *
4  * @subpage le_base64.h "API Reference"
5  *
6  * <HR>
7  *
8  * This module implements encoding binary data into base64-encoded string, which contains only
9  * the characters that belong to the base64 alphabet:
10  * ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=
11  *
12  * This allows to convert the binary data into a form that is suitable for serialization
13  * into a text file (without conflicting with special characters and markup elements),
14  * and for sending through the channels that do not support arbitrary binary data.
15  *
16  * Encoded data is about 33% larger in size than the original binary data. Padding characters '='
17  * are added to the end of the encoded string, to make the string length multiple of 4.
18  *
19  * The following sample performs base64 encoding and decoding:
20  *
21  * @code
22  *
23  * void Base64EncodeDecodeExample
24  * (
25  * void
26  * )
27  * {
28  * // allocate 4-byte array and fill it with some data
29  * uint8_t binBuf[4] = {1, 2, 3, 4};
30  * // use macro to calculate the encoded size, add 1 byte for terminating 0
31  * char encodedBuf[LE_BASE64_ENCODED_SIZE(sizeof(binBuf)) + 1];
32  * uint8_t decodedBuf[4] = {0};
33  *
34  * // perform encoding
35  * size_t len = sizeof(encodedBuf);
36  * le_result_t result = le_base64_Encode(binBuf,
37  * sizeof(binBuf),
38  * encodedBuf,
39  * &len);
40  * if (LE_OK != result)
41  * {
42  * LE_ERROR("Error %d encoding data!", result);
43  * }
44  * LE_INFO("Encoded string [%s] size %zd", encodedBuf, len);
45  *
46  * // perform decoding
47  * len = sizeof(decodedBuf);
48  * result = le_base64_Decode(encodedBuf,
49  * strlen(encodedBuf),
50  * decodedBuf,
51  * &len);
52  * if (LE_OK != result)
53  * {
54  * LE_ERROR("Error %d decoding data!", result);
55  * }
56  * LE_INFO("Decoded length: %zd", len);
57  * LE_INFO("Decoded data: %u %u %u %u",
58  * decodedBuf[0], decodedBuf[1],
59  * decodedBuf[2], decodedBuf[3]);
60  * }
61  * @endcode
62  *
63  * <HR>
64  *
65  * Copyright (C) Sierra Wireless Inc.
66  *
67  */
68 
69 //--------------------------------------------------------------------------------------------------
70 /** @file le_base64.h
71  *
72  * Legato @ref c_base64 include file.
73  *
74  * Copyright (C) Sierra Wireless Inc.
75  */
76 //--------------------------------------------------------------------------------------------------
77 
78 #ifndef LEGATO_BASE64_INCLUDE_GUARD
79 #define LEGATO_BASE64_INCLUDE_GUARD
80 
81 //--------------------------------------------------------------------------------------------------
82 /**
83  * Calculate the encoded string length (including padding, not including terminating zero)
84  * for a given binary data size.
85  */
86 //--------------------------------------------------------------------------------------------------
87 #define LE_BASE64_ENCODED_SIZE(x) (4 * ((x + 2) / 3))
88 
89 //--------------------------------------------------------------------------------------------------
90 /**
91  * Perform base64 data encoding.
92  *
93  * @return
94  * - LE_OK if succeeds
95  * - LE_BAD_PARAMETER if NULL pointer provided
96  * - LE_OVERFLOW if provided buffer is not large enough
97  */
98 //--------------------------------------------------------------------------------------------------
100 (
101  const uint8_t *dataPtr, ///< [IN] Data to be encoded
102  size_t dataLength, ///< [IN] Data length
103  char *resultPtr, ///< [OUT] Base64-encoded string buffer
104  size_t *resultSizePtr ///< [INOUT] Length of the base64-encoded string buffer
105 );
106 
107 //--------------------------------------------------------------------------------------------------
108 /**
109  * Decode base64-encoded data.
110  *
111  * @return
112  * - LE_OK if succeeds
113  * - LE_BAD_PARAMETER if NULL pointer provided
114  * - LE_FORMAT_ERROR if data contains invalid (non-base64) characters
115  * - LE_OVERFLOW if provided buffer is not large enough
116  */
117 //--------------------------------------------------------------------------------------------------
119 (
120  const char *srcPtr, ///< [IN] Encoded string
121  size_t srcLen, ///< [IN] Encoded string length
122  uint8_t *dstPtr, ///< [OUT] Binary data buffer
123  size_t *dstLenPtr ///< [INOUT] Binary data buffer size / decoded data size
124 );
125 
126 #endif // LEGATO_BASE64_INCLUDE_GUARD
le_result_t
Definition: le_basics.h:46
le_result_t le_base64_Encode(const uint8_t *dataPtr, size_t dataLength, char *resultPtr, size_t *resultSizePtr)
le_result_t le_base64_Decode(const char *srcPtr, size_t srcLen, uint8_t *dstPtr, size_t *dstLenPtr)