Loading...
Searching...
No Matches
AVDictionary
libavutil » Data Structures

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);
av_dict_free
void av_dict_free(AVDictionary **m)
Free all the memory allocated for an AVDictionary struct and all keys and values.
AVDictionary
struct AVDictionary AVDictionary
Definition dict.h:94
av_dict_iterate
const AVDictionaryEntry * av_dict_iterate(const AVDictionary *m, const AVDictionaryEntry *prev)
Iterate over a dictionary.
AV_DICT_DONT_STRDUP_VAL
#define AV_DICT_DONT_STRDUP_VAL
Take ownership of a value that's been allocated with av_malloc() or another memory allocation functio...
Definition dict.h:79
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.
AV_DICT_DONT_STRDUP_KEY
#define AV_DICT_DONT_STRDUP_KEY
Take ownership of a key that's been allocated with av_malloc() or another memory allocation function.
Definition dict.h:77
av_strdup
char * av_strdup(const char *s) av_malloc_attrib
Duplicate a string.
AVDictionaryEntry
Definition dict.h:89

## 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