Mstdlib-1.24.0
m_bin.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_BIN_H__
25#define __M_BIN_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_bin Binary data
37 * \ingroup mstdlib_base
38 *
39 * Allows for wrapping binary data into a data type that includes both length and data.
40 * This is to allow binary data to be passed around as a single pointer instead of having
41 * to manage the data separate from the length.
42 *
43 * Binary data of form data, len will be wrapped into len+data.
44 * The length prefix is always fixed as 8. 8 was chosen instead of sizeof(size_t) because
45 * 32bit Solaris Sparc sizeof(size_t) is 4 but alignment is 8. 8 is also sizeof(size_t) on
46 * 64bit platforms.
47 *
48 * Example:
49 *
50 * \code{.c}
51 * M_uint8 data[3] = { 1, 2, 3 };
52 * M_uint8 *wd;
53 * M_uint8 *wd_dup;
54 * size_t len;
55 *
56 * wd = M_bin_wrap(data, 3);
57 * wd_dup = M_bin_wrapeddup(wd);
58 *
59 * M_free(wd);
60 * wd = M_bin_unwrapdup(wd_dup, &len);
61 *
62 * M_free(wd);
63 * M_free(wd_dup);
64 *
65 * M_printf(len='%zu'\n", len);
66 * \endcode
67 *
68 * @{
69 */
70
71
72/*! Duplicate a binary value with the length prepended.
73 *
74 * \param[in] value The binary data.
75 * \param[in] len The length of value.
76 *
77 * \return Allocated memory of len+data of length len+sizeof(len). Where sizeof(size_t) is typically 8.
78 */
79M_API M_uint8 *M_bin_wrap(const M_uint8 *value, size_t len);
80
81
82/*! Duplicates binary data that has the length prepended.
83 *
84 * The data would have to have been created using M_bin_wrap.
85 * The prepended length is used to determine how much memory to duplicate.
86 *
87 * \param[in] value Wrapped binary data to duplicate.
88 *
89 * \return Copy of wrapped data (len+data).
90 */
91M_API M_uint8 *M_bin_wrapeddup(const M_uint8 *value);
92
93
94/*! Duplicates data that has the length prepended.
95 *
96 * The data would have to have been created using M_bin_wrap.
97 * The prepended length is used to determine how much memory to duplicate.
98 * This function should be considered unsafe and is only provided
99 * as a convience to avoid casting if the data is not an M_uint8.
100 *
101 * \param[in] value Wrapped binary data to duplicate.
102 *
103 * \return Copy of wrapped data (len+data).
104 *
105 * \see M_bin_wrapeddup
106 */
107M_API void *M_bin_wrapeddup_vp(const void *value);
108
109
110/*! Unwrap wrapped binary data.
111 *
112 * \param[in] value Wrapped binary data.
113 * \param[out] len The length of the binary data.
114 *
115 * \return Pointer to start of data within value.
116 */
117M_API const M_uint8 *M_bin_unwrap(const M_uint8 *value, size_t *len);
118
119
120/*! Unwrap wrapped binary data and return a copy of the data.
121 *
122 * \param[in] value Wrapped binary data.
123 * \param[out] len The length of the binary data.
124 *
125 * \return Allocated memory with a copy of data from value. The prepended length will not be duplicated.
126 */
127M_API M_uint8 *M_bin_unwrapdup(const M_uint8 *value, size_t *len);
128
129/*! @} */
130
131__END_DECLS
132
133#endif /* __M_BIN_H__ */
M_bin_wrapeddup_vp
void * M_bin_wrapeddup_vp(const void *value)
M_bin_wrapeddup
M_uint8 * M_bin_wrapeddup(const M_uint8 *value)
M_bin_unwrapdup
M_uint8 * M_bin_unwrapdup(const M_uint8 *value, size_t *len)
M_bin_unwrap
const M_uint8 * M_bin_unwrap(const M_uint8 *value, size_t *len)
M_bin_wrap
M_uint8 * M_bin_wrap(const M_uint8 *value, size_t len)