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