AVDictionary

Simple key:value store. More...

Data Structures
struct	AVDictionaryEntry

Macros
#define	AV_DICT_MATCH_CASE   1
#define	AV_DICT_IGNORE_SUFFIX   2
#define	AV_DICT_DONT_STRDUP_KEY   4
	Take ownership of a key that's been allocated with av_malloc() and children.
#define	AV_DICT_DONT_STRDUP_VAL   8
	Take ownership of a value that's been allocated with av_malloc() and chilren.
#define	AV_DICT_DONT_OVERWRITE   16
	Don't overwrite existing entries.
#define	AV_DICT_APPEND   32
	If the entry already exists, append to it.

Functions
AVDictionaryEntry *	av_dict_get (AVDictionary *m, const char *key, const AVDictionaryEntry *prev, int flags)
	Get a dictionary entry with matching key.
int	av_dict_count (const AVDictionary *m)
	Get number of entries in dictionary.
int	av_dict_set (AVDictionary **pm, const char *key, const char *value, int flags)
	Set the given entry in *pm, overwriting an existing entry.
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 to a dictionary.
void	av_dict_copy (AVDictionary **dst, AVDictionary *src, int flags)
	Copy entries from one AVDictionary struct into another.
void	av_dict_free (AVDictionary **m)
	Free all the memory allocated for an AVDictionary struct and all keys and values.

Detailed Description

Simple key:value store.

Dictionaries are used for storing key:value pairs. To create an AVDictionary, simply pass an address of a NULL pointer to av_dict_set(). NULL can be used as an empty dictionary wherever a pointer to an AVDictionary is required. Use av_dict_get() to retrieve an entry or iterate over all entries and finally av_dict_free() to free the dictionary and all its contents.

AVDictionary *d = NULL;                // "create" an empty dictionary
av_dict_set(&d, "foo", "bar", 0);      // add an entry

char *k = av_strdup("key");            // if your strings are already allocated,
char *v = av_strdup("value");          // you can avoid copying them like this
av_dict_set(&d, k, v, AV_DICT_DONT_STRDUP_KEY | AV_DICT_DONT_STRDUP_VAL);

AVDictionaryEntry *t = NULL;
while (t = av_dict_get(d, "", t, AV_DICT_IGNORE_SUFFIX)) {
    <....>                             // iterate over all entries in d
}

av_dict_free(&d);

Macro Definition Documentation

#define AV_DICT_MATCH_CASE   1

Definition at line 67 of file dict.h.

Referenced by av_dict_get(), ff_mov_read_stsd_entries(), and get_date_tag().

#define AV_DICT_IGNORE_SUFFIX   2

Examples:

doc/examples/metadata.c.

Definition at line 68 of file dict.h.

Referenced by asf_write_header1(), assert_avoptions(), av_dict_copy(), av_dict_get(), av_opt_set_dict(), caf_write_header(), config_output(), configure_filtergraph(), dump_metadata(), ff_ape_write(), ff_id3v2_write_metadata(), ff_metadata_conv(), ff_vorbiscomment_length(), ff_vorbiscomment_write(), filter_codec_opts(), flv_write_header(), id3v2_3_metadata_split_date(), lavfi_read_packet(), main(), mkv_write_tag(), mkv_write_tags(), mov_write_string_metadata(), mp3_read_header(), mpc_read_header(), open_input_file(), open_output_file(), open_slave(), read_thread(), show_tags(), smjpeg_write_header(), stream_component_open(), tta_read_header(), write_chapter(), write_globalinfo(), write_streaminfo(), write_table_entries_attrib(), write_table_redirector_legacy_attrib(), write_tags(), wv_read_header(), and X264_init().

#define AV_DICT_DONT_STRDUP_KEY   4

Take ownership of a key that's been allocated with av_malloc() and children.

Definition at line 69 of file dict.h.

Referenced by av_dict_parse_string(), av_dict_set(), decode_text_chunk(), ff_vorbis_comment(), opt_show_entries(), parse_slave_options(), read_tag(), and read_ttag().

#define AV_DICT_DONT_STRDUP_VAL   8

Take ownership of a value that's been allocated with av_malloc() and chilren.

Definition at line 71 of file dict.h.

Referenced by add_doubles_metadata(), add_metadata(), add_shorts_metadata(), add_string_metadata(), ape_tag_read_field(), asf_read_picture(), av_dict_parse_string(), av_dict_set(), avi_read_tag(), decode_text_chunk(), dtshd_read_header(), ff_rtp_chain_mux_open(), ff_sauce_read(), ff_vorbis_comment(), get_meta(), get_metadata(), modplug_load_metadata(), mov_metadata_raw(), ogm_chapter(), parse_picture(), parse_slave_options(), read_tag(), read_ttag(), smjpeg_read_header(), sox_read_header(), var_read_metadata(), and wc3_read_header().

