git.sesse.net Git - ffmpeg/blob - 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 <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 void av_hash_update(struct AVHashContext *ctx, const uint8_t *src, size_t len);
 186
 187 /**
 188  * Finalize a hash context and compute the actual hash value.
 189  *
 190  * The minimum size of `dst` buffer is given by av_hash_get_size() or
 191  * #AV_HASH_MAX_SIZE. The use of the latter macro is discouraged.
 192  *
 193  * It is not safe to update or finalize a hash context again, if it has already
 194  * been finalized.
 195  *
 196  * @param[in,out] ctx Hash context
 197  * @param[out]    dst Where the final hash value will be stored
 198  *
 199  * @see av_hash_final_bin() provides an alternative API
 200  */
 201 void av_hash_final(struct AVHashContext *ctx, uint8_t *dst);
 202
 203 /**
 204  * Finalize a hash context and store the actual hash value in a buffer.
 205  *
 206  * It is not safe to update or finalize a hash context again, if it has already
 207  * been finalized.
 208  *
 209  * If `size` is smaller than the hash size (given by av_hash_get_size()), the
 210  * hash is truncated; if size is larger, the buffer is padded with 0.
 211  *
 212  * @param[in,out] ctx  Hash context
 213  * @param[out]    dst  Where the final hash value will be stored
 214  * @param[in]     size Number of bytes to write to `dst`
 215  */
 216 void av_hash_final_bin(struct AVHashContext *ctx, uint8_t *dst, int size);
 217
 218 /**
 219  * Finalize a hash context and store the hexadecimal representation of the
 220  * actual hash value as a string.
 221  *
 222  * It is not safe to update or finalize a hash context again, if it has already
 223  * been finalized.
 224  *
 225  * The string is always 0-terminated.
 226  *
 227  * If `size` is smaller than `2 * hash_size + 1`, where `hash_size` is the
 228  * value returned by av_hash_get_size(), the string will be truncated.
 229  *
 230  * @param[in,out] ctx  Hash context
 231  * @param[out]    dst  Where the string will be stored
 232  * @param[in]     size Maximum number of bytes to write to `dst`
 233  */
 234 void av_hash_final_hex(struct AVHashContext *ctx, uint8_t *dst, int size);
 235
 236 /**
 237  * Finalize a hash context and store the Base64 representation of the
 238  * actual hash value as a string.
 239  *
 240  * It is not safe to update or finalize a hash context again, if it has already
 241  * been finalized.
 242  *
 243  * The string is always 0-terminated.
 244  *
 245  * If `size` is smaller than AV_BASE64_SIZE(hash_size), where `hash_size` is
 246  * the value returned by av_hash_get_size(), the string will be truncated.
 247  *
 248  * @param[in,out] ctx  Hash context
 249  * @param[out]    dst  Where the final hash value will be stored
 250  * @param[in]     size Maximum number of bytes to write to `dst`
 251  */
 252 void av_hash_final_b64(struct AVHashContext *ctx, uint8_t *dst, int size);
 253
 254 /**
 255  * Free hash context and set hash context pointer to `NULL`.
 256  *
 257  * @param[in,out] ctx  Pointer to hash context
 258  */
 259 void av_hash_freep(struct AVHashContext **ctx);
 260
 261 /**
 262  * @}
 263  * @}
 264  */
 265
 266 #endif /* AVUTIL_HASH_H */