FFmpeg
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 
117 struct 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  */
127 int 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  */
137 const char *av_hash_names(int i);
138 
139 /**
140  * Get the name of the algorithm corresponding to the given hash context.
141  */
142 const 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  */
169 int 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  */
176 void 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
186 void av_hash_update(struct AVHashContext *ctx, const uint8_t *src, int len);
187 #else
188 void 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  */
205 void 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  */
220 void 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  */
238 void 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  */
256 void 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  */
263 void av_hash_freep(struct AVHashContext **ctx);
264 
265 /**
266  * @}
267  * @}
268  */
269 
270 #endif /* AVUTIL_HASH_H */
name
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf default minimum maximum flags name is the option name
Definition: writing_filters.txt:88
av_hash_final_b64
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.
Definition: hash.c:227
av_hash_get_name
const char * av_hash_get_name(const struct AVHashContext *ctx)
Get the name of the algorithm corresponding to the given hash context.
av_hash_final_bin
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.
Definition: hash.c:206
av_hash_alloc
int av_hash_alloc(struct AVHashContext **ctx, const char *name)
Allocate a hash context for the algorithm specified by name.
Definition: hash.c:102
ctx
AVFormatContext * ctx
Definition: movenc.c:48
av_hash_names
const char * av_hash_names(int i)
Get the names of available hash algorithms.
Definition: hash.c:86
av_hash_init
void av_hash_init(struct AVHashContext *ctx)
Initialize or reset a hash context.
Definition: hash.c:139
src
#define src
Definition: vp8dsp.c:255
av_hash_get_size
int av_hash_get_size(const struct AVHashContext *ctx)
Get the size of the resulting hash value in bytes.
av_hash_freep
void av_hash_freep(struct AVHashContext **ctx)
Free hash context and set hash context pointer to NULL.
Definition: hash.c:240
size
int size
Definition: twinvq_data.h:10344
av_hash_final
void av_hash_final(struct AVHashContext *ctx, uint8_t *dst)
Finalize a hash context and compute the actual hash value.
Definition: hash.c:185
AVHashContext
Definition: hash.c:58
i
int i
Definition: input.c:407
uint8_t
uint8_t
Definition: audio_convert.c:194
len
int len
Definition: vorbis_enc_data.h:452
version.h
av_hash_update
void av_hash_update(struct AVHashContext *ctx, const uint8_t *src, int len)
Update a hash context with additional data.
Definition: hash.c:161
av_hash_final_hex
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...
Definition: hash.c:217
Generated on Wed Aug 24 2022 21:34:49 for FFmpeg by   doxygen 1.8.17