#define AV_DICT_DONT_OVERWRITE   16

Don't overwrite existing entries.

Definition at line 73 of file dict.h.

Referenced by av_dict_set(), copy_metadata(), new_output_stream(), open_output_file(), read_ttag(), and transcode_init().

#define AV_DICT_APPEND   32

If the entry already exists, append to it.

Note that no delimiter is added, the strings are simply concatenated.

Definition at line 74 of file dict.h.

Referenced by av_dict_set(), new_video_stream(), and nist_read_header().

Function Documentation

AVDictionaryEntry* av_dict_get	(	AVDictionary *	m,
		const char *	key,
		const AVDictionaryEntry *	prev,
		int	flags
	)

Get a dictionary entry with matching key.

Parameters

prev	Set to the previous matching element to find the next. If set to NULL the first matching element is returned.
flags	Allows case as well as suffix-insensitive comparisons.

Returns

Found entry or NULL, changing key or value leads to undefined behavior.

Definition at line 39 of file dict.c.

Referenced by asf_write_header1(), assert_avoptions(), av_dict_copy(), av_dict_set(), av_dump_format(), av_opt_set_dict(), avi_write_header(), caf_write_header(), config_output(), configure_filtergraph(), dump_attachment(), dump_metadata(), dump_stream_format(), dv_init_mux(), dv_write_header(), export_orphan_timecode(), ff_ape_write(), ff_id3v2_write_apic(), ff_id3v2_write_metadata(), ff_metadata_conv(), ff_mov_read_stsd_entries(), ff_vorbiscomment_length(), ff_vorbiscomment_write(), ffm_write_header(), filter_codec_opts(), flv_write_header(), get_date_tag(), get_metadata_val(), gxf_write_header(), gxf_write_umf_material_description(), id3v1_create_tag(), id3v1_set_string(), id3v2_3_metadata_split_date(), init_input_stream(), lavfi_read_packet(), main(), mkv_write_attachments(), mkv_write_chapters(), mkv_write_header(), mkv_write_tag(), mkv_write_tags(), mkv_write_tracks(), mov_read_header(), mov_write_3gp_udta_tag(), mov_write_chpl_tag(), mov_write_header(), mov_write_int8_metadata(), mov_write_string_metadata(), mov_write_tkhd_tag(), mov_write_tmpo_tag(), mov_write_trkn_tag(), mov_write_uuidusmt_tag(), mp3_read_header(), mpc_read_header(), mpegts_write_header(), mpegts_write_pmt(), mxf_write_header(), open_input_file(), open_output_file(), open_slave(), put_meta(), read_thread(), rv10_write_header(), sap_write_header(), show_tags(), smjpeg_write_header(), sox_write_header(), stream_component_open(), transcode_init(), tta_read_header(), write_chapter(), write_globalinfo(), write_streaminfo(), write_table_entries_attrib(), write_table_redirector_legacy_attrib(), write_tags(), writer_print_integer(), writer_print_string(), wv_read_header(), and X264_init().

int av_dict_count

(

const AVDictionary *

m

)

Get number of entries in dictionary.

Parameters

m	dictionary

Returns

number of entries in dictionary

Definition at line 33 of file dict.c.

Referenced by asf_write_header1(), caf_write_header(), and dump_metadata().

int av_dict_set	(	AVDictionary **	pm,
		const char *	key,
		const char *	value,
		int	flags
	)

Set the given entry in *pm, overwriting an existing entry.

Parameters

pm	pointer to a pointer to a dictionary struct. If *pm is NULL a dictionary struct is allocated and put in *pm.
key	entry key to add to *pm (will be av_strduped depending on flags)
value	entry value to add to *pm (will be av_strduped depending on flags). Passing a NULL value will cause an existing entry to be deleted.

Returns

>= 0 on success otherwise an error code <0

Definition at line 62 of file dict.c.

