FFmpeg
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Files | Macros | Functions
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, int 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) {
}
// 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

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

#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 157 of file hash.h.

Referenced by av_hash_final_b64(), av_hash_final_bin(), av_hash_final_hex(), decode(), finish(), and writer_print_data_hash().

Function Documentation

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.

Definition at line 100 of file hash.c.

Referenced by decode(), and main().

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

Definition at line 84 of file hash.c.

Referenced by main(), and usage().

const char* av_hash_get_name ( const struct AVHashContext ctx)

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

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
void av_hash_init ( struct AVHashContext ctx)

Initialize or reset a hash context.

Parameters
[in,out]ctxHash context

Definition at line 137 of file hash.c.

Referenced by check(), decode(), main(), and writer_print_data_hash().

void av_hash_update ( struct AVHashContext ctx,
const uint8_t src,
int  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

Definition at line 159 of file hash.c.

Referenced by check(), decode(), main(), and writer_print_data_hash().

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

Definition at line 183 of file hash.c.

Referenced by av_hash_final_b64(), av_hash_final_bin(), and av_hash_final_hex().

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

Definition at line 204 of file hash.c.

Referenced by main().

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

Definition at line 215 of file hash.c.

Referenced by decode(), finish(), main(), and writer_print_data_hash().

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

Definition at line 225 of file hash.c.

Referenced by finish(), and main().

void av_hash_freep ( struct AVHashContext **  ctx)

Free hash context and set hash context pointer to NULL.

Parameters
[in,out]ctxPointer to hash context

Definition at line 238 of file hash.c.

Referenced by decode(), and main().