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. To create
43  * an AVDictionary, simply pass an address of a NULL pointer to
44  * av_dict_set(). NULL can be used as an empty dictionary wherever
45  * a pointer to an AVDictionary is required.
46  * Use av_dict_get() to retrieve an entry or iterate over all
47  * entries and finally av_dict_free() to free the dictionary
48  * and all its contents.
49  *
50  @code
51  AVDictionary *d = NULL; // "create" an empty dictionary
52  AVDictionaryEntry *t = NULL;
53 
54  av_dict_set(&d, "foo", "bar", 0); // add an entry
55 
56  char *k = av_strdup("key"); // if your strings are already allocated,
57  char *v = av_strdup("value"); // you can avoid copying them like this
58  av_dict_set(&d, k, v, AV_DICT_DONT_STRDUP_KEY | AV_DICT_DONT_STRDUP_VAL);
59 
60  while (t = av_dict_get(d, "", t, AV_DICT_IGNORE_SUFFIX)) {
61  <....> // iterate over all entries in d
62  }
63  av_dict_free(&d);
64  @endcode
65  */
66 
67 #define AV_DICT_MATCH_CASE 1 /**< Only get an entry with exact-case key match. Only relevant in av_dict_get(). */
68 #define AV_DICT_IGNORE_SUFFIX 2 /**< Return first entry in a dictionary whose first part corresponds to the search key,
69  ignoring the suffix of the found key string. Only relevant in av_dict_get(). */
70 #define AV_DICT_DONT_STRDUP_KEY 4 /**< Take ownership of a key that's been
71  allocated with av_malloc() or another memory allocation function. */
72 #define AV_DICT_DONT_STRDUP_VAL 8 /**< Take ownership of a value that's been
73  allocated with av_malloc() or another memory allocation function. */
74 #define AV_DICT_DONT_OVERWRITE 16 ///< Don't overwrite existing entries.
75 #define AV_DICT_APPEND 32 /**< If the entry already exists, append to it. Note that no
76  delimiter is added, the strings are simply concatenated. */
77 #define AV_DICT_MULTIKEY 64 /**< Allow to store several equal keys in the dictionary */
78 
79 typedef struct AVDictionaryEntry {
80  char *key;
81  char *value;
83 
84 typedef struct AVDictionary AVDictionary;
85 
86 /**
87  * Get a dictionary entry with matching key.
88  *
89  * The returned entry key or value must not be changed, or it will
90  * cause undefined behavior.
91  *
92  * To iterate through all the dictionary entries, you can set the matching key
93  * to the null string "" and set the AV_DICT_IGNORE_SUFFIX flag.
94  *
95  * @param prev Set to the previous matching element to find the next.
96  * If set to NULL the first matching element is returned.
97  * @param key matching key
98  * @param flags a collection of AV_DICT_* flags controlling how the entry is retrieved
99  * @return found entry or NULL in case no matching entry was found in the dictionary
100  */
101 AVDictionaryEntry *av_dict_get(const AVDictionary *m, const char *key,
102  const AVDictionaryEntry *prev, int flags);
103 
104 /**
105  * Get number of entries in dictionary.
106  *
107  * @param m dictionary
108  * @return number of entries in dictionary
109  */
110 int av_dict_count(const AVDictionary *m);
111 
112 /**
113  * Set the given entry in *pm, overwriting an existing entry.
114  *
115  * Note: If AV_DICT_DONT_STRDUP_KEY or AV_DICT_DONT_STRDUP_VAL is set,
116  * these arguments will be freed on error.
117  *
118  * Warning: Adding a new entry to a dictionary invalidates all existing entries
119  * previously returned with av_dict_get.
120  *
121  * @param pm pointer to a pointer to a dictionary struct. If *pm is NULL
122  * a dictionary struct is allocated and put in *pm.
123  * @param key entry key to add to *pm (will either be av_strduped or added as a new key depending on flags)
124  * @param value entry value to add to *pm (will be av_strduped or added as a new key depending on flags).
125  * Passing a NULL value will cause an existing entry to be deleted.
126  * @return >= 0 on success otherwise an error code <0
127  */
128 int av_dict_set(AVDictionary **pm, const char *key, const char *value, int flags);
129 
130 /**
131  * Convenience wrapper for av_dict_set that converts the value to a string
132  * and stores it.
133  *
134  * Note: If AV_DICT_DONT_STRDUP_KEY is set, key will be freed on error.
135  */
136 int av_dict_set_int(AVDictionary **pm, const char *key, int64_t value, int flags);
137 
138 /**
139  * Parse the key/value pairs list and add the parsed entries to a dictionary.
140  *
141  * In case of failure, all the successfully set entries are stored in
142  * *pm. You may need to manually free the created dictionary.
143  *
144  * @param key_val_sep a 0-terminated list of characters used to separate
145  * key from value
146  * @param pairs_sep a 0-terminated list of characters used to separate
147  * two pairs from each other
148  * @param flags flags to use when adding to dictionary.
149  * AV_DICT_DONT_STRDUP_KEY and AV_DICT_DONT_STRDUP_VAL
150  * are ignored since the key/value tokens will always
151  * be duplicated.
152  * @return 0 on success, negative AVERROR code on failure
153  */
154 int av_dict_parse_string(AVDictionary **pm, const char *str,
155  const char *key_val_sep, const char *pairs_sep,
156  int flags);
157 
158 /**
159  * Copy entries from one AVDictionary struct into another.
160  * @param dst pointer to a pointer to a AVDictionary struct. If *dst is NULL,
161  * this function will allocate a struct for you and put it in *dst
162  * @param src pointer to source AVDictionary struct
163  * @param flags flags to use when setting entries in *dst
164  * @note metadata is read using the AV_DICT_IGNORE_SUFFIX flag
165  * @return 0 on success, negative AVERROR code on failure. If dst was allocated
166  * by this function, callers should free the associated memory.
167  */
168 int av_dict_copy(AVDictionary **dst, const AVDictionary *src, int flags);
169 
170 /**
171  * Free all the memory allocated for an AVDictionary struct
172  * and all keys and values.
173  */
174 void av_dict_free(AVDictionary **m);
175 
176 /**
177  * Get dictionary entries as a string.
178  *
179  * Create a string containing dictionary's entries.
180  * Such string may be passed back to av_dict_parse_string().
181  * @note String is escaped with backslashes ('\').
182  *
183  * @param[in] m dictionary
184  * @param[out] buffer Pointer to buffer that will be allocated with string containg entries.
185  * Buffer must be freed by the caller when is no longer needed.
186  * @param[in] key_val_sep character used to separate key from value
187  * @param[in] pairs_sep character used to separate two pairs from each other
188  * @return >= 0 on success, negative on error
189  * @warning Separators cannot be neither '\\' nor '\0'. They also cannot be the same.
190  */
191 int av_dict_get_string(const AVDictionary *m, char **buffer,
192  const char key_val_sep, const char pairs_sep);
193 
194 /**
195  * @}
196  */
197 
198 #endif /* AVUTIL_DICT_H */
av_dict_count
int av_dict_count(const AVDictionary *m)
Get number of entries in dictionary.
Definition: dict.c:36
AVDictionary
Definition: dict.c:31
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:41
AVDictionaryEntry::key
char * key
Definition: dict.h:80
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:208
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:185
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:152
AVDictionaryEntry
Definition: dict.h:79
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:71
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:235
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:222
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:81