FFmpeg
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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 <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 
114 struct 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  */
124 int 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  */
134 const char *av_hash_names(int i);
135 
136 /**
137  * Get the name of the algorithm corresponding to the given hash context.
138  */
139 const 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  */
166 int 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  */
173 void 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  */
182 void 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  */
198 void 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  */
213 void 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  */
231 void 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  */
249 void 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  */
256 void av_hash_freep(struct AVHashContext **ctx);
257 
258 /**
259  * @}
260  * @}
261  */
262 
263 #endif /* AVUTIL_HASH_H */
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:221
#define src
Definition: vp8dsp.c:254
const char * av_hash_get_name(const struct AVHashContext *ctx)
Get the name of the algorithm corresponding to the given hash context.
uint8_t
ptrdiff_t size
Definition: opengl_enc.c:101
void av_hash_init(struct AVHashContext *ctx)
Initialize or reset a hash context.
Definition: hash.c:137
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:200
void av_hash_final(struct AVHashContext *ctx, uint8_t *dst)
Finalize a hash context and compute the actual hash value.
Definition: hash.c:179
int av_hash_get_size(const struct AVHashContext *ctx)
Get the size of the resulting hash value in bytes.
int av_hash_alloc(struct AVHashContext **ctx, const char *name)
Allocate a hash context for the algorithm specified by name.
Definition: hash.c:100
const char * av_hash_names(int i)
Get the names of available hash algorithms.
Definition: hash.c:84
AVFormatContext * ctx
Definition: movenc.c:48
void av_hash_update(struct AVHashContext *ctx, const uint8_t *src, int len)
Update a hash context with additional data.
Definition: hash.c:158
void av_hash_freep(struct AVHashContext **ctx)
Free hash context and set hash context pointer to NULL.
Definition: hash.c:234
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:211
int len
const char * name
Definition: opengl_enc.c:103