FFmpeg
Main Page
Related Pages
Modules
Namespaces
Data Structures
Files
Examples
File List
Globals
All
Data Structures
Namespaces
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
libavutil
dict.h
Go to the documentation of this file.
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 */
Generated on Wed Jul 10 2013 23:48:15 for FFmpeg by
1.8.2