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