1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY!
2 #ifndef _GLIBMM_CHECKSUM_H
3 #define _GLIBMM_CHECKSUM_H
4
5
6 /* Copyright (C) 2002 The gtkmm Development Team
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 */
21
22
23 #include <glibmm/value.h>
24 #include <glib.h>
25 #include <string>
26
27 #ifndef DOXYGEN_SHOULD_SKIP_THIS
28 extern "C" { typedef struct _GChecksum GChecksum; }
29 #endif
30
31 //TODO: When we can change API, make Checksum a _CLASS_BOXEDTYPE.
32
33 namespace Glib
34 {
35
36 /** Computes the checksum for data.
37 * This is a generic API for computing checksums (or "digests") for a sequence of arbitrary bytes,
38 * using various hashing algorithms like MD5, SHA-1 and SHA-256. Checksums are commonly used in various environments and specifications.
39 *
40 * glibmm supports incremental checksums by calling update() as long as there's data available and then using get_string()
41 * or get_digest() to compute the checksum and return it either as a string in hexadecimal form, or as a raw sequence of bytes.
42 * To compute the checksum for binary blobs and NULL-terminated strings in one go, use the static compute_checksum() convenience functions().
43 *
44 * @newin{2,16}
45 */
46 class GLIBMM_API Checksum
47 {
48 public:
49 #ifndef DOXYGEN_SHOULD_SKIP_THIS
50 using CppObjectType = Checksum;
51 using BaseObjectType = GChecksum;
52 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
53
54 /** Constructs an invalid object.
55 * E.g. for output arguments to methods. There is not much you can do with
56 * the object before it has been assigned a valid value.
57 */
58 Checksum();
59
60 // Use make_a_copy=true when getting it directly from a struct.
61 explicit Checksum(GChecksum* castitem, bool make_a_copy = false);
62
63 Checksum(const Checksum& src);
64 Checksum& operator=(const Checksum& src);
65
66 Checksum(Checksum&& other) noexcept;
67 Checksum& operator=(Checksum&& other) noexcept;
68
69 ~Checksum() noexcept;
70
71 void swap(Checksum& other) noexcept;
72
gobj()73 GChecksum* gobj() { return gobject_; }
gobj()74 const GChecksum* gobj() const { return gobject_; }
75
76 ///Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.
77 GChecksum* gobj_copy() const;
78
79 protected:
80 GChecksum* gobject_;
81
82 private:
83
84
85 public:
86 /** @addtogroup glibmmEnums glibmm Enums and Flags */
87
88 /**
89 * @var ChecksumType CHECKSUM_MD5
90 * Use the MD5 hashing algorithm.
91 *
92 * @var ChecksumType CHECKSUM_SHA1
93 * Use the SHA-1 hashing algorithm.
94 *
95 * @var ChecksumType CHECKSUM_SHA256
96 * Use the SHA-256 hashing algorithm.
97 *
98 * @var ChecksumType CHECKSUM_SHA384
99 * Use the SHA-384 hashing algorithm (Since: 2.51).
100 *
101 * @var ChecksumType CHECKSUM_SHA512
102 * Use the SHA-512 hashing algorithm (Since: 2.36).
103 *
104 * @enum ChecksumType
105 *
106 * The hashing algorithm to be used by Checksum when performing the
107 * digest of some data.
108 *
109 * Note that the ChecksumType enumeration may be extended at a later
110 * date to include new hashing algorithm types.
111 *
112 * @newin{2,16}
113 *
114 * @ingroup glibmmEnums
115 */
116 enum ChecksumType
117 {
118 CHECKSUM_MD5,
119 CHECKSUM_SHA1,
120 CHECKSUM_SHA256,
121 CHECKSUM_SHA512,
122 CHECKSUM_SHA384
123 };
124
125
126 /** Creates a new Checksum, using the checksum algorithm @a checksum_type.
127 * If the checksum_type is not known, then operator bool() will return false.
128 *
129 * @param checksum_type Checksum type, one of defined above.
130 */
131 explicit Checksum(ChecksumType checksum_type);
132
133 /** Returns true if the Checksum object is valid.
134 * This will return false, for instance, if an unsupported checksum type was provided to the constructor.
135 */
136 explicit operator bool() const;
137
138
139 /** Resets the state of the @a checksum back to its initial state.
140 *
141 * @newin{2,18}
142 */
143 void reset();
144
145 //TODO: length should really be gssize, not gsize, when we can break ABI:
146
147
148 /** Feeds @a data into an existing Checksum. The checksum must still be
149 * open, that is g_checksum_get_string() or g_checksum_get_digest() must
150 * not have been called on @a checksum.
151 *
152 * @newin{2,16}
153 *
154 * @param data Buffer used to compute the checksum.
155 * @param length Size of the buffer, or -1 if it is a null-terminated string.
156 */
157 void update(const guchar* data, gsize length);
158
159 /** Feeds data into an existing Checksum.
160 * The checksum must still be open, that is get_string() or get_digest() must not have been called on the checksum.
161 *
162 * @param data Buffer used to compute the checksum
163 */
164 void update(const std::string& data);
165
166
167 /** Gets the digest from @a checksum as a raw binary vector and places it
168 * into @a buffer. The size of the digest depends on the type of checksum.
169 *
170 * Once this function has been called, the Checksum is closed and can
171 * no longer be updated with g_checksum_update().
172 *
173 * @newin{2,16}
174 *
175 * @param buffer Output buffer.
176 * @param digest_len An inout parameter. The caller initializes it to the size of @a buffer.
177 * After the call it contains the length of the digest.
178 */
179 void get_digest(guint8 * buffer, gsize * digest_len) const;
180
181
182 /** Gets the digest as a hexadecimal string.
183 *
184 * Once this function has been called the Checksum can no longer be
185 * updated with g_checksum_update().
186 *
187 * The hexadecimal characters will be lower case.
188 *
189 * @newin{2,16}
190 *
191 * @return The hexadecimal representation of the checksum. The
192 * returned string is owned by the checksum and should not be modified
193 * or freed.
194 */
195 std::string get_string() const;
196
197
198 /** Computes the checksum for a binary @a data of @a length. This is a
199 * convenience wrapper for g_checksum_new(), g_checksum_get_string()
200 * and g_checksum_free().
201 *
202 * The hexadecimal string returned will be in lower case.
203 *
204 * @newin{2,16}
205 *
206 * @param checksum_type A ChecksumType.
207 * @param data Binary blob to compute the digest of.
208 * @param length Length of @a data.
209 * @return The digest of the binary data as a string in hexadecimal.
210 */
211 static std::string compute_checksum(ChecksumType checksum_type, const guchar* data, gsize length);
212
213 /** Computes the checksum of a string.
214 *
215 * @param checksum_type A ChecksumType
216 * @param str The string to compute the checksum of.
217 * @result The checksum as a hexadecimal string.
218 */
219 static std::string compute_checksum(ChecksumType checksum_type, const std::string& str);
220
221
222 //We don't use _WRAP_METHOD because this is not really a GCheckSum function:
223 /** Gets the length in bytes of digests of type @a checksum_type.
224 *
225 * @param checksum_type A ChecksumType.
226 * @result The checksum length, or -1 if @a checksum_type is not supported.
227 */
228 static gssize get_length(ChecksumType checksum_type);
229
230
231 };
232
233 #ifndef DOXYGEN_SHOULD_SKIP_THIS
234 // This is needed so Glib::Checksum can be used with Glib::Value and _WRAP_PROPERTY.
235 template <>
236 class GLIBMM_API Value<Glib::Checksum> : public ValueBase_Boxed
237 {
238 public:
239 using CppType = Glib::Checksum;
240 using CType = GChecksum*;
241
242 static GType value_type();
243
244 void set(const CppType& data);
245 CppType get() const;
246 };
247 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
248
249 } //namespace Glib
250
251
252 namespace Glib
253 {
254
255 /** @relates Glib::Checksum
256 * @param lhs The left-hand side
257 * @param rhs The right-hand side
258 */
swap(Checksum & lhs,Checksum & rhs)259 inline void swap(Checksum& lhs, Checksum& rhs) noexcept
260 { lhs.swap(rhs); }
261
262 } // namespace Glib
263
264 namespace Glib
265 {
266
267 /** A Glib::wrap() method for this object.
268 *
269 * @param object The C instance.
270 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
271 * @result A C++ instance that wraps this C instance.
272 *
273 * @relates Glib::Checksum
274 */
275 GLIBMM_API
276 Glib::Checksum wrap(GChecksum* object, bool take_copy = false);
277
278 } // namespace Glib
279
280
281 #endif /* _GLIBMM_CHECKSUM_H */
282
283