Generic Hashing API

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
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);

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]

i

Index 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]

ctx

Hash 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]

ctx

Hash 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]	ctx	Hash context
[in]	src	Data to be added to the hash context
[in]	len	Size 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]	ctx	Hash context
[out]	dst	Where 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]	ctx	Hash context
[out]	dst	Where the final hash value will be stored
[in]	size	Number 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]	ctx	Hash context
[out]	dst	Where the string will be stored
[in]	size	Maximum 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]	ctx	Hash context
[out]	dst	Where the final hash value will be stored
[in]	size	Maximum 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]

ctx

Pointer to hash context

Examples

ffhash.c.