avutil/hash: Add more detailed Doxygen documentation
This commit is contained in:
Timothy Gu
parent
613c86299f
commit
f29ffbc87d
|
|
@ -822,7 +822,7 @@ EXCLUDE_SYMBOLS =
|
|||
# that contain example code fragments that are included (see the \include
|
||||
# command).
|
||||
|
||||
EXAMPLE_PATH = doc/examples/
|
||||
EXAMPLE_PATH = doc/examples/ tools/
|
||||
|
||||
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
|
||||
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
|
||||
|
|
|
|||
169
libavutil/hash.h
169
libavutil/hash.h
|
|
@ -32,21 +32,94 @@
|
|||
/**
|
||||
* @defgroup lavu_hash Hash Functions
|
||||
* @ingroup lavu_crypto
|
||||
* Hash functions useful in multimedia.
|
||||
*
|
||||
* Hash functions are widely used in multimedia, from error checking and
|
||||
* concealment to internal regression testing. libavutil has efficient
|
||||
* implementations of a variety of hash functions that may be useful for
|
||||
* FFmpeg and other multimedia applications.
|
||||
*
|
||||
* @{
|
||||
*
|
||||
* @defgroup lavu_hash_generic Generic Hashing API
|
||||
* An abstraction layer for all hash functions supported by libavutil.
|
||||
*
|
||||
* If your application needs to support a wide range of different hash
|
||||
* functions, then the Generic Hashing API is for you. It provides a generic,
|
||||
* reusable API for @ref lavu_hash "all hash functions" implemented in libavutil.
|
||||
* If you just need to use one particular hash function, use the @ref lavu_hash
|
||||
* "individual hash" directly.
|
||||
*
|
||||
* @section Sample Code
|
||||
*
|
||||
* A basic template for using the Generic Hashing API follows:
|
||||
*
|
||||
* @code
|
||||
* struct AVHashContext *ctx = NULL;
|
||||
* const char *hash_name = NULL;
|
||||
* uint8_t *output_buf = NULL;
|
||||
*
|
||||
* // Select from a string returned by av_hash_names()
|
||||
* hash_name = ...;
|
||||
*
|
||||
* // Allocate a hash context
|
||||
* ret = av_hash_alloc(&ctx, hash_name);
|
||||
* if (ret < 0)
|
||||
* return ret;
|
||||
*
|
||||
* // Initialize the hash context
|
||||
* av_hash_init(ctx);
|
||||
*
|
||||
* // Update the hash context with data
|
||||
* while (data_left) {
|
||||
* av_hash_update(ctx, data, size);
|
||||
* }
|
||||
*
|
||||
* // Now we have no more data, so it is time to finalize the hash and get the
|
||||
* // output. But we need to first allocate an output buffer. Note that you can
|
||||
* // use any memory allocation function, including malloc(), not just
|
||||
* // av_malloc().
|
||||
* output_buf = av_malloc(av_hash_get_size(ctx));
|
||||
* if (!output_buf)
|
||||
* return AVERROR(ENOMEM);
|
||||
*
|
||||
* // Finalize the hash context.
|
||||
* // You can use any of the av_hash_final*() functions provided, for other
|
||||
* // output formats. If you do so, be sure to adjust the memory allocation
|
||||
* // above. See the function documentation below for the exact amount of extra
|
||||
* // memory needed.
|
||||
* av_hash_final(ctx, output_buffer);
|
||||
*
|
||||
* // Free the context
|
||||
* av_hash_freep(&ctx);
|
||||
* @endcode
|
||||
*
|
||||
* @section Hash Function-Specific Information
|
||||
* If the CRC32 hash is selected, the #AV_CRC_32_IEEE polynomial will be
|
||||
* used.
|
||||
*
|
||||
* If the Murmur3 hash is selected, the default seed will be used. See @ref
|
||||
* lavu_murmur3_seedinfo "Murmur3" for more information.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @example ffhash.c
|
||||
* This example is a simple command line application that takes one or more
|
||||
* arguments. It demonstrates a typical use of the hashing API with allocation,
|
||||
* initialization, updating, and finalizing.
|
||||
*/
|
||||
|
||||
struct AVHashContext;
|
||||
|
||||
/**
|
||||
* Allocate a hash context for the algorithm specified by name.
|
||||
*
|
||||
* @return >= 0 for success, a negative error code for failure
|
||||
* @note The context is not initialized, you must call av_hash_init().
|
||||
*
|
||||
* @note The context is not initialized after a call to this function; you must
|
||||
* call av_hash_init() to do so.
|
||||
*/
|
||||
int av_hash_alloc(struct AVHashContext **ctx, const char *name);
|
||||
|
||||
|
|
@ -55,8 +128,8 @@ int av_hash_alloc(struct AVHashContext **ctx, const char *name);
|
|||
*
|
||||
* This function can be used to enumerate the algorithms.
|
||||
*
|
||||
* @param i index of the hash algorithm, starting from 0
|
||||
* @return a pointer to a static string or NULL if i is out of range
|
||||
* @param[in] i Index of the hash algorithm, starting from 0
|
||||
* @return Pointer to a static string or `NULL` if `i` is out of range
|
||||
*/
|
||||
const char *av_hash_names(int i);
|
||||
|
||||
|
|
@ -66,63 +139,119 @@ const char *av_hash_names(int i);
|
|||
const char *av_hash_get_name(const struct AVHashContext *ctx);
|
||||
|
||||
/**
|
||||
* Maximum value that av_hash_get_size will currently return.
|
||||
* Maximum value that av_hash_get_size() will currently return.
|
||||
*
|
||||
* You can use this if you absolutely want or need to use static allocation
|
||||
* and are fine with not supporting hashes newly added to libavutil without
|
||||
* recompilation.
|
||||
* Note that you still need to check against av_hash_get_size, adding new hashes
|
||||
* with larger sizes will not be considered an ABI change and should not cause
|
||||
* your code to overflow a buffer.
|
||||
* You can use this if you absolutely want or need to use static allocation for
|
||||
* the output buffer and are fine with not supporting hashes newly added to
|
||||
* libavutil without recompilation.
|
||||
*
|
||||
* @warning
|
||||
* Adding new hashes with larger sizes, and increasing the macro while doing
|
||||
* so, will not be considered an ABI change. To prevent your code from
|
||||
* overflowing a buffer, either dynamically allocate the output buffer with
|
||||
* av_hash_get_size(), or limit your use of the Hashing API to hashes that are
|
||||
* already in FFmpeg during the time of compilation.
|
||||
*/
|
||||
#define AV_HASH_MAX_SIZE 64
|
||||
|
||||
/**
|
||||
* Get the size of the resulting hash value in bytes.
|
||||
*
|
||||
* The pointer passed to av_hash_final have space for at least this many bytes.
|
||||
* The maximum value this function will currently return is available as macro
|
||||
* #AV_HASH_MAX_SIZE.
|
||||
*
|
||||
* @param[in] ctx Hash context
|
||||
* @return Size of the hash value in bytes
|
||||
*/
|
||||
int av_hash_get_size(const struct AVHashContext *ctx);
|
||||
|
||||
/**
|
||||
* Initialize or reset a hash context.
|
||||
*
|
||||
* @param[in,out] ctx Hash context
|
||||
*/
|
||||
void av_hash_init(struct AVHashContext *ctx);
|
||||
|
||||
/**
|
||||
* Update a hash context with additional data.
|
||||
*
|
||||
* @param[in,out] ctx Hash context
|
||||
* @param[in] src Data to be added to the hash context
|
||||
* @param[in] len Size of the additional data
|
||||
*/
|
||||
void av_hash_update(struct AVHashContext *ctx, const uint8_t *src, int len);
|
||||
|
||||
/**
|
||||
* Finalize a hash context and compute the actual hash value.
|
||||
*
|
||||
* The minimum size of `dst` buffer is given by av_hash_get_size() or
|
||||
* #AV_HASH_MAX_SIZE. The use of the latter macro is discouraged.
|
||||
*
|
||||
* It is not safe to update or finalize a hash context again, if it has already
|
||||
* been finalized.
|
||||
*
|
||||
* @param[in,out] ctx Hash context
|
||||
* @param[out] dst Where the final hash value will be stored
|
||||
*
|
||||
* @see av_hash_final_bin() provides an alternative API
|
||||
*/
|
||||
void av_hash_final(struct AVHashContext *ctx, uint8_t *dst);
|
||||
|
||||
/**
|
||||
* Finalize a hash context and compute the actual hash value.
|
||||
* If size is smaller than the hash size, the hash is truncated;
|
||||
* if size is larger, the buffer is padded with 0.
|
||||
* Finalize a hash context and store the actual hash value in a buffer.
|
||||
*
|
||||
* It is not safe to update or finalize a hash context again, if it has already
|
||||
* been finalized.
|
||||
*
|
||||
* If `size` is smaller than the hash size (given by av_hash_get_size()), the
|
||||
* hash is truncated; if size is larger, the buffer is padded with 0.
|
||||
*
|
||||
* @param[in,out] ctx Hash context
|
||||
* @param[out] dst Where the final hash value will be stored
|
||||
* @param[in] size Number of bytes to write to `dst`
|
||||
*/
|
||||
void av_hash_final_bin(struct AVHashContext *ctx, uint8_t *dst, int size);
|
||||
|
||||
/**
|
||||
* Finalize a hash context and compute the actual hash value as a hex string.
|
||||
* Finalize a hash context and store the hexadecimal representation of the
|
||||
* actual hash value as a string.
|
||||
*
|
||||
* It is not safe to update or finalize a hash context again, if it has already
|
||||
* been finalized.
|
||||
*
|
||||
* The string is always 0-terminated.
|
||||
* If size is smaller than 2 * hash_size + 1, the hex string is truncated.
|
||||
*
|
||||
* If `size` is smaller than `2 * hash_size + 1`, where `hash_size` is the
|
||||
* value returned by av_hash_get_size(), the string will be truncated.
|
||||
*
|
||||
* @param[in,out] ctx Hash context
|
||||
* @param[out] dst Where the string will be stored
|
||||
* @param[in] size Maximum number of bytes to write to `dst`
|
||||
*/
|
||||
void av_hash_final_hex(struct AVHashContext *ctx, uint8_t *dst, int size);
|
||||
|
||||
/**
|
||||
* Finalize a hash context and compute the actual hash value as a base64 string.
|
||||
* Finalize a hash context and store the Base64 representation of the
|
||||
* actual hash value as a string.
|
||||
*
|
||||
* It is not safe to update or finalize a hash context again, if it has already
|
||||
* been finalized.
|
||||
*
|
||||
* The string is always 0-terminated.
|
||||
* If size is smaller than AV_BASE64_SIZE(hash_size), the base64 string is
|
||||
* truncated.
|
||||
*
|
||||
* If `size` is smaller than AV_BASE64_SIZE(hash_size), where `hash_size` is
|
||||
* the value returned by av_hash_get_size(), the string will be truncated.
|
||||
*
|
||||
* @param[in,out] ctx Hash context
|
||||
* @param[out] dst Where the final hash value will be stored
|
||||
* @param[in] size Maximum number of bytes to write to `dst`
|
||||
*/
|
||||
void av_hash_final_b64(struct AVHashContext *ctx, uint8_t *dst, int size);
|
||||
|
||||
/**
|
||||
* Free hash context.
|
||||
* Free hash context and set hash context pointer to `NULL`.
|
||||
*
|
||||
* @param[in,out] ctx Pointer to hash context
|
||||
*/
|
||||
void av_hash_freep(struct AVHashContext **ctx);
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user