1
0
mirror of https://github.com/FFmpeg/FFmpeg.git synced 2024-12-23 12:43:46 +02:00

dict: extend documentation.

This commit is contained in:
Anton Khirnov 2011-07-08 08:27:53 +02:00
parent fdaf1d0640
commit 8c28e01d31

View File

@ -25,10 +25,42 @@
#ifndef AVUTIL_DICT_H
#define AVUTIL_DICT_H
/**
* @defgroup dict_api Public Dictionary API
* @{
* 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.
*
* @code
* 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
* av_dict_set(&d, k, v, AV_DICT_DONT_STRDUP_KEY | AV_DICT_DONT_STRDUP_VAL);
*
* AVDictionaryEntry *t = NULL;
* while (t = av_dict_get(d, "", t, AV_DICT_IGNORE_SUFFIX)) {
* <....> // iterate over all entries in d
* }
*
* av_dict_free(&d);
* @endcode
*
* @}
*/
#define AV_DICT_MATCH_CASE 1
#define AV_DICT_IGNORE_SUFFIX 2
#define AV_DICT_DONT_STRDUP_KEY 4
#define AV_DICT_DONT_STRDUP_VAL 8
#define AV_DICT_DONT_STRDUP_KEY 4 /**< Take ownership of a key that's been
allocated with av_malloc() and children. */
#define AV_DICT_DONT_STRDUP_VAL 8 /**< Take ownership of a value that's been
allocated with av_malloc() and chilren. */
#define AV_DICT_DONT_OVERWRITE 16 ///< Don't overwrite existing entries.
#define AV_DICT_APPEND 32 /**< If the entry already exists, append to it. Note that no
delimiter is added, the strings are simply concatenated. */
@ -74,7 +106,8 @@ int av_dict_set(AVDictionary **pm, const char *key, const char *value, int flags
void av_dict_copy(AVDictionary **dst, AVDictionary *src, int flags);
/**
* Free all the memory allocated for an AVDictionary struct.
* Free all the memory allocated for an AVDictionary struct
* and all keys and values.
*/
void av_dict_free(AVDictionary **m);