AVDictionary

Simple key:value store. More...

Data Structures
struct	AVDictionaryEntry

Typedefs
typedef struct AVDictionary	AVDictionary

Functions
AVDictionaryEntry *	av_dict_get (const AVDictionary *m, const char *key, const AVDictionaryEntry *prev, int flags)
	Get a dictionary entry with matching key.
const AVDictionaryEntry *	av_dict_iterate (const AVDictionary *m, const AVDictionaryEntry *prev)
	Iterate over a dictionary.
int	av_dict_count (const AVDictionary *m)
	Get number of entries in dictionary.
int	av_dict_set (AVDictionary **pm, const char *key, const char *value, int flags)
	Set the given entry in *pm, overwriting an existing entry.
int	av_dict_set_int (AVDictionary **pm, const char *key, int64_t value, int flags)
	Convenience wrapper for av_dict_set() that converts the value to a string and stores it.
int	av_dict_parse_string (AVDictionary **pm, const char *str, const char *key_val_sep, const char *pairs_sep, int flags)
	Parse the key/value pairs list and add the parsed entries to a dictionary.
int	av_dict_copy (AVDictionary **dst, const AVDictionary *src, int flags)
	Copy entries from one AVDictionary struct into another.
void	av_dict_free (AVDictionary **m)
	Free all the memory allocated for an AVDictionary struct and all keys and values.
int	av_dict_get_string (const AVDictionary *m, char **buffer, const char key_val_sep, const char pairs_sep)
	Get dictionary entries as a string.

AVDictionary Flags
Flags that influence behavior of the matching of keys or insertion to the dictionary.
#define	AV_DICT_MATCH_CASE   1
	Only get an entry with exact-case key match.
#define	AV_DICT_IGNORE_SUFFIX   2
	Return first entry in a dictionary whose first part corresponds to the search key, ignoring the suffix of the found key string.
#define	AV_DICT_DONT_STRDUP_KEY   4
	Take ownership of a key that's been allocated with av_malloc() or another memory allocation function.
#define	AV_DICT_DONT_STRDUP_VAL   8
	Take ownership of a value that's been allocated with av_malloc() or another memory allocation function.
#define	AV_DICT_DONT_OVERWRITE   16
	Don't overwrite existing entries.
#define	AV_DICT_APPEND   32
	If the entry already exists, append to it.
#define	AV_DICT_MULTIKEY   64
	Allow to store several equal keys in the dictionary.

Detailed Description

Simple key:value store.

Dictionaries are used for storing key-value pairs.

• To create an AVDictionary, simply pass an address of a NULL pointer to av_dict_set(). NULL can be used as an empty dictionary wherever a pointer to an AVDictionary is required.
• To insert an entry, use av_dict_set().
• Use av_dict_get() to retrieve an entry.
• To iterate over all entries, use av_dict_iterate().
• In order to free the dictionary and all its contents, use av_dict_free().

AVDictionary *d = NULL;           // "create" an empty dictionary
AVDictionaryEntry *t = NULL;
 
av_dict_set(&d, "foo", "bar", 0); // add an entry
 
char *k = av_strdup("key");       // if your strings are already allocated,
char *v = av_strdup("value");     // you can avoid copying them like this
av_dict_set(&d, k, v, AV_DICT_DONT_STRDUP_KEY | AV_DICT_DONT_STRDUP_VAL);
 
while ((t = av_dict_iterate(d, t))) {
    <....>                        // iterate over all entries in d
}
av_dict_free(&d);

Macro Definition Documentation

AV_DICT_MATCH_CASE

#define AV_DICT_MATCH_CASE   1

Only get an entry with exact-case key match.

Only relevant in av_dict_get().

Definition at line 74 of file dict.h.

AV_DICT_IGNORE_SUFFIX

#define AV_DICT_IGNORE_SUFFIX   2

Return first entry in a dictionary whose first part corresponds to the search key, ignoring the suffix of the found key string.

Only relevant in av_dict_get().

Definition at line 76 of file dict.h.

AV_DICT_DONT_STRDUP_KEY

#define AV_DICT_DONT_STRDUP_KEY   4

Take ownership of a key that's been allocated with av_malloc() or another memory allocation function.

Definition at line 78 of file dict.h.

AV_DICT_DONT_STRDUP_VAL

#define AV_DICT_DONT_STRDUP_VAL   8

Take ownership of a value that's been allocated with av_malloc() or another memory allocation function.

Definition at line 80 of file dict.h.

AV_DICT_DONT_OVERWRITE

#define AV_DICT_DONT_OVERWRITE   16

Don't overwrite existing entries.

Definition at line 81 of file dict.h.

AV_DICT_APPEND

#define AV_DICT_APPEND   32

If the entry already exists, append to it.

Note that no delimiter is added, the strings are simply concatenated.

Definition at line 83 of file dict.h.

AV_DICT_MULTIKEY

#define AV_DICT_MULTIKEY   64

Allow to store several equal keys in the dictionary.

Definition at line 84 of file dict.h.

Typedef Documentation

AVDictionary

typedef struct AVDictionary AVDictionary

Definition at line 94 of file dict.h.

Function Documentation

av_dict_get()

AVDictionaryEntry * av_dict_get	(	const AVDictionary *	m,
		const char *	key,
		const AVDictionaryEntry *	prev,
		int	flags
	)

Get a dictionary entry with matching key.