Referenced by add_doubles_metadata(), add_metadata(), add_metadata_from_side_data(), add_shorts_metadata(), add_string_metadata(), add_timecode_metadata(), amf_parse_object(), ape_tag_read_field(), asf_read_header(), asf_read_picture(), av_dict_copy(), av_opt_set_dict(), avformat_find_stream_info(), avi_metadata_creation_time(), avi_read_nikon(), avi_read_tag(), avpriv_new_chapter(), build_file_streams(), config(), decode_frame(), decode_info_header(), decode_text_chunk(), dtshd_read_header(), dv_read_timecode(), export_orphan_timecode(), ff_frame_thread_encoder_init(), ff_id3v2_parse_apic(), ff_metadata_conv(), ff_parse_mpeg2_descriptor(), ff_rm_read_mdpr_codecdata(), ff_rtp_chain_mux_open(), ff_sauce_read(), ff_vorbis_comment(), ff_wms_parse_sdp_a_line(), filter_codec_opts(), filter_frame(), get_attachment(), get_meta(), get_metadata(), get_string(), get_tag(), hls_read_header(), http_open_cnx(), http_prepare_data(), id3v2_3_metadata_split_date(), init(), init_input_stream(), init_muxer(), ism_seek(), ism_write_header(), main(), matroska_convert_tag(), matroska_metadata_creation_time(), matroska_read_header(), merge_date(), modplug_load_metadata(), mov_metadata_creation_time(), mov_metadata_gnre(), mov_metadata_int8_bypass_padding(), mov_metadata_int8_no_padding(), mov_metadata_raw(), mov_metadata_track_or_disc_number(), mov_read_ftyp(), mov_read_hdlr(), mov_read_header(), mov_read_mdhd(), mov_read_tkhd(), mov_read_udta_string(), mxf_add_timecode_metadata(), new_output_stream(), new_video_stream(), nist_read_header(), nsv_parse_NSVf_header(), ogm_chapter(), open_input(), open_input_file(), open_output_file(), open_slave(), opt_bitrate(), opt_default(), opt_profile(), opt_show_entries(), opt_target(), opt_timecode(), parse_chunks(), parse_key_value_pair(), parse_picture(), parse_playlist(), parse_slave_options(), parse_tag(), parse_timecode_in_framenum_format(), prepare_sdp_description(), r3d_read_red1(), read_gab2_sub(), read_info_chunk(), read_tag(), read_ttag(), rm_read_metadata(), rpl_read_header(), rtmp_open(), sap_write_header(), sdt_cb(), select_frame(), smjpeg_read_header(), sox_read_header(), stream_component_open(), subviewer_read_header(), transcode_init(), try_decode_frame(), var_read_metadata(), vivo_read_header(), vqf_read_header(), and wc3_read_header().

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 to a dictionary.

Parameters

key_val_sep	a 0-terminated list of characters used to separate key from value
pairs_sep	a 0-terminated list of characters used to separate two pairs from each other
flags	flags to use when adding to dictionary. AV_DICT_DONT_STRDUP_KEY and AV_DICT_DONT_STRDUP_VAL are ignored since the key/value tokens will always be duplicated.

Returns

0 on success, negative AVERROR code on failure

Definition at line 139 of file dict.c.

Referenced by init(), and X264_init().

void av_dict_copy	(	AVDictionary **	dst,
		AVDictionary *	src,
		int	flags
	)

Copy entries from one AVDictionary struct into another.

Parameters

dst	pointer to a pointer to a AVDictionary struct. If *dst is NULL, this function will allocate a struct for you and put it in *dst
src	pointer to source AVDictionary struct
flags	flags to use when setting entries in *dst

Note

metadata is read using the AV_DICT_IGNORE_SUFFIX flag

Definition at line 176 of file dict.c.

Referenced by avcodec_open2(), avfilter_copy_buffer_ref_props(), avfilter_copy_frame_props(), avfilter_ref_buffer(), avformat_open_input(), copy_chapters(), copy_metadata(), ff_frame_thread_encoder_init(), ff_wms_parse_sdp_a_line(), init_muxer(), mark_section_show_entries(), new_output_stream(), open_output_file(), open_slave(), and opt_default_new().

void av_dict_free

(

AVDictionary **

m

)

Free all the memory allocated for an AVDictionary struct and all keys and values.

Definition at line 162 of file dict.c.

Referenced by add_metadata_from_side_data(), av_opt_set_dict(), avcodec_close(), avcodec_open2(), avfilter_copy_buffer_ref_props(), avfilter_copy_frame_props(), avfilter_unref_buffer(), avformat_find_stream_info(), avformat_free_context(), avformat_open_input(), close_connection(), config(), decode_frame(), exit_program(), ff_frame_thread_encoder_init(), ff_free_stream(), ff_metadata_conv(), ff_rtp_chain_mux_open(), ff_wms_parse_sdp_a_line(), http_open_cnx(), http_prepare_data(), id3v2_3_metadata_split_date(), init_muxer(), ism_seek(), ism_write_header(), main(), open_input(), open_input_file(), open_slave(), opt_default_new(), opt_show_entries(), parse_playlist(), parse_slave_options(), prepare_sdp_description(), read_thread(), rtmp_open(), transcode(), try_decode_frame(), uninit(), uninit_opts(), uninit_parse_context(), and X264_init().