Details | Last modification | View Log | RSS feed
| Rev | Author | Line No. | Line |
|---|---|---|---|
| 4349 | Serge | 1 | /* |
| 2 | * |
||
| 3 | * This file is part of FFmpeg. |
||
| 4 | * |
||
| 5 | * FFmpeg is free software; you can redistribute it and/or |
||
| 6 | * modify it under the terms of the GNU Lesser General Public |
||
| 7 | * License as published by the Free Software Foundation; either |
||
| 8 | * version 2.1 of the License, or (at your option) any later version. |
||
| 9 | * |
||
| 10 | * FFmpeg is distributed in the hope that it will be useful, |
||
| 11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
||
| 12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
||
| 13 | * Lesser General Public License for more details. |
||
| 14 | * |
||
| 15 | * You should have received a copy of the GNU Lesser General Public |
||
| 16 | * License along with FFmpeg; if not, write to the Free Software |
||
| 17 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
||
| 18 | */ |
||
| 19 | |||
| 20 | /** |
||
| 21 | * @file |
||
| 22 | * Public dictionary API. |
||
| 23 | * @deprecated |
||
| 24 | * AVDictionary is provided for compatibility with libav. It is both in |
||
| 25 | * implementation as well as API inefficient. It does not scale and is |
||
| 26 | * extremely slow with large dictionaries. |
||
| 27 | * It is recommended that new code uses our tree container from tree.c/h |
||
| 28 | * where applicable, which uses AVL trees to achieve O(log n) performance. |
||
| 29 | */ |
||
| 30 | |||
| 31 | #ifndef AVUTIL_DICT_H |
||
| 32 | #define AVUTIL_DICT_H |
||
| 33 | |||
| 34 | /** |
||
| 35 | * @addtogroup lavu_dict AVDictionary |
||
| 36 | * @ingroup lavu_data |
||
| 37 | * |
||
| 38 | * @brief Simple key:value store |
||
| 39 | * |
||
| 40 | * @{ |
||
| 41 | * Dictionaries are used for storing key:value pairs. To create |
||
| 42 | * an AVDictionary, simply pass an address of a NULL pointer to |
||
| 43 | * av_dict_set(). NULL can be used as an empty dictionary wherever |
||
| 44 | * a pointer to an AVDictionary is required. |
||
| 45 | * Use av_dict_get() to retrieve an entry or iterate over all |
||
| 46 | * entries and finally av_dict_free() to free the dictionary |
||
| 47 | * and all its contents. |
||
| 48 | * |
||
| 49 | * @code |
||
| 50 | * AVDictionary *d = NULL; // "create" an empty dictionary |
||
| 51 | * av_dict_set(&d, "foo", "bar", 0); // add an entry |
||
| 52 | * |
||
| 53 | * char *k = av_strdup("key"); // if your strings are already allocated, |
||
| 54 | * char *v = av_strdup("value"); // you can avoid copying them like this |
||
| 55 | * av_dict_set(&d, k, v, AV_DICT_DONT_STRDUP_KEY | AV_DICT_DONT_STRDUP_VAL); |
||
| 56 | * |
||
| 57 | * AVDictionaryEntry *t = NULL; |
||
| 58 | * while (t = av_dict_get(d, "", t, AV_DICT_IGNORE_SUFFIX)) { |
||
| 59 | * <....> // iterate over all entries in d |
||
| 60 | * } |
||
| 61 | * |
||
| 62 | * av_dict_free(&d); |
||
| 63 | * @endcode |
||
| 64 | * |
||
| 65 | */ |
||
| 66 | |||
| 67 | #define AV_DICT_MATCH_CASE 1 |
||
| 68 | #define AV_DICT_IGNORE_SUFFIX 2 |
||
| 69 | #define AV_DICT_DONT_STRDUP_KEY 4 /**< Take ownership of a key that's been |
||
| 70 | allocated with av_malloc() and children. */ |
||
| 71 | #define AV_DICT_DONT_STRDUP_VAL 8 /**< Take ownership of a value that's been |
||
| 72 | allocated with av_malloc() and chilren. */ |
||
| 73 | #define AV_DICT_DONT_OVERWRITE 16 ///< Don't overwrite existing entries. |
||
| 74 | #define AV_DICT_APPEND 32 /**< If the entry already exists, append to it. Note that no |
||
| 75 | delimiter is added, the strings are simply concatenated. */ |
||
| 76 | |||
| 77 | typedef struct AVDictionaryEntry { |
||
| 78 | char *key; |
||
| 79 | char *value; |
||
| 80 | } AVDictionaryEntry; |
||
| 81 | |||
| 82 | typedef struct AVDictionary AVDictionary; |
||
| 83 | |||
| 84 | /** |
||
| 85 | * Get a dictionary entry with matching key. |
||
| 86 | * |
||
| 87 | * @param prev Set to the previous matching element to find the next. |
||
| 88 | * If set to NULL the first matching element is returned. |
||
| 89 | * @param flags Allows case as well as suffix-insensitive comparisons. |
||
| 90 | * @return Found entry or NULL, changing key or value leads to undefined behavior. |
||
| 91 | */ |
||
| 92 | AVDictionaryEntry * |
||
| 93 | av_dict_get(AVDictionary *m, const char *key, const AVDictionaryEntry *prev, int flags); |
||
| 94 | |||
| 95 | /** |
||
| 96 | * Get number of entries in dictionary. |
||
| 97 | * |
||
| 98 | * @param m dictionary |
||
| 99 | * @return number of entries in dictionary |
||
| 100 | */ |
||
| 101 | int av_dict_count(const AVDictionary *m); |
||
| 102 | |||
| 103 | /** |
||
| 104 | * Set the given entry in *pm, overwriting an existing entry. |
||
| 105 | * |
||
| 106 | * @param pm pointer to a pointer to a dictionary struct. If *pm is NULL |
||
| 107 | * a dictionary struct is allocated and put in *pm. |
||
| 108 | * @param key entry key to add to *pm (will be av_strduped depending on flags) |
||
| 109 | * @param value entry value to add to *pm (will be av_strduped depending on flags). |
||
| 110 | * Passing a NULL value will cause an existing entry to be deleted. |
||
| 111 | * @return >= 0 on success otherwise an error code <0 |
||
| 112 | */ |
||
| 113 | int av_dict_set(AVDictionary **pm, const char *key, const char *value, int flags); |
||
| 114 | |||
| 115 | /** |
||
| 116 | * Parse the key/value pairs list and add to a dictionary. |
||
| 117 | * |
||
| 118 | * @param key_val_sep a 0-terminated list of characters used to separate |
||
| 119 | * key from value |
||
| 120 | * @param pairs_sep a 0-terminated list of characters used to separate |
||
| 121 | * two pairs from each other |
||
| 122 | * @param flags flags to use when adding to dictionary. |
||
| 123 | * AV_DICT_DONT_STRDUP_KEY and AV_DICT_DONT_STRDUP_VAL |
||
| 124 | * are ignored since the key/value tokens will always |
||
| 125 | * be duplicated. |
||
| 126 | * @return 0 on success, negative AVERROR code on failure |
||
| 127 | */ |
||
| 128 | int av_dict_parse_string(AVDictionary **pm, const char *str, |
||
| 129 | const char *key_val_sep, const char *pairs_sep, |
||
| 130 | int flags); |
||
| 131 | |||
| 132 | /** |
||
| 133 | * Copy entries from one AVDictionary struct into another. |
||
| 134 | * @param dst pointer to a pointer to a AVDictionary struct. If *dst is NULL, |
||
| 135 | * this function will allocate a struct for you and put it in *dst |
||
| 136 | * @param src pointer to source AVDictionary struct |
||
| 137 | * @param flags flags to use when setting entries in *dst |
||
| 138 | * @note metadata is read using the AV_DICT_IGNORE_SUFFIX flag |
||
| 139 | */ |
||
| 140 | void av_dict_copy(AVDictionary **dst, AVDictionary *src, int flags); |
||
| 141 | |||
| 142 | /** |
||
| 143 | * Free all the memory allocated for an AVDictionary struct |
||
| 144 | * and all keys and values. |
||
| 145 | */ |
||
| 146 | void av_dict_free(AVDictionary **m); |
||
| 147 | |||
| 148 | /** |
||
| 149 | * @} |
||
| 150 | */ |
||
| 151 | |||
| 152 | #endif /* AVUTIL_DICT_H */ |