dict.h 8.1 KB

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