All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Functions

Simple key:value store. More...

Data Structures

struct  AVDictionaryEntry


#define AV_DICT_MATCH_CASE   1
 Only get an entry with exact-case key match. More...
 Return first entry in a dictionary whose first part corresponds to the search key, ignoring the suffix of the found key string. More...
 Take ownership of a key that's been allocated with av_malloc() or another memory allocation function. More...
 Take ownership of a value that's been allocated with av_malloc() or another memory allocation function. More...
 Don't overwrite existing entries. More...
#define AV_DICT_APPEND   32
 If the entry already exists, append to it. More...


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

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
while (t = av_dict_get(d, "", t, AV_DICT_IGNORE_SUFFIX)) {
<....> // iterate over all entries in d

Macro Definition Documentation

#define AV_DICT_MATCH_CASE   1

Take ownership of a key that's been allocated with av_malloc() or another memory allocation function.

Definition at line 75 of file dict.h.

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

#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 82 of file dict.h.

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

Function Documentation

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

Get a dictionary entry with matching key.

The returned entry key or value must not be changed, or it will cause undefined behavior.

To iterate through all the dictionary entries, you can set the matching key to the null string "" and set the AV_DICT_IGNORE_SUFFIX flag.

prevSet to the previous matching element to find the next. If set to NULL the first matching element is returned.
keymatching key
flagsa collection of AV_DICT_* flags controlling how the entry is retrieved
found entry or NULL in case no matching entry was found in the dictionary

Definition at line 39 of file dict.c.

Referenced by add_codec(), adts_aac_read_header(), asf_write_header1(), asf_write_markers(), assert_avoptions(), av_dict_copy(), av_dict_get_string(), av_dict_set(), av_dump_format(), av_opt_set_dict2(), av_packet_pack_dictionary(), avfilter_init_str(), avformat_match_stream_specifier(), avi_read_header(), avi_write_header(), bitstream_switching(), caf_write_header(), choose_pix_fmts(), config_output(), config_props(), configure_filtergraph(), configure_output_video_filter(), cookie_string(), dump_attachment(), dump_metadata(), dump_stream_format(), dv_init_mux(), dv_write_header(), export_orphan_timecode(), ff_ape_write_tag(), ff_frame_thread_encoder_init(), ff_id3v2_write_apic(), ff_metadata_conv(), ff_replaygain_export(), ff_riff_write_info(), ff_vorbis_comment(), ff_vorbiscomment_length(), ff_vorbiscomment_write(), ffm_write_header(), ffm_write_recommended_config(), ffserver_save_avoption(), ffurl_connect(), ffurl_open_whitelist(), filter_codec_opts(), filter_frame(), find_compressor(), flac_read_header(), flac_write_header(), flv_read_packet(), func_metadata(), get_concatdec_select(), get_date_tag(), get_duration(), get_metadata_val(), get_rotation(), gxf_write_header(), gxf_write_umf_material_description(), id3_has_changed_values(), id3v1_create_tag(), id3v1_set_string(), id3v2_3_metadata_split_date(), init(), init_dict(), init_input_stream(), init_muxer(), init_output_stream(), lavfi_read_packet(), libkvazaar_init(), libx265_encode_init(), lrc_write_header(), main(), matroska_parse_flac(), mkv_check_tag(), mkv_write_attachments(), mkv_write_chapters(), mkv_write_header(), mkv_write_stereo_mode(), mkv_write_tag(), mkv_write_track(), mov_parse_stsd_audio(), mov_read_header(), mov_write_3gp_udta_tag(), mov_write_chpl_tag(), mov_write_hdlr_tag(), mov_write_header(), mov_write_int8_metadata(), mov_write_raw_metadata_tag(), mov_write_string_metadata(), mov_write_tkhd_tag(), mov_write_tmcd_tag(), mov_write_tmpo_tag(), mov_write_track_metadata(), mov_write_trkn_tag(), mov_write_uuidusmt_tag(), mp3_read_header(), mp3_write_xing(), mpc_read_header(), mpegts_init(), mpegts_write_pmt(), mxf_init_timecode(), mxf_write_header(), mxf_write_header_metadata_sets(), mxf_write_user_comments(), open_input_file(), open_output_file(), open_slave(), prepare_sdp_description(), put_meta(), qsv_transcode_init(), queue_picture(), read_thread(), receiver_thread(), remove_avoptions(), riff_has_valid_tags(), sap_write_header(), set_encoder_id(), show_tags(), smjpeg_write_header(), sox_write_header(), stream_component_open(), strip_specifiers(), subsegment_alignment(), write_adaptation_set(), write_chapter(), write_globalinfo(), write_manifest(), write_metadata(), write_representation(), write_streaminfo(), write_table_entries_attrib(), write_table_redirector_legacy_attrib(), write_tags(), writer_open(), 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.

number of entries in dictionary

Definition at line 34 of file dict.c.

Referenced by add_codec(), asf_write_header1(), av_dict_get_string(), av_opt_copy(), caf_write_header(), dump_metadata(), ff_vorbiscomment_write(), hls_write_header(), and seg_write_header().

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

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

Note: If AV_DICT_DONT_STRDUP_KEY or AV_DICT_DONT_STRDUP_VAL is set, these arguments will be freed on error.

pmpointer to a pointer to a dictionary struct. If *pm is NULL a dictionary struct is allocated and put in *pm.
keyentry key to add to *pm (will be av_strduped depending on flags)
valueentry value to add to *pm (will be av_strduped depending on flags). Passing a NULL value will cause an existing entry to be deleted.
>= 0 on success otherwise an error code <0

Definition at line 69 of file dict.c.

Referenced by add_codec(), add_meta(), add_metadata(), add_metadata_from_renditions(), add_timecode_metadata(), amf_parse_object(), ape_tag_read_field(), asf_read_header(), asf_read_metadata(), asf_read_picture(), asf_read_properties(), asf_read_value(), asf_set_metadata(), asf_write_header1(), av_dict_copy(), av_dict_set_fxp(), av_dict_set_int(), av_opt_set_dict2(), av_packet_unpack_dictionary(), avformat_find_stream_info(), avi_metadata_creation_time(), avi_read_nikon(), avi_read_tag(), avpriv_new_chapter(), build_file_streams(), cine_read_header(), config_input(), config_props(), dash_write_header(), decode_frame(), decode_info_header(), decode_text_chunk(), dss_read_metadata_date(), dss_read_metadata_string(), dtshd_read_header(), dv_read_timecode(), export_orphan_timecode(), ff_flac_parse_picture(), ff_frame_thread_encoder_init(), ff_id3v2_parse_apic(), ff_load_image(), ff_metadata_conv(), ff_parse_mpeg2_descriptor(), ff_read_riff_info(), ff_rm_read_mdpr_codecdata(), ff_rtp_chain_mux_open(), ff_sauce_read(), ff_tadd_bytes_metadata(), ff_tadd_doubles_metadata(), ff_tadd_long_metadata(), ff_tadd_rational_metadata(), ff_tadd_shorts_metadata(), ff_tadd_string_metadata(), ff_vorbis_comment(), ff_wms_parse_sdp_a_line(), ffm_write_recommended_config(), ffserver_parse_config_stream(), ffserver_save_avoption(), ffurl_connect(), ffurl_open_whitelist(), filter(), filter_codec_opts(), filter_frame(), flac_read_header(), flac_write_header(), get_attachment(), get_meta(), get_metadata(), get_string(), get_tag(), hls_read_header(), hls_start(), icecast_open(), id3v2_3_metadata_split_date(), iff_read_header(), init(), init_filter_graph(), init_input_stream(), init_muxer(), init_opts(), init_output_stream(), ism_seek(), ism_write_header(), lavfi_read_header(), lrc_read_header(), lrc_write_header(), main(), map_to_opts(), matroska_convert_tag(), matroska_metadata_creation_time(), matroska_parse_tracks(), matroska_read_header(), merge_date(), modplug_load_metadata(), mov_metadata_creation_time(), mov_metadata_gnre(), mov_metadata_loci(), mov_metadata_track_or_disc_number(), mov_parse_stsd_data(), mov_parse_stsd_video(), mov_read_custom_2plus(), mov_read_ftyp(), mov_read_hdlr(), mov_read_header(), mov_read_mdhd(), mov_read_tkhd(), mov_read_udta_string(), mov_read_uuid(), mxf_add_timecode_metadata(), mxf_add_umid_metadata(), mxf_parse_package_comments(), mxf_parse_physical_source_package(), mxf_parse_structural_metadata(), new_output_stream(), new_video_stream(), nist_read_header(), nsv_parse_NSVf_header(), ogm_chapter(), open_codec_context(), open_input(), open_input_file(), open_output_file(), open_slave(), open_url(), opt_bitrate(), opt_default(), opt_profile(), opt_show_entries(), opt_timecode(), output_frame(), parse_chunks(), parse_cookie(), parse_dsd_prop(), parse_icy(), parse_key_value_pair(), parse_playlist(), parse_slave_options(), parse_tag(), parse_timecode_in_framenum_format(), prepare_sdp_description(), process_options(), put_flac_codecpriv(), r3d_read_red1(), read_gab2_sub(), read_header(), read_info_chunk(), read_string(), read_tag(), read_thread(), read_ttag(), read_uslt(), remove_avoptions(), rm_read_metadata(), rpl_read_header(), rtmp_open(), rtsp_read_setup(), sap_write_header(), save_avio_options(), scan_file(), sdt_cb(), select_frame(), sender_thread(), set_colorquant_ratio_meta(), set_encoder_id(), set_http_options(), set_language(), set_meta(), set_metadata_float(), smjpeg_read_header(), smvjpeg_decode_init(), sox_read_header(), stream_component_open(), strip_specifiers(), subviewer_read_header(), try_decode_frame(), update(), update_metadata(), var_read_metadata(), vivo_read_header(), wc3_read_header(), webm_dash_manifest_cues(), and webm_dash_manifest_read_header().

int av_dict_set_int ( AVDictionary **  pm,
const char *  key,
int64_t  value,
int  flags 
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.

In case of failure, all the successfully set entries are stored in *pm. You may need to manually free the created dictionary.

key_val_sepa 0-terminated list of characters used to separate key from value
pairs_sepa 0-terminated list of characters used to separate two pairs from each other
flagsflags 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.
0 on success, negative AVERROR code on failure

Definition at line 176 of file dict.c.

Referenced by concat_read_header(), ffm_write_recommended_config(), hls_write_header(), libkvazaar_init(), libx265_encode_init(), read_ffserver_streams(), seg_write_header(), writer_open(), and X264_init().

int av_dict_copy ( AVDictionary **  dst,
const AVDictionary src,
int  flags 

Copy entries from one AVDictionary struct into another.

dstpointer to a pointer to a AVDictionary struct. If *dst is NULL, this function will allocate a struct for you and put it in *dst
srcpointer to source AVDictionary struct
flagsflags to use when setting entries in *dst
metadata is read using the AV_DICT_IGNORE_SUFFIX flag
0 on success, negative AVERROR code on failure. If dst was allocated by this function, callers should free the associated memory.

Definition at line 213 of file dict.c.

Referenced by add_codec(), asf_read_header(), av_opt_copy(), av_opt_get_dict_val(), av_opt_set_dict_val(), avcodec_open2(), avformat_open_input(), chunk_mux_init(), copy_chapters(), copy_metadata(), copy_stream_props(), ff_frame_thread_encoder_init(), ff_mjpeg_decode_frame(), ff_wms_parse_sdp_a_line(), frame_copy_props(), handle_id3(), hls_mux_init(), hls_write_header(), http_open(), http_open_cnx(), http_prepare_data(), init_muxer(), list_devices_for_context(), mark_section_show_entries(), new_output_stream(), ogg_write_header(), open_audio(), open_output_file(), open_slave(), open_url(), open_video(), opt_default_new(), opt_target(), read_frame_internal(), seg_write_header(), segment_mux_init(), url_connect(), and webp_decode_frame().

void av_dict_free ( AVDictionary **  m)

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

Definition at line 199 of file dict.c.

Referenced by add_codec(), asf_read_close(), av_frame_unref(), av_opt_copy(), av_opt_free(), av_opt_set_dict2(), av_opt_set_dict_val(), avfilter_init_str(), avformat_find_stream_info(), avformat_free_context(), avformat_open_input(), close_connection(), concat_read_close(), config_input(), config_props(), dash_write_header(), decode_frame_common(), ff_frame_thread_encoder_init(), ff_http_do_new_request(), ff_load_image(), ff_metadata_conv(), ff_mjpeg_decode_end(), ff_mjpeg_decode_frame(), ff_rtp_chain_mux_open(), ff_wms_parse_sdp_a_line(), ffm_write_recommended_config(), ffmpeg_cleanup(), ffprobe_cleanup(), ffserver_parse_config_stream(), free_playlist_list(), free_side_data(), free_stream(), ftp_connect_control_connection(), ftp_connect_data_connection(), get_cookies(), handle_id3(), hls_close(), hls_start(), hls_window(), hls_write_header(), http_close(), http_listen(), http_open(), http_prepare_data(), http_read_header(), http_seek_internal(), icecast_open(), id3v2_3_metadata_split_date(), init(), init_dict(), init_filter_graph(), init_fps(), init_muxer(), ism_seek(), ism_write_header(), libkvazaar_init(), libx265_encode_init(), list_devices_for_context(), main(), matroska_parse_flac(), open_audio(), open_input(), open_input_file(), open_output_file(), open_slave(), open_url(), open_video(), opt_default_new(), opt_show_entries(), parse_playlist(), parse_slave_options(), prepare_sdp_description(), put_flac_codecpriv(), read_ffserver_streams(), read_frame_internal(), read_thread(), rtmp_open(), rtsp_read_setup(), seg_write_header(), seg_write_trailer(), show_packet(), smvjpeg_decode_init(), stream_component_open(), transcode(), try_decode_frame(), uninit(), uninit_opts(), uninit_parse_context(), url_connect(), vorbis_update_metadata(), webp_decode_frame(), writer_open(), and X264_init().

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.

Create a string containing dictionary's entries. Such string may be passed back to av_dict_parse_string().

String is escaped with backslashes ('\').
[out]bufferPointer to buffer that will be allocated with string containg entries. Buffer must be freed by the caller when is no longer needed.
[in]key_val_sepcharacter used to separate key from value
[in]pairs_sepcharacter used to separate two pairs from each other
>= 0 on success, negative on error
Separators cannot be neither '\' nor '\0'. They also cannot be the same.

Definition at line 226 of file dict.c.

Referenced by add_codec(), and ffm_write_recommended_config().