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