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