Simple key:value store. More...

Data Structures

struct  AVDictionaryEntry
 

Macros

#define AV_DICT_MATCH_CASE   1
 
#define AV_DICT_IGNORE_SUFFIX   2
 
#define AV_DICT_DONT_STRDUP_KEY   4
 Take ownership of a key that's been allocated with av_malloc() and children. More...
 
#define AV_DICT_DONT_STRDUP_VAL   8
 Take ownership of a value that's been allocated with av_malloc() and children. More...
 
#define AV_DICT_DONT_OVERWRITE   16
 Don't overwrite existing entries. More...
 
#define AV_DICT_APPEND   32
 If the entry already exists, append to it. More...
 

Typedefs

typedef struct AVDictionary AVDictionary
 

Functions

AVDictionaryEntryav_dict_get (const AVDictionary *m, const char *key, const AVDictionaryEntry *prev, int flags)
 Get a dictionary entry with matching key. More...
 
int av_dict_count (const AVDictionary *m)
 Get number of entries in dictionary. More...
 
int av_dict_set (AVDictionary **pm, const char *key, const char *value, int flags)
 Set the given entry in *pm, overwriting an existing entry. More...
 
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 to a dictionary. More...
 
int av_dict_copy (AVDictionary **dst, const AVDictionary *src, int flags)
 Copy entries from one AVDictionary struct into another. More...
 
void av_dict_free (AVDictionary **m)
 Free all the memory allocated for an AVDictionary struct and all keys and values. More...
 

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. Use av_dict_get() to retrieve an entry or iterate over all entries and finally av_dict_free() to free the dictionary and all its contents.

AVDictionary *d = NULL; // "create" an empty dictionary
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
while (t = av_dict_get(d, "", t, AV_DICT_IGNORE_SUFFIX)) {
<....> // iterate over all entries in d
}

Macro Definition Documentation

◆ AV_DICT_MATCH_CASE

#define AV_DICT_MATCH_CASE   1

Definition at line 59 of file dict.h.

◆ AV_DICT_IGNORE_SUFFIX

#define AV_DICT_IGNORE_SUFFIX   2
Examples:
metadata.c.

Definition at line 60 of file dict.h.

Referenced by main().

◆ AV_DICT_DONT_STRDUP_KEY

#define AV_DICT_DONT_STRDUP_KEY   4

Take ownership of a key that's been allocated with av_malloc() and children.

Definition at line 61 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() and children.

Definition at line 64 of file dict.h.

◆ AV_DICT_DONT_OVERWRITE

#define AV_DICT_DONT_OVERWRITE   16

Don't overwrite existing entries.

Definition at line 67 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 68 of file dict.h.

Typedef Documentation

◆ AVDictionary

typedef struct AVDictionary AVDictionary

Definition at line 77 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.

Parameters
prevSet to the previous matching element to find the next. If set to NULL the first matching element is returned.
flagsAllows case as well as suffix-insensitive comparisons.
Returns
Found entry or NULL, changing key or value leads to undefined behavior.
Examples:
metadata.c.

Referenced by main().

◆ av_dict_count()

int av_dict_count ( const AVDictionary m)

Get number of entries in dictionary.

Parameters
mdictionary
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.

Parameters
pmpointer to a pointer to a dictionary struct. If *pm is NULL a dictionary struct is allocated and put in *pm.
keyentry key to add to *pm (will be av_strduped depending on flags)
valueentry value to add to *pm (will be av_strduped 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:
filter_audio.c.

Referenced by init_filter_graph().

◆ 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 to a dictionary.

Parameters
key_val_sepa 0-terminated list of characters used to separate key from value
pairs_sepa 0-terminated list of characters used to separate two pairs from each other
flagsflags to use when adding to 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.

Parameters
dstpointer to a pointer to a AVDictionary struct. If *dst is NULL, this function will allocate a struct for you and put it in *dst
srcpointer to source AVDictionary struct
flagsflags to use when setting entries in *dst
Note
metadata is read using the AV_DICT_IGNORE_SUFFIX flag
Returns
0 on success, negative AVERROR code on failure. If dst was allocated by this function, callers should free the associated memory.

◆ av_dict_free()

void av_dict_free ( AVDictionary **  m)

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

Examples:
filter_audio.c.

Referenced by init_filter_graph().