FFmpeg 5.1.6
Files | Macros | Functions

An abstraction layer for all hash functions supported by libavutil. More...

Files

file  hash.h
 Generic hashing API.
 

Macros

#define AV_HASH_MAX_SIZE   64
 Maximum value that av_hash_get_size() will currently return. More...
 

Functions

int av_hash_alloc (struct AVHashContext **ctx, const char *name)
 Allocate a hash context for the algorithm specified by name. More...
 
const char * av_hash_names (int i)
 Get the names of available hash algorithms. More...
 
const char * av_hash_get_name (const struct AVHashContext *ctx)
 Get the name of the algorithm corresponding to the given hash context. More...
 
int av_hash_get_size (const struct AVHashContext *ctx)
 Get the size of the resulting hash value in bytes. More...
 
void av_hash_init (struct AVHashContext *ctx)
 Initialize or reset a hash context. More...
 
void av_hash_update (struct AVHashContext *ctx, const uint8_t *src, size_t len)
 Update a hash context with additional data. More...
 
void av_hash_final (struct AVHashContext *ctx, uint8_t *dst)
 Finalize a hash context and compute the actual hash value. More...
 
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. More...
 
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. More...
 
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. More...
 
void av_hash_freep (struct AVHashContext **ctx)
 Free hash context and set hash context pointer to NULL. More...
 

Detailed Description

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 all hash functions implemented in libavutil. If you just need to use one particular hash function, use the individual hash directly.

Code

A basic template for using the Generic Hashing API follows:

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
// 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
#define AVERROR(e)
Definition: error.h:45
void av_hash_freep(struct AVHashContext **ctx)
Free hash context and set hash context pointer to NULL.
void av_hash_init(struct AVHashContext *ctx)
Initialize or reset a hash context.
int av_hash_get_size(const struct AVHashContext *ctx)
Get the size of the resulting hash value in bytes.
void av_hash_update(struct AVHashContext *ctx, const uint8_t *src, size_t len)
Update a hash context with additional data.
int av_hash_alloc(struct AVHashContext **ctx, const char *name)
Allocate a hash context for the algorithm specified by name.
void av_hash_final(struct AVHashContext *ctx, uint8_t *dst)
Finalize a hash context and compute the actual hash value.
void * av_malloc(size_t size) av_malloc_attrib
Allocate a memory block with alignment suitable for all memory accesses (including vectors if availab...

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 Murmur3 for more information.

Macro Definition Documentation

◆ AV_HASH_MAX_SIZE

#define AV_HASH_MAX_SIZE   64

Maximum value that av_hash_get_size() will currently return.

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.
Examples
ffhash.c.

Definition at line 156 of file hash.h.

Function Documentation

◆ av_hash_alloc()

int av_hash_alloc ( struct AVHashContext **  ctx,
const char *  name 
)

Allocate a hash context for the algorithm specified by name.

Returns
>= 0 for success, a negative error code for failure
Note
The context is not initialized after a call to this function; you must call av_hash_init() to do so.
Examples
ffhash.c.

◆ av_hash_names()

const char * av_hash_names ( int  i)

Get the names of available hash algorithms.

This function can be used to enumerate the algorithms.

Parameters
[in]iIndex of the hash algorithm, starting from 0
Returns
Pointer to a static string or NULL if i is out of range
Examples
ffhash.c.

◆ av_hash_get_name()

const char * av_hash_get_name ( const struct AVHashContext *  ctx)

Get the name of the algorithm corresponding to the given hash context.

Examples
ffhash.c.

◆ av_hash_get_size()

int av_hash_get_size ( const struct AVHashContext *  ctx)

Get the size of the resulting hash value in bytes.

The maximum value this function will currently return is available as macro AV_HASH_MAX_SIZE.

Parameters
[in]ctxHash context
Returns
Size of the hash value in bytes

◆ av_hash_init()

void av_hash_init ( struct AVHashContext *  ctx)

Initialize or reset a hash context.

Parameters
[in,out]ctxHash context
Examples
ffhash.c.

◆ av_hash_update()

void av_hash_update ( struct AVHashContext *  ctx,
const uint8_t *  src,
size_t  len 
)

Update a hash context with additional data.

Parameters
[in,out]ctxHash context
[in]srcData to be added to the hash context
[in]lenSize of the additional data
Examples
ffhash.c.

◆ av_hash_final()

void av_hash_final ( struct AVHashContext *  ctx,
uint8_t *  dst 
)

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.

Parameters
[in,out]ctxHash context
[out]dstWhere the final hash value will be stored
See also
av_hash_final_bin() provides an alternative API

◆ av_hash_final_bin()

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.

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.

Parameters
[in,out]ctxHash context
[out]dstWhere the final hash value will be stored
[in]sizeNumber of bytes to write to dst

◆ av_hash_final_hex()

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.

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, where hash_size is the value returned by av_hash_get_size(), the string will be truncated.

Parameters
[in,out]ctxHash context
[out]dstWhere the string will be stored
[in]sizeMaximum number of bytes to write to dst
Examples
ffhash.c.

◆ av_hash_final_b64()

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.

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), where hash_size is the value returned by av_hash_get_size(), the string will be truncated.

Parameters
[in,out]ctxHash context
[out]dstWhere the final hash value will be stored
[in]sizeMaximum number of bytes to write to dst
Examples
ffhash.c.

◆ av_hash_freep()

void av_hash_freep ( struct AVHashContext **  ctx)

Free hash context and set hash context pointer to NULL.

Parameters
[in,out]ctxPointer to hash context
Examples
ffhash.c.