The returned entry key or value must not be changed, or it will cause undefined behavior.

Parameters

prev	Set to the previous matching element to find the next. If set to NULL the first matching element is returned.
key	Matching key
flags	A collection of AV_DICT_* flags controlling how the entry is retrieved

Returns

Found entry or NULL in case no matching entry was found in the dictionary

Examples

qsv_transcode.c.

Referenced by dec_enc(), and dynamic_set_parameter().

av_dict_iterate()

const AVDictionaryEntry * av_dict_iterate	(	const AVDictionary *	m,
		const AVDictionaryEntry *	prev
	)

Iterate over a dictionary.

Iterates through all entries in the dictionary.

Warning

The returned AVDictionaryEntry key/value must not be changed.

As av_dict_set() invalidates all previous entries returned by this function, it must not be called while iterating over the dict.

Typical usage:

const AVDictionaryEntry *e = NULL;
while ((e = av_dict_iterate(m, e))) {
    // ...
}

Parameters

m	The dictionary to iterate over
prev	Pointer to the previous AVDictionaryEntry, NULL initially

Return values

AVDictionaryEntry*	The next element in the dictionary
NULL	No more elements in the dictionary

Examples

show_metadata.c.

Referenced by main().

av_dict_count()

int av_dict_count

(

const AVDictionary *

m

)

Get number of entries in dictionary.

Parameters

m	dictionary

Returns

number of entries in dictionary

av_dict_set()

int av_dict_set	(	AVDictionary **	pm,
		const char *	key,
		const char *	value,
		int	flags
	)

Set the given entry in *pm, overwriting an existing entry.

Note: If AV_DICT_DONT_STRDUP_KEY or AV_DICT_DONT_STRDUP_VAL is set, these arguments will be freed on error.

Warning

Adding a new entry to a dictionary invalidates all existing entries previously returned with av_dict_get() or av_dict_iterate().

Parameters

pm	Pointer to a pointer to a dictionary struct. If *pm is NULL a dictionary struct is allocated and put in *pm.
key	Entry key to add to *pm (will either be av_strduped or added as a new key depending on flags)
value	Entry value to add to *pm (will be av_strduped or added as a new key depending on flags). Passing a NULL value will cause an existing entry to be deleted.

Returns

>= 0 on success otherwise an error code <0

Examples

extract_mvs.c, filter_audio.c, mux.c, and qsv_transcode.c.

Referenced by init_filter_graph(), main(), open_codec_context(), and str_to_dict().

av_dict_set_int()

int av_dict_set_int	(	AVDictionary **	pm,
		const char *	key,
		int64_t	value,
		int	flags
	)

Convenience wrapper for av_dict_set() that converts the value to a string and stores it.

Note: If AV_DICT_DONT_STRDUP_KEY is set, key will be freed on error.

av_dict_parse_string()

int av_dict_parse_string	(	AVDictionary **	pm,
		const char *	str,
		const char *	key_val_sep,
		const char *	pairs_sep,
		int	flags
	)

Parse the key/value pairs list and add the parsed entries to a dictionary.

In case of failure, all the successfully set entries are stored in *pm. You may need to manually free the created dictionary.

Parameters

key_val_sep	A 0-terminated list of characters used to separate key from value
pairs_sep	A 0-terminated list of characters used to separate two pairs from each other
flags	Flags to use when adding to the dictionary. AV_DICT_DONT_STRDUP_KEY and AV_DICT_DONT_STRDUP_VAL are ignored since the key/value tokens will always be duplicated.

Returns

0 on success, negative AVERROR code on failure

av_dict_copy()

int av_dict_copy	(	AVDictionary **	dst,
		const AVDictionary *	src,
		int	flags
	)

Copy entries from one AVDictionary struct into another.

Note

Metadata is read using the AV_DICT_IGNORE_SUFFIX flag

Parameters

dst	Pointer to a pointer to a AVDictionary struct to copy into. If *dst is NULL, this function will allocate a struct for you and put it in *dst
src	Pointer to the source AVDictionary struct to copy items from.
flags	Flags to use when setting entries in *dst

Returns

0 on success, negative AVERROR code on failure. If dst was allocated by this function, callers should free the associated memory.

Examples

mux.c.

Referenced by open_audio(), and open_video().

av_dict_free()

void av_dict_free

(

AVDictionary **

m

)

Free all the memory allocated for an AVDictionary struct and all keys and values.

Examples

extract_mvs.c, filter_audio.c, mux.c, and qsv_transcode.c.

Referenced by dec_enc(), dynamic_set_parameter(), init_filter_graph(), open_audio(), open_codec_context(), and open_video().

av_dict_get_string()

int av_dict_get_string	(	const AVDictionary *	m,
		char **	buffer,
		const char	key_val_sep,
		const char	pairs_sep
	)

Get dictionary entries as a string.

Create a string containing dictionary's entries. Such string may be passed back to av_dict_parse_string().

Note

String is escaped with backslashes ('\').

Warning

Separators cannot be neither '\' nor '\0'. They also cannot be the same.

Parameters

[in]	m	The dictionary
[out]	buffer	Pointer to buffer that will be allocated with string containg entries. Buffer must be freed by the caller when is no longer needed.
[in]	key_val_sep	Character used to separate key from value
[in]	pairs_sep	Character used to separate two pairs from each other

Returns

>= 0 on success, negative on error