FFmpeg
dict.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 /**
20  * @file
21  * Public dictionary API.
22  * @deprecated
23  * AVDictionary is provided for compatibility with libav. It is both in
24  * implementation as well as API inefficient. It does not scale and is
25  * extremely slow with large dictionaries.
26  * It is recommended that new code uses our tree container from tree.c/h
27  * where applicable, which uses AVL trees to achieve O(log n) performance.
28  */
29 
30 #ifndef AVUTIL_DICT_H
31 #define AVUTIL_DICT_H
32 
33 #include <stdint.h>
34 
35 /**
36  * @addtogroup lavu_dict AVDictionary
37  * @ingroup lavu_data
38  *
39  * @brief Simple key:value store
40  *
41  * @{
42  * Dictionaries are used for storing key-value pairs.
43  *
44  * - To **create an AVDictionary**, simply pass an address of a NULL
45  * pointer to av_dict_set(). NULL can be used as an empty dictionary
46  * wherever a pointer to an AVDictionary is required.
47  * - To **insert an entry**, use av_dict_set().
48  * - Use av_dict_get() to **retrieve an entry**.
49  * - To **iterate over all entries**, use av_dict_iterate().
50  * - In order to **free the dictionary and all its contents**, use av_dict_free().
51  *
52  @code
53  AVDictionary *d = NULL; // "create" an empty dictionary
54  AVDictionaryEntry *t = NULL;
55 
56  av_dict_set(&d, "foo", "bar", 0); // add an entry
57 
58  char *k = av_strdup("key"); // if your strings are already allocated,
59  char *v = av_strdup("value"); // you can avoid copying them like this
60  av_dict_set(&d, k, v, AV_DICT_DONT_STRDUP_KEY | AV_DICT_DONT_STRDUP_VAL);
61 
62  while ((t = av_dict_iterate(d, t))) {
63  <....> // iterate over all entries in d
64  }
65  av_dict_free(&d);
66  @endcode
67  */
68 
69 /**
70  * @name AVDictionary Flags
71  * Flags that influence behavior of the matching of keys or insertion to the dictionary.
72  * @{
73  */
74 #define AV_DICT_MATCH_CASE 1 /**< Only get an entry with exact-case key match. Only relevant in av_dict_get(). */
75 #define AV_DICT_IGNORE_SUFFIX 2 /**< Return first entry in a dictionary whose first part corresponds to the search key,
76  ignoring the suffix of the found key string. Only relevant in av_dict_get(). */
77 #define AV_DICT_DONT_STRDUP_KEY 4 /**< Take ownership of a key that's been
78  allocated with av_malloc() or another memory allocation function. */
79 #define AV_DICT_DONT_STRDUP_VAL 8 /**< Take ownership of a value that's been
80  allocated with av_malloc() or another memory allocation function. */
81 #define AV_DICT_DONT_OVERWRITE 16 /**< Don't overwrite existing entries. */
82 #define AV_DICT_APPEND 32 /**< If the entry already exists, append to it. Note that no
83  delimiter is added, the strings are simply concatenated. */
84 #define AV_DICT_MULTIKEY 64 /**< Allow to store several equal keys in the dictionary */
85 /**
86  * @}
87  */
88 
89 typedef struct AVDictionaryEntry {
90  char *key;
91  char *value;
92 } AVDictionaryEntry;
93 
94 typedef struct AVDictionary AVDictionary;
95 
96 /**
97  * Get a dictionary entry with matching key.
98  *
99  * The returned entry key or value must not be changed, or it will
100  * cause undefined behavior.
101  *
102  * @param prev Set to the previous matching element to find the next.
103  * If set to NULL the first matching element is returned.
104  * @param key Matching key
105  * @param flags A collection of AV_DICT_* flags controlling how the
106  * entry is retrieved
107  *
108  * @return Found entry or NULL in case no matching entry was found in the dictionary
109  */
110 AVDictionaryEntry *av_dict_get(const AVDictionary *m, const char *key,
111  const AVDictionaryEntry *prev, int flags);
112 
113 /**
114  * Iterate over a dictionary
115  *
116  * Iterates through all entries in the dictionary.
117  *
118  * @warning The returned AVDictionaryEntry key/value must not be changed.
119  *
120  * @warning As av_dict_set() invalidates all previous entries returned
121  * by this function, it must not be called while iterating over the dict.
122  *
123  * Typical usage:
124  * @code
125  * const AVDictionaryEntry *e = NULL;
126  * while ((e = av_dict_iterate(m, e))) {
127  * // ...
128  * }
129  * @endcode
130  *
131  * @param m The dictionary to iterate over
132  * @param prev Pointer to the previous AVDictionaryEntry, NULL initially
133  *
134  * @retval AVDictionaryEntry* The next element in the dictionary
135  * @retval NULL No more elements in the dictionary
136  */
137 const AVDictionaryEntry *av_dict_iterate(const AVDictionary *m,
138  const AVDictionaryEntry *prev);
139 
140 /**
141  * Get number of entries in dictionary.
142  *
143  * @param m dictionary
144  * @return number of entries in dictionary
145  */
146 int av_dict_count(const AVDictionary *m);
147 
148 /**
149  * Set the given entry in *pm, overwriting an existing entry.
150  *
151  * Note: If AV_DICT_DONT_STRDUP_KEY or AV_DICT_DONT_STRDUP_VAL is set,
152  * these arguments will be freed on error.
153  *
154  * @warning Adding a new entry to a dictionary invalidates all existing entries
155  * previously returned with av_dict_get() or av_dict_iterate().
156  *
157  * @param pm Pointer to a pointer to a dictionary struct. If *pm is NULL
158  * a dictionary struct is allocated and put in *pm.
159  * @param key Entry key to add to *pm (will either be av_strduped or added as a new key depending on flags)
160  * @param value Entry value to add to *pm (will be av_strduped or added as a new key depending on flags).
161  * Passing a NULL value will cause an existing entry to be deleted.
162  *
163  * @return >= 0 on success otherwise an error code <0
164  */
165 int av_dict_set(AVDictionary **pm, const char *key, const char *value, int flags);
166 
167 /**
168  * Convenience wrapper for av_dict_set() that converts the value to a string
169  * and stores it.
170  *
171  * Note: If ::AV_DICT_DONT_STRDUP_KEY is set, key will be freed on error.
172  */
173 int av_dict_set_int(AVDictionary **pm, const char *key, int64_t value, int flags);
174 
175 /**
176  * Parse the key/value pairs list and add the parsed entries to a dictionary.
177  *
178  * In case of failure, all the successfully set entries are stored in
179  * *pm. You may need to manually free the created dictionary.
180  *
181  * @param key_val_sep A 0-terminated list of characters used to separate
182  * key from value
183  * @param pairs_sep A 0-terminated list of characters used to separate
184  * two pairs from each other
185  * @param flags Flags to use when adding to the dictionary.
186  * ::AV_DICT_DONT_STRDUP_KEY and ::AV_DICT_DONT_STRDUP_VAL
187  * are ignored since the key/value tokens will always
188  * be duplicated.
189  *
190  * @return 0 on success, negative AVERROR code on failure
191  */
192 int av_dict_parse_string(AVDictionary **pm, const char *str,
193  const char *key_val_sep, const char *pairs_sep,
194  int flags);
195 
196 /**
197  * Copy entries from one AVDictionary struct into another.
198  *
199  * @note Metadata is read using the ::AV_DICT_IGNORE_SUFFIX flag
200  *
201  * @param dst Pointer to a pointer to a AVDictionary struct to copy into. If *dst is NULL,
202  * this function will allocate a struct for you and put it in *dst
203  * @param src Pointer to the source AVDictionary struct to copy items from.
204  * @param flags Flags to use when setting entries in *dst
205  *
206  * @return 0 on success, negative AVERROR code on failure. If dst was allocated
207  * by this function, callers should free the associated memory.
208  */
209 int av_dict_copy(AVDictionary **dst, const AVDictionary *src, int flags);
210 
211 /**
212  * Free all the memory allocated for an AVDictionary struct
213  * and all keys and values.
214  */
215 void av_dict_free(AVDictionary **m);
216 
217 /**
218  * Get dictionary entries as a string.
219  *
220  * Create a string containing dictionary's entries.
221  * Such string may be passed back to av_dict_parse_string().
222  * @note String is escaped with backslashes ('\').
223  *
224  * @warning Separators cannot be neither '\\' nor '\0'. They also cannot be the same.
225  *
226  * @param[in] m The dictionary
227  * @param[out] buffer Pointer to buffer that will be allocated with string containg entries.
228  * Buffer must be freed by the caller when is no longer needed.
229  * @param[in] key_val_sep Character used to separate key from value
230  * @param[in] pairs_sep Character used to separate two pairs from each other
231  *
232  * @return >= 0 on success, negative on error
233  */
234 int av_dict_get_string(const AVDictionary *m, char **buffer,
235  const char key_val_sep, const char pairs_sep);
236 
237 /**
238  * @}
239  */
240 
241 #endif /* AVUTIL_DICT_H */
av_dict_count
int av_dict_count(const AVDictionary *m)
Get number of entries in dictionary.
Definition: dict.c:37
AVDictionary
Definition: dict.c:32
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.
Definition: dict.c:60
AVDictionaryEntry::key
char * key
Definition: dict.h:90
key
const char * key
Definition: hwcontext_opencl.c:174
av_dict_free
void av_dict_free(AVDictionary **m)
Free all the memory allocated for an AVDictionary struct and all keys and values.
Definition: dict.c:223
value
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf default value
Definition: writing_filters.txt:86
buffer
the frame and frame reference mechanism is intended to as much as expensive copies of that data while still allowing the filters to produce correct results The data is stored in buffers represented by AVFrame structures Several references can point to the same frame buffer
Definition: filter_design.txt:49
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.
Definition: dict.c:200
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.
Definition: dict.c:167
AVDictionaryEntry
Definition: dict.h:89
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.
Definition: dict.c:86
src
INIT_CLIP pixel * src
Definition: h264pred_template.c:418
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.
Definition: dict.c:250
av_dict_copy
int av_dict_copy(AVDictionary **dst, const AVDictionary *src, int flags)
Copy entries from one AVDictionary struct into another.
Definition: dict.c:237
convert_header.str
string str
Definition: convert_header.py:20
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:561
AVDictionaryEntry::value
char * value
Definition: dict.h:91
av_dict_iterate
const AVDictionaryEntry * av_dict_iterate(const AVDictionary *m, const AVDictionaryEntry *prev)
Iterate over a dictionary.
Definition: dict.c:42
Generated on Tue Feb 28 2023 21:34:12 for FFmpeg by   doxygen 1.8.17