yading@11: /* yading@11: * yading@11: * This file is part of FFmpeg. yading@11: * yading@11: * FFmpeg is free software; you can redistribute it and/or yading@11: * modify it under the terms of the GNU Lesser General Public yading@11: * License as published by the Free Software Foundation; either yading@11: * version 2.1 of the License, or (at your option) any later version. yading@11: * yading@11: * FFmpeg is distributed in the hope that it will be useful, yading@11: * but WITHOUT ANY WARRANTY; without even the implied warranty of yading@11: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU yading@11: * Lesser General Public License for more details. yading@11: * yading@11: * You should have received a copy of the GNU Lesser General Public yading@11: * License along with FFmpeg; if not, write to the Free Software yading@11: * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA yading@11: */ yading@11: yading@11: /** yading@11: * @file yading@11: * Public dictionary API. yading@11: * @deprecated yading@11: * AVDictionary is provided for compatibility with libav. It is both in yading@11: * implementation as well as API inefficient. It does not scale and is yading@11: * extremely slow with large dictionaries. yading@11: * It is recommended that new code uses our tree container from tree.c/h yading@11: * where applicable, which uses AVL trees to achieve O(log n) performance. yading@11: */ yading@11: yading@11: #ifndef AVUTIL_DICT_H yading@11: #define AVUTIL_DICT_H yading@11: yading@11: /** yading@11: * @addtogroup lavu_dict AVDictionary yading@11: * @ingroup lavu_data yading@11: * yading@11: * @brief Simple key:value store yading@11: * yading@11: * @{ yading@11: * Dictionaries are used for storing key:value pairs. To create yading@11: * an AVDictionary, simply pass an address of a NULL pointer to yading@11: * av_dict_set(). NULL can be used as an empty dictionary wherever yading@11: * a pointer to an AVDictionary is required. yading@11: * Use av_dict_get() to retrieve an entry or iterate over all yading@11: * entries and finally av_dict_free() to free the dictionary yading@11: * and all its contents. yading@11: * yading@11: * @code yading@11: * AVDictionary *d = NULL; // "create" an empty dictionary yading@11: * av_dict_set(&d, "foo", "bar", 0); // add an entry yading@11: * yading@11: * char *k = av_strdup("key"); // if your strings are already allocated, yading@11: * char *v = av_strdup("value"); // you can avoid copying them like this yading@11: * av_dict_set(&d, k, v, AV_DICT_DONT_STRDUP_KEY | AV_DICT_DONT_STRDUP_VAL); yading@11: * yading@11: * AVDictionaryEntry *t = NULL; yading@11: * while (t = av_dict_get(d, "", t, AV_DICT_IGNORE_SUFFIX)) { yading@11: * <....> // iterate over all entries in d yading@11: * } yading@11: * yading@11: * av_dict_free(&d); yading@11: * @endcode yading@11: * yading@11: */ yading@11: yading@11: #define AV_DICT_MATCH_CASE 1 yading@11: #define AV_DICT_IGNORE_SUFFIX 2 yading@11: #define AV_DICT_DONT_STRDUP_KEY 4 /**< Take ownership of a key that's been yading@11: allocated with av_malloc() and children. */ yading@11: #define AV_DICT_DONT_STRDUP_VAL 8 /**< Take ownership of a value that's been yading@11: allocated with av_malloc() and chilren. */ yading@11: #define AV_DICT_DONT_OVERWRITE 16 ///< Don't overwrite existing entries. yading@11: #define AV_DICT_APPEND 32 /**< If the entry already exists, append to it. Note that no yading@11: delimiter is added, the strings are simply concatenated. */ yading@11: yading@11: typedef struct AVDictionaryEntry { yading@11: char *key; yading@11: char *value; yading@11: } AVDictionaryEntry; yading@11: yading@11: typedef struct AVDictionary AVDictionary; yading@11: yading@11: /** yading@11: * Get a dictionary entry with matching key. yading@11: * yading@11: * @param prev Set to the previous matching element to find the next. yading@11: * If set to NULL the first matching element is returned. yading@11: * @param flags Allows case as well as suffix-insensitive comparisons. yading@11: * @return Found entry or NULL, changing key or value leads to undefined behavior. yading@11: */ yading@11: AVDictionaryEntry * yading@11: av_dict_get(AVDictionary *m, const char *key, const AVDictionaryEntry *prev, int flags); yading@11: yading@11: /** yading@11: * Get number of entries in dictionary. yading@11: * yading@11: * @param m dictionary yading@11: * @return number of entries in dictionary yading@11: */ yading@11: int av_dict_count(const AVDictionary *m); yading@11: yading@11: /** yading@11: * Set the given entry in *pm, overwriting an existing entry. yading@11: * yading@11: * @param pm pointer to a pointer to a dictionary struct. If *pm is NULL yading@11: * a dictionary struct is allocated and put in *pm. yading@11: * @param key entry key to add to *pm (will be av_strduped depending on flags) yading@11: * @param value entry value to add to *pm (will be av_strduped depending on flags). yading@11: * Passing a NULL value will cause an existing entry to be deleted. yading@11: * @return >= 0 on success otherwise an error code <0 yading@11: */ yading@11: int av_dict_set(AVDictionary **pm, const char *key, const char *value, int flags); yading@11: yading@11: /** yading@11: * Parse the key/value pairs list and add to a dictionary. yading@11: * yading@11: * @param key_val_sep a 0-terminated list of characters used to separate yading@11: * key from value yading@11: * @param pairs_sep a 0-terminated list of characters used to separate yading@11: * two pairs from each other yading@11: * @param flags flags to use when adding to dictionary. yading@11: * AV_DICT_DONT_STRDUP_KEY and AV_DICT_DONT_STRDUP_VAL yading@11: * are ignored since the key/value tokens will always yading@11: * be duplicated. yading@11: * @return 0 on success, negative AVERROR code on failure yading@11: */ yading@11: int av_dict_parse_string(AVDictionary **pm, const char *str, yading@11: const char *key_val_sep, const char *pairs_sep, yading@11: int flags); yading@11: yading@11: /** yading@11: * Copy entries from one AVDictionary struct into another. yading@11: * @param dst pointer to a pointer to a AVDictionary struct. If *dst is NULL, yading@11: * this function will allocate a struct for you and put it in *dst yading@11: * @param src pointer to source AVDictionary struct yading@11: * @param flags flags to use when setting entries in *dst yading@11: * @note metadata is read using the AV_DICT_IGNORE_SUFFIX flag yading@11: */ yading@11: void av_dict_copy(AVDictionary **dst, AVDictionary *src, int flags); yading@11: yading@11: /** yading@11: * Free all the memory allocated for an AVDictionary struct yading@11: * and all keys and values. yading@11: */ yading@11: void av_dict_free(AVDictionary **m); yading@11: yading@11: /** yading@11: * @} yading@11: */ yading@11: yading@11: #endif /* AVUTIL_DICT_H */