Mstdlib-1.24.0
m_bincodec.h
1/* The MIT License (MIT)
2 *
3 * Copyright (c) 2015 Monetra Technologies, LLC.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to deal
7 * in the Software without restriction, including without limitation the rights
8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 * copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 * THE SOFTWARE.
22 */
23
24#ifndef __M_BINCODEC_H__
25#define __M_BINCODEC_H__
26
27/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
28
29#include <mstdlib/base/m_defs.h>
30#include <mstdlib/base/m_types.h>
31
32/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
33
34__BEGIN_DECLS
35
36/*! \addtogroup m_bincodec Binary Conversion
37 * \ingroup mstdlib_base
38 *
39 * Text to binary and binary to text conversion. Supports conversion of
40 * binary to or from base64 or hex.
41 *
42 * Example:
43 *
44 * \code{.c}
45 * const char *data = "abcd";
46 * char *out[16];
47 * char *odata;
48 *
49 * M_bincodec_encode(out, sizeof(out), (M_uint8 *)data, M_str_len(data), 0, M_BINCODEC_HEX);
50 * M_printf("hex='%s'\n", out);
51 *
52 * M_bincodec_encode(out, sizeof(out), (M_uint8 *)data, M_str_len(data), 0, M_BINCODEC_BASE64);
53 * M_printf("b64='%s'\n", out);
54 *
55 * odata = (char *)M_bincodec_decode_alloc(out, M_str_len(out), NULL, M_BINCODEC_BASE64ORHEX);
56 * M_printf("original='%s'\n", odata);
57 *
58 * M_free(odata);
59 * \endcode
60 *
61 * @{
62 */
63
64#define M_BINCODEC_PEM_LINE_LEN 64
65
66/*! Binary conversion types. */
67typedef enum {
68 M_BINCODEC_BASE64, /*!< Base64 encoding. */
69 M_BINCODEC_HEX, /*!< Hex encoding. */
70 M_BINCODEC_BASE64ORHEX, /*!< Auto detected between base64 and hex encoding. */
71 M_BINCODEC_BASE32 /*!< Base32 encoding. */
72} M_bincodec_codec_t;
73
74
75/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
76 * Encode
77 */
78
79/*! The maximum number of bytes necessary to encode using the specified codec.
80 *
81 * \param[in] inLen Number of bytes that will be passed to the encoder.
82 * \param[in] wrap The maximum length of a given line. Longer lines will be split with a new line. Pass 0 if
83 * line splitting is not desired.
84 * \param[in] codec The binary codec that will be used for encoding.
85 *
86 * \return The maximum number of bytes needed to store the data after encoding.
87 */
88M_API size_t M_bincodec_encode_size(size_t inLen, size_t wrap, M_bincodec_codec_t codec);
89
90
91/*! Encodes data passed into it using the specified binary codec.
92 *
93 * \param[in] in The binary data to encode.
94 * \param[in] inLen The length of the input data.
95 * \param[in] wrap The maximum length of a given line. Longer lines will be split with a new line. Pass 0 if
96 * line splitting is not desired.
97 * \param[in] codec The binary codec to use for encoding.
98 *
99 * \return A new NULL terminated string with the encoded data. Otherwise NULL on error.
100 *
101 * \see M_free
102 */
103M_API char *M_bincodec_encode_alloc(const M_uint8 *in, size_t inLen, size_t wrap, M_bincodec_codec_t codec) M_WARN_UNUSED_RESULT M_MALLOC;
104
105
106/*! Encodes data passed into it using the specified binary codec.
107 *
108 * \param[out] out A buffer large enough to hold the encoded data.
109 * \param[in] outLen The length of the output buffer.
110 * \param[in] in The binary data to encode.
111 * \param[in] inLen The length of the input data.
112 * \param[in] wrap The maximum length of a given line. Longer lines will be split with a new line. Pass 0 if
113 * line splitting is not desired.
114 * \param[in] codec The binary codec to use for encoding.
115 *
116 * \return The number of bytes written into the output buffer.
117 */
118M_API size_t M_bincodec_encode(char *out, size_t outLen, const M_uint8 *in, size_t inLen, size_t wrap, M_bincodec_codec_t codec);
119
120
121/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
122 * Decode
123 */
124
125
126/*! The maximum number of bytes necessary to encode using the specified codec.
127 *
128 * \param[in] inLen Number of bytes that will be passed to the decoder.
129 * \param[in] codec The binary codec that will be used for decoding.
130 *
131 * \return The maximum number of bytes needed to store the data after decoding.
132 */
133M_API size_t M_bincodec_decode_size(size_t inLen, M_bincodec_codec_t codec);
134
135/*! Decodes data passed into it using the specified binary codec.
136 *
137 * \param[in] in The string data to decode.
138 * \param[in] inLen The length of the input data.
139 * \param[out] outLen The length ouf the buffer.
140 * \param[in] codec The binary codec to use for decoding.
141 *
142 * \return A new array with the decoded data. Otherwise NULL on error.
143 *
144 * \see M_free
145 */
146M_API M_uint8 *M_bincodec_decode_alloc(const char *in, size_t inLen, size_t *outLen, M_bincodec_codec_t codec) M_WARN_UNUSED_RESULT M_MALLOC;
147
148
149/*! Convenience function for validating decoded data is a string. Some protocols
150 * may encode string data even if it is not necessary, so this function helps
151 * validate that data is really in string form to prevent issues.
152 *
153 * \param[in] in The string data to decode.
154 * \param[in] codec The binary codec to use for decoding.
155 *
156 * \return A new buffer with decoded data, otherwise NULL on error.
157 */
158M_API char *M_bincodec_decode_str_alloc(const char *in, M_bincodec_codec_t codec);
159
160
161/*! Decodes data passed into it using the specified binary codec.
162 *
163 * \param[out] out A buffer large enought to hold the decoded data.
164 * \param[in] outLen The length of the output buffer.
165 * \param[in] in The string data to decode.
166 * \param[in] inLen The length of the input data.
167 * \param[in] codec The binary codec to use for decoding.
168 *
169 * \return The number of bytes written into the output buffer, or 0 on error.
170 */
171M_API size_t M_bincodec_decode(M_uint8 *out, size_t outLen, const char *in, size_t inLen, M_bincodec_codec_t codec);
172
173
174/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
175 * Conversion
176 */
177
178/*! Convert a string from one binary encoding to another.
179 *
180 * A conversion will always be performed even when using the same input and
181 * output codecs.
182 *
183 * \param[in] in The data to convert.
184 * \param[in] inLen The length of the input data.
185 * \param[in] wrap The maximum length of a given line. Longer lines will be split with a new line. Pass 0 if
186 * line splitting is not desired.
187 * \param[in] inCodec The format the input data is encoded using.
188 * \param[in] outCodec The output format to convert into.
189 *
190 * \return A new NULL terminated string with the converted data. Otherwise NULL on error.
191 *
192 * \see M_free
193 */
194M_API char *M_bincodec_convert_alloc(const char *in, size_t inLen, size_t wrap, M_bincodec_codec_t inCodec, M_bincodec_codec_t outCodec) M_WARN_UNUSED_RESULT M_MALLOC;
195
196
197/*! Convert a string from one binary encoding to another.
198 *
199 * A conversion will always be performed even when using the same input and
200 * output codecs.
201 *
202 * \param[out] out A buffer large enought to hold the converted data.
203 * \param[in] outLen The length of the output buffer.
204 * \param[in] wrap The maximum length of a given line. Longer lines will be split with a new line. Pass 0 if
205 * line splitting is not desired.
206 * \param[in] outCodec The output format to convert into.
207 * \param[in] in The data to convert.
208 * \param[in] inLen The length of the input data.
209 * \param[in] inCodec The format the input data is encoded using.
210 *
211 * \return The number of bytes written into the output buffer.
212 */
213M_API size_t M_bincodec_convert(char *out, size_t outLen, size_t wrap, M_bincodec_codec_t outCodec, const char *in, size_t inLen, M_bincodec_codec_t inCodec);
214
215/*! @} */
216
217__END_DECLS
218
219#endif /* __M_BINCODEC_H__ */
M_bincodec_convert_alloc
char * M_bincodec_convert_alloc(const char *in, size_t inLen, size_t wrap, M_bincodec_codec_t inCodec, M_bincodec_codec_t outCodec) M_WARN_UNUSED_RESULT M_MALLOC
M_bincodec_codec_t
M_bincodec_codec_t
Definition: m_bincodec.h:67
M_bincodec_convert
size_t M_bincodec_convert(char *out, size_t outLen, size_t wrap, M_bincodec_codec_t outCodec, const char *in, size_t inLen, M_bincodec_codec_t inCodec)
M_bincodec_decode_alloc
M_uint8 * M_bincodec_decode_alloc(const char *in, size_t inLen, size_t *outLen, M_bincodec_codec_t codec) M_WARN_UNUSED_RESULT M_MALLOC
M_bincodec_decode
size_t M_bincodec_decode(M_uint8 *out, size_t outLen, const char *in, size_t inLen, M_bincodec_codec_t codec)
M_bincodec_encode
size_t M_bincodec_encode(char *out, size_t outLen, const M_uint8 *in, size_t inLen, size_t wrap, M_bincodec_codec_t codec)
M_bincodec_encode_size
size_t M_bincodec_encode_size(size_t inLen, size_t wrap, M_bincodec_codec_t codec)
M_bincodec_encode_alloc
char * M_bincodec_encode_alloc(const M_uint8 *in, size_t inLen, size_t wrap, M_bincodec_codec_t codec) M_WARN_UNUSED_RESULT M_MALLOC
M_bincodec_decode_size
size_t M_bincodec_decode_size(size_t inLen, M_bincodec_codec_t codec)
M_bincodec_decode_str_alloc
char * M_bincodec_decode_str_alloc(const char *in, M_bincodec_codec_t codec)
M_BINCODEC_BASE64ORHEX
@ M_BINCODEC_BASE64ORHEX
Definition: m_bincodec.h:70
M_BINCODEC_BASE32
@ M_BINCODEC_BASE32
Definition: m_bincodec.h:71
M_BINCODEC_HEX
@ M_BINCODEC_HEX
Definition: m_bincodec.h:69
M_BINCODEC_BASE64
@ M_BINCODEC_BASE64
Definition: m_bincodec.h:68