summaryrefslogtreecommitdiff
path: root/libavutil/hash.h (plain)
blob: a20b8934f196f21b81d6566648eb2b8bc0bc2e4c
1/*
2 * Copyright (C) 2013 Reimar Döffinger <Reimar.Doeffinger@gmx.de>
3 *
4 * This file is part of FFmpeg.
5 *
6 * FFmpeg is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * FFmpeg is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with FFmpeg; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20
21/**
22 * @file
23 * @ingroup lavu_hash_generic
24 * Generic hashing API
25 */
26
27#ifndef AVUTIL_HASH_H
28#define AVUTIL_HASH_H
29
30#include <stdint.h>
31
32/**
33 * @defgroup lavu_hash Hash Functions
34 * @ingroup lavu_crypto
35 * Hash functions useful in multimedia.
36 *
37 * Hash functions are widely used in multimedia, from error checking and
38 * concealment to internal regression testing. libavutil has efficient
39 * implementations of a variety of hash functions that may be useful for
40 * FFmpeg and other multimedia applications.
41 *
42 * @{
43 *
44 * @defgroup lavu_hash_generic Generic Hashing API
45 * An abstraction layer for all hash functions supported by libavutil.
46 *
47 * If your application needs to support a wide range of different hash
48 * functions, then the Generic Hashing API is for you. It provides a generic,
49 * reusable API for @ref lavu_hash "all hash functions" implemented in libavutil.
50 * If you just need to use one particular hash function, use the @ref lavu_hash
51 * "individual hash" directly.
52 *
53 * @section Sample Code
54 *
55 * A basic template for using the Generic Hashing API follows:
56 *
57 * @code
58 * struct AVHashContext *ctx = NULL;
59 * const char *hash_name = NULL;
60 * uint8_t *output_buf = NULL;
61 *
62 * // Select from a string returned by av_hash_names()
63 * hash_name = ...;
64 *
65 * // Allocate a hash context
66 * ret = av_hash_alloc(&ctx, hash_name);
67 * if (ret < 0)
68 * return ret;
69 *
70 * // Initialize the hash context
71 * av_hash_init(ctx);
72 *
73 * // Update the hash context with data
74 * while (data_left) {
75 * av_hash_update(ctx, data, size);
76 * }
77 *
78 * // Now we have no more data, so it is time to finalize the hash and get the
79 * // output. But we need to first allocate an output buffer. Note that you can
80 * // use any memory allocation function, including malloc(), not just
81 * // av_malloc().
82 * output_buf = av_malloc(av_hash_get_size(ctx));
83 * if (!output_buf)
84 * return AVERROR(ENOMEM);
85 *
86 * // Finalize the hash context.
87 * // You can use any of the av_hash_final*() functions provided, for other
88 * // output formats. If you do so, be sure to adjust the memory allocation
89 * // above. See the function documentation below for the exact amount of extra
90 * // memory needed.
91 * av_hash_final(ctx, output_buffer);
92 *
93 * // Free the context
94 * av_hash_freep(&ctx);
95 * @endcode
96 *
97 * @section Hash Function-Specific Information
98 * If the CRC32 hash is selected, the #AV_CRC_32_IEEE polynomial will be
99 * used.
100 *
101 * If the Murmur3 hash is selected, the default seed will be used. See @ref
102 * lavu_murmur3_seedinfo "Murmur3" for more information.
103 *
104 * @{
105 */
106
107/**
108 * @example ffhash.c
109 * This example is a simple command line application that takes one or more
110 * arguments. It demonstrates a typical use of the hashing API with allocation,
111 * initialization, updating, and finalizing.
112 */
113
114struct AVHashContext;
115
116/**
117 * Allocate a hash context for the algorithm specified by name.
118 *
119 * @return >= 0 for success, a negative error code for failure
120 *
121 * @note The context is not initialized after a call to this function; you must
122 * call av_hash_init() to do so.
123 */
124int av_hash_alloc(struct AVHashContext **ctx, const char *name);
125
126/**
127 * Get the names of available hash algorithms.
128 *
129 * This function can be used to enumerate the algorithms.
130 *
131 * @param[in] i Index of the hash algorithm, starting from 0
132 * @return Pointer to a static string or `NULL` if `i` is out of range
133 */
134const char *av_hash_names(int i);
135
136/**
137 * Get the name of the algorithm corresponding to the given hash context.
138 */
139const char *av_hash_get_name(const struct AVHashContext *ctx);
140
141/**
142 * Maximum value that av_hash_get_size() will currently return.
143 *
144 * You can use this if you absolutely want or need to use static allocation for
145 * the output buffer and are fine with not supporting hashes newly added to
146 * libavutil without recompilation.
147 *
148 * @warning
149 * Adding new hashes with larger sizes, and increasing the macro while doing
150 * so, will not be considered an ABI change. To prevent your code from
151 * overflowing a buffer, either dynamically allocate the output buffer with
152 * av_hash_get_size(), or limit your use of the Hashing API to hashes that are
153 * already in FFmpeg during the time of compilation.
154 */
155#define AV_HASH_MAX_SIZE 64
156
157/**
158 * Get the size of the resulting hash value in bytes.
159 *
160 * The maximum value this function will currently return is available as macro
161 * #AV_HASH_MAX_SIZE.
162 *
163 * @param[in] ctx Hash context
164 * @return Size of the hash value in bytes
165 */
166int av_hash_get_size(const struct AVHashContext *ctx);
167
168/**
169 * Initialize or reset a hash context.
170 *
171 * @param[in,out] ctx Hash context
172 */
173void av_hash_init(struct AVHashContext *ctx);
174
175/**
176 * Update a hash context with additional data.
177 *
178 * @param[in,out] ctx Hash context
179 * @param[in] src Data to be added to the hash context
180 * @param[in] len Size of the additional data
181 */
182void av_hash_update(struct AVHashContext *ctx, const uint8_t *src, int len);
183
184/**
185 * Finalize a hash context and compute the actual hash value.
186 *
187 * The minimum size of `dst` buffer is given by av_hash_get_size() or
188 * #AV_HASH_MAX_SIZE. The use of the latter macro is discouraged.
189 *
190 * It is not safe to update or finalize a hash context again, if it has already
191 * been finalized.
192 *
193 * @param[in,out] ctx Hash context
194 * @param[out] dst Where the final hash value will be stored
195 *
196 * @see av_hash_final_bin() provides an alternative API
197 */
198void av_hash_final(struct AVHashContext *ctx, uint8_t *dst);
199
200/**
201 * Finalize a hash context and store the actual hash value in a buffer.
202 *
203 * It is not safe to update or finalize a hash context again, if it has already
204 * been finalized.
205 *
206 * If `size` is smaller than the hash size (given by av_hash_get_size()), the
207 * hash is truncated; if size is larger, the buffer is padded with 0.
208 *
209 * @param[in,out] ctx Hash context
210 * @param[out] dst Where the final hash value will be stored
211 * @param[in] size Number of bytes to write to `dst`
212 */
213void av_hash_final_bin(struct AVHashContext *ctx, uint8_t *dst, int size);
214
215/**
216 * Finalize a hash context and store the hexadecimal representation of the
217 * actual hash value as a string.
218 *
219 * It is not safe to update or finalize a hash context again, if it has already
220 * been finalized.
221 *
222 * The string is always 0-terminated.
223 *
224 * If `size` is smaller than `2 * hash_size + 1`, where `hash_size` is the
225 * value returned by av_hash_get_size(), the string will be truncated.
226 *
227 * @param[in,out] ctx Hash context
228 * @param[out] dst Where the string will be stored
229 * @param[in] size Maximum number of bytes to write to `dst`
230 */
231void av_hash_final_hex(struct AVHashContext *ctx, uint8_t *dst, int size);
232
233/**
234 * Finalize a hash context and store the Base64 representation of the
235 * actual hash value as a string.
236 *
237 * It is not safe to update or finalize a hash context again, if it has already
238 * been finalized.
239 *
240 * The string is always 0-terminated.
241 *
242 * If `size` is smaller than AV_BASE64_SIZE(hash_size), where `hash_size` is
243 * the value returned by av_hash_get_size(), the string will be truncated.
244 *
245 * @param[in,out] ctx Hash context
246 * @param[out] dst Where the final hash value will be stored
247 * @param[in] size Maximum number of bytes to write to `dst`
248 */
249void av_hash_final_b64(struct AVHashContext *ctx, uint8_t *dst, int size);
250
251/**
252 * Free hash context and set hash context pointer to `NULL`.
253 *
254 * @param[in,out] ctx Pointer to hash context
255 */
256void av_hash_freep(struct AVHashContext **ctx);
257
258/**
259 * @}
260 * @}
261 */
262
263#endif /* AVUTIL_HASH_H */
264
generated by cgit at 2024-05-17 06:59:50 (GMT)