Skip to content
Projects
Groups
Snippets
Help
Loading...
Sign in / Register
Toggle navigation
F
ffmpeg
Project
Project
Details
Activity
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
0
Issues
0
List
Board
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Charts
Packages
Packages
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
submodule
ffmpeg
Commits
f29ffbc8
Commit
f29ffbc8
authored
Aug 02, 2016
by
Timothy Gu
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
avutil/hash: Add more detailed Doxygen documentation
parent
613c8629
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
150 additions
and
21 deletions
+150
-21
Doxyfile
doc/Doxyfile
+1
-1
hash.h
libavutil/hash.h
+149
-20
No files found.
doc/Doxyfile
View file @
f29ffbc8
...
...
@@ -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
...
...
libavutil/hash.h
View file @
f29ffbc8
...
...
@@ -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 i
ndex 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 I
ndex 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
);
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment