Media Format API. More...

#include "asterisk/codec.h"

Include dependency graph for format.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ast_format_interface
	Optional format interface to extend format operations. More...

Macros
#define	ast_format_interface_register(codec, interface) __ast_format_interface_register(codec, interface, AST_MODULE_SELF)
	Register a format interface for use with the provided codec. More...

Enumerations
enum	ast_format_cmp_res { AST_FORMAT_CMP_EQUAL = 0, AST_FORMAT_CMP_NOT_EQUAL, AST_FORMAT_CMP_SUBSET }
	Format comparison results. More...

Functions
int	__ast_format_interface_register (const char codec, const struct ast_format_interface interface, struct ast_module *mod)
	Register a format interface for use with the provided codec. More...

const void *	ast_format_attribute_get (const struct ast_format format, const char name)

struct ast_format *	ast_format_attribute_set (const struct ast_format format, const char name, const char *value)
	Set an attribute on a format to a specific value. More...

int	ast_format_can_be_smoothed (const struct ast_format *format)
	Get whether or not the format can be smoothed. More...

struct ast_format *	ast_format_clone (const struct ast_format *format)
	Clone an existing media format so it can be modified. More...

enum ast_format_cmp_res	ast_format_cmp (const struct ast_format format1, const struct ast_format format2)
	Compare two formats. More...

struct ast_format *	ast_format_create (struct ast_codec *codec)
	Create a new media format. More...

struct ast_format *	ast_format_create_named (const char format_name, struct ast_codec codec)
	Create a new media format with a specific name. More...

unsigned int	ast_format_determine_length (const struct ast_format *format, unsigned int samples)
	Get the length (in milliseconds) for the format with a given number of samples. More...

void	ast_format_generate_sdp_fmtp (const struct ast_format format, unsigned int payload, struct ast_str *str)
	This function is used to produce an fmtp SDP line for an Asterisk format. The attributes present on the Asterisk format are translated into the SDP equivalent. More...

void *	ast_format_get_attribute_data (const struct ast_format *format)
	Get the attribute data on a format. More...

unsigned int	ast_format_get_channel_count (const struct ast_format *format)
	Get the channel count on a format. More...

struct ast_codec *	ast_format_get_codec (const struct ast_format *format)
	Get the codec associated with a format. More...

unsigned int	ast_format_get_codec_id (const struct ast_format *format)
	Get the codec identifier associated with a format. More...

const char *	ast_format_get_codec_name (const struct ast_format *format)
	Get the codec name associated with a format. More...

unsigned int	ast_format_get_default_ms (const struct ast_format *format)
	Get the default framing size (in milliseconds) for a format. More...

unsigned int	ast_format_get_maximum_ms (const struct ast_format *format)
	Get the maximum amount of media carried in this format. More...

unsigned int	ast_format_get_minimum_bytes (const struct ast_format *format)
	Get the minimum number of bytes expected in a frame for this format. More...

unsigned int	ast_format_get_minimum_ms (const struct ast_format *format)
	Get the minimum amount of media carried in this format. More...

const char *	ast_format_get_name (const struct ast_format *format)
	Get the name associated with a format. More...

unsigned int	ast_format_get_sample_rate (const struct ast_format *format)
	Get the sample rate of a media format. More...

int	ast_format_get_smoother_flags (const struct ast_format *format)
	Get smoother flags for this format. More...

enum ast_media_type	ast_format_get_type (const struct ast_format *format)
	Get the media type of a format. More...

int	ast_format_init (void)
	Initialize media format support. More...

struct ast_format *	ast_format_joint (const struct ast_format format1, const struct ast_format format2)
	Get a common joint capability between two formats. More...

struct ast_format *	ast_format_parse_sdp_fmtp (const struct ast_format format, const char attributes)
	This function is used to have a media format aware module parse and interpret SDP attribute information. Once interpreted this information is stored on the format itself using Asterisk format attributes. More...

struct stasis_message_type *	ast_format_register_type (void)
	Get the message type used for signaling a format registration. More...

void	ast_format_set_attribute_data (struct ast_format format, void attribute_data)
	Set the attribute data on a format. More...

void	ast_format_set_channel_count (struct ast_format *format, unsigned int channel_count)
	Set the channel count on a format. More...

struct stasis_message_type *	ast_format_unregister_type (void)
	Get the message type used for signaling a format unregistration. More...

Detailed Description

Media Format API.

Author: Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file format.h.

Macro Definition Documentation

◆ ast_format_interface_register

#define ast_format_interface_register	(	codec,
		interface
	)	__ast_format_interface_register(codec, interface, AST_MODULE_SELF)

Register a format interface for use with the provided codec.

Parameters

codec	The name of codec the interface is applicable to
interface	A pointer to the interface implementation

Return values

0	success
-1	failure

Definition at line 273 of file format.h.

Referenced by load_module().

Enumeration Type Documentation

◆ ast_format_cmp_res

enum ast_format_cmp_res

Format comparison results.

Enumerator
AST_FORMAT_CMP_EQUAL	Both formats are equivalent to each other
AST_FORMAT_CMP_NOT_EQUAL	Both formats are completely different and not the same in any way
AST_FORMAT_CMP_SUBSET	Both formats are similar but not equivalent

Definition at line 34 of file format.h.

                         {
    /*! Both formats are equivalent to each other */
    AST_FORMAT_CMP_EQUAL = 0,
    /*! Both formats are completely different and not the same in any way */
    AST_FORMAT_CMP_NOT_EQUAL,
    /*! Both formats are similar but not equivalent */
    AST_FORMAT_CMP_SUBSET,
 };

Function Documentation

◆ __ast_format_interface_register()

int __ast_format_interface_register	(	const char *	codec,
		const struct ast_format_interface *	interface,
		struct ast_module *	mod
	)

Register a format interface for use with the provided codec.

Parameters

codec	The name of codec the interface is applicable to
interface	A pointer to the interface implementation
mod	The module this format interface is provided by

Return values

0	success
-1	failure

Definition at line 90 of file format.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_find, ao2_link_flags, ao2_ref, ast_log, ast_module_shutdown_ref, ast_verb, format_interface::codec, ast_format_interface::format_clone, ast_format_interface::format_destroy, ast_format::interface, format_interface::interface, lock, LOG_ERROR, NULL, OBJ_NOLOCK, OBJ_SEARCH_KEY, and SCOPED_AO2WRLOCK.

Referenced by load_module().

 {
    SCOPED_AO2WRLOCK(lock, interfaces);
    struct format_interface *format_interface;
 
    if (!interface->format_clone || !interface->format_destroy) {
       ast_log(LOG_ERROR, "Format interface for codec '%s' does not implement required callbacks\n", codec);
       return -1;
    }
 
    format_interface = ao2_find(interfaces, codec, OBJ_SEARCH_KEY | OBJ_NOLOCK);
    if (format_interface) {
       ast_log(LOG_ERROR, "A format interface is already present for codec '%s'\n", codec);
       ao2_ref(format_interface, -1);
       return -1;
    }
 
    format_interface = ao2_alloc_options(sizeof(*format_interface) + strlen(codec) + 1,
       NULL, AO2_ALLOC_OPT_LOCK_NOLOCK);
    if (!format_interface) {
       return -1;
    }
    format_interface->interface = interface;
    strcpy(format_interface->codec, codec); /* Safe */
 
    /* Once registered a format interface cannot be unregistered. */
    ast_module_shutdown_ref(mod);
    ao2_link_flags(interfaces, format_interface, OBJ_NOLOCK);
    ao2_ref(format_interface, -1);
 
    ast_verb(2, "Registered format interface for codec '%s'\n", codec);
 
    return 0;
 }

◆ ast_format_attribute_get()

const void* ast_format_attribute_get	(	const struct ast_format *	format,
		const char *	name
	)

Since: 13.6.0

Parameters

format	The format to retrieve the attribute from
name	Attribute name

Return values

non-NULL	the attribute value
NULL	the attribute does not exist or is unset

Definition at line 267 of file format.c.

References ao2_find, ao2_ref, ast_format::codec, ast_codec::name, NULL, and OBJ_SEARCH_KEY.

Referenced by AST_TEST_DEFINE().

 {
    const struct ast_format_interface *interface = format->interface;
 
    if (!interface) {
       struct format_interface *format_interface = ao2_find(interfaces, format->codec->name, OBJ_SEARCH_KEY);
       if (format_interface) {
          interface = format_interface->interface;
          ao2_ref(format_interface, -1);
       }
    }
 
    if (!interface || !interface->format_attribute_get) {
       return NULL;
    }
 
    return interface->format_attribute_get(format, name);
 }

◆ ast_format_attribute_set()

struct ast_format* ast_format_attribute_set	(	const struct ast_format *	format,
		const char *	name,
		const char *	value
	)

Set an attribute on a format to a specific value.

Parameters

format	The format to set the attribute on
name	Attribute name
value	Attribute value

Return values

non-NULL	success
NULL	failure

Definition at line 248 of file format.c.

References ao2_bump, ao2_find, ao2_ref, format, ast_format::name, OBJ_SEARCH_KEY, and value.

Referenced by AST_TEST_DEFINE().

 {
    const struct ast_format_interface *interface = format->interface;
 
    if (!interface) {
       struct format_interface *format_interface = ao2_find(interfaces, format->codec->name, OBJ_SEARCH_KEY);
       if (format_interface) {
          interface = format_interface->interface;
          ao2_ref(format_interface, -1);
       }
    }
 
    if (!interface || !interface->format_attribute_set) {
       return ao2_bump((struct ast_format*)format);
    }
 
    return interface->format_attribute_set(format, name, value);
 }

◆ ast_format_can_be_smoothed()

int ast_format_can_be_smoothed ( const struct ast_format * format )

Get whether or not the format can be smoothed.

Parameters

format The media format

Return values

0	the format cannot be smoothed
1	the format can be smoothed

Definition at line 344 of file format.c.

References ast_format::codec, and ast_codec::smooth.

Referenced by ast_rtp_write(), and multicast_rtp_write().

 {
    return format->codec->smooth;
 }

◆ ast_format_clone()

struct ast_format* ast_format_clone ( const struct ast_format * format )

Clone an existing media format so it can be modified.

Parameters

format The existing media format

Note: The returned format is a new ao2 object. It must be released using ao2_cleanup.

Return values

non-NULL	success
NULL	failure

Definition at line 180 of file format.c.

References ao2_ref, ast_format_create_named(), ast_format::codec, ast_format_interface::format_clone, ast_format::interface, ast_format::name, and NULL.

Referenced by AST_TEST_DEFINE(), celt_getjoint(), celt_parse_sdp_fmtp(), celt_set(), h263_getjoint(), h263_parse_sdp_fmtp(), h264_getjoint(), h264_parse_sdp_fmtp(), ilbc_getjoint(), ilbc_parse_sdp_fmtp(), opus_getjoint(), opus_parse_sdp_fmtp(), opus_set(), silk_getjoint(), silk_parse_sdp_fmtp(), silk_set(), test_core_format_attribute_set(), test_core_format_get_joint(), test_core_format_parse_sdp_fmtp(), vp8_getjoint(), vp8_parse_sdp_fmtp(), and vp8_set().

 {
    struct ast_format *cloned = ast_format_create_named(format->name, format->codec);
 
    if (!cloned) {
       return NULL;
    }
 
    if (cloned->interface && cloned->interface->format_clone(format, cloned)) {
       ao2_ref(cloned, -1);
       return NULL;
    }
 
    return cloned;
 }

◆ ast_format_cmp()

enum ast_format_cmp_res ast_format_cmp	(	const struct ast_format *	format1,
		const struct ast_format *	format2
	)

Compare two formats.

Return values

ast_format_cmp_res representing the result of comparing format1 and format2.

Examples:: /usr/src/asterisk-18.5.0/main/app.c.

Definition at line 201 of file format.c.

References AST_FORMAT_CMP_EQUAL, AST_FORMAT_CMP_NOT_EQUAL, ast_format::codec, if(), ast_format::interface, and NULL.

Referenced by __ast_read(), __ast_smoother_feed(), add_codec_to_sdp(), add_tcodec_to_sdp(), add_vcodec_to_sdp(), adsi_careful_send(), alarmreceiver_exec(), ast_bridge_channel_restore_formats(), ast_channel_make_compatible_helper(), ast_dsp_process(), ast_dsp_silence_noise_with_energy(), ast_format_cache_is_slinear(), ast_format_cap_get_compatible_format(), ast_format_cap_get_format_framing(), ast_format_cap_iscompatible_format(), ast_format_compatibility_format2bitfield(), ast_format_joint(), ast_frame_slinear_sum(), ast_read_generator_actions(), ast_read_image(), ast_rtp_codecs_payload_code(), ast_rtp_codecs_payload_code_tx(), ast_rtp_codecs_payloads_set_rtpmap_type_rate(), ast_rtp_engine_unload_format(), ast_rtp_get_rate(), ast_rtp_interpret(), ast_rtp_lookup_mime_subtype2(), ast_rtp_lookup_sample_rate2(), ast_rtp_write(), ast_set_read_format_path(), ast_set_write_format_path(), ast_slinfactory_feed(), AST_TEST_DEFINE(), ast_write_stream(), ast_writestream(), audiohook_list_translate_to_native(), audiohook_list_translate_to_slin(), audiohook_read_frame_helper(), background_detect_exec(), bridge_p2p_rtp_write(), chan_pjsip_read_stream(), codec_ast2skinny(), conf_run(), dahdi_read(), dahdi_write(), fax_detect_framehook(), fax_gateway_framehook(), filehelper(), find_static_payload_type(), generate_interpolated_slin(), generic_fax_exec(), iax2_send(), iax_frame_wrap(), jack_hook_callback(), jingle_add_payloads_to_description(), make_silence(), measurenoise(), misdn_write(), moh_files_generator(), ooh323_convertAsteriskCapToH323Cap(), ooh323_rtp_read(), ooh323c_set_capability(), ooh323c_set_capability_for_call(), ooh323c_start_transmit_channel(), payload_mapping_rx_clear_primary(), pcm_seek(), pcm_write(), phone_read(), phone_setup(), phone_write(), process_sdp_a_audio(), rtp_get_rate(), rtp_raw_write(), send_start_rtp(), set_format(), setup_rtp_connection(), socket_process_helper(), softmix_bridge_write_voice(), softmix_process_write_audio(), spandsp_fax_gateway_process(), spandsp_v21_detect(), and transmit_audio().

 {
    const struct ast_format_interface *interface;
 
    if (format1 == NULL || format2 == NULL) {
       return AST_FORMAT_CMP_NOT_EQUAL;
    }
 
    if (format1 == format2) {
       return AST_FORMAT_CMP_EQUAL;
    }
 
    if (format1->codec != format2->codec) {
       return AST_FORMAT_CMP_NOT_EQUAL;
    }
 
    interface = format1->interface ? format1->interface : format2->interface;
 
    if (interface && interface->format_cmp) {
       return interface->format_cmp(format1, format2);
    }
 
    return AST_FORMAT_CMP_EQUAL;
 }

◆ ast_format_create()

struct ast_format* ast_format_create ( struct ast_codec * codec )

Create a new media format.

Parameters

codec The codec to use

Return values

non-NULL	success
NULL	failure

Note: The format is returned with reference count incremented. It must be released using ao2_ref or ao2_cleanup.

Definition at line 196 of file format.c.

References ast_format_create_named(), and ast_codec::name.

Referenced by ast_format_cap_append_by_type(), AST_TEST_DEFINE(), and newpvt().

 {
    return ast_format_create_named(codec->name, codec);
 }

◆ ast_format_create_named()

struct ast_format* ast_format_create_named	(	const char *	format_name,
		struct ast_codec *	codec
	)

Create a new media format with a specific name.

Parameters

format_name	The name to use for the format
codec	The codec to use

Note: This creation function should be used when the name of the codec cannot be explicitly used for the name of the format. This is the case for codecs with multiple sample rates; The format is returned with reference count incremented. It must be released using ao2_ref or ao2_cleanup.

Return values

non-NULL	success
NULL	failure

Definition at line 157 of file format.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_bump, ao2_find, ao2_ref, ao2_t_alloc_options, ast_format::channel_count, ast_format::codec, ast_codec::description, format, format_destroy(), ast_format::interface, format_interface::interface, ast_format::name, ast_codec::name, NULL, OBJ_SEARCH_KEY, and S_OR.

Referenced by ast_format_clone(), ast_format_create(), and AST_TEST_DEFINE().

 {
    struct ast_format *format;
    struct format_interface *format_interface;
 
    format = ao2_t_alloc_options(sizeof(*format), format_destroy,
       AO2_ALLOC_OPT_LOCK_NOLOCK, S_OR(codec->description, ""));
    if (!format) {
       return NULL;
    }
    format->name = format_name;
    format->codec = ao2_bump(codec);
    format->channel_count = 1;
 
    format_interface = ao2_find(interfaces, codec->name, OBJ_SEARCH_KEY);
    if (format_interface) {
       format->interface = format_interface->interface;
       ao2_ref(format_interface, -1);
    }
 
    return format;
 }

◆ ast_format_determine_length()

unsigned int ast_format_determine_length	(	const struct ast_format *	format,
		unsigned int	samples
	)

Get the length (in milliseconds) for the format with a given number of samples.

Parameters

format	The media format
samples	The number of samples

Returns: length of media (in milliseconds)

Definition at line 384 of file format.c.

References ast_codec_determine_length(), and ast_format::codec.

Referenced by moh_generate(), and monmp3thread().

 {
    return ast_codec_determine_length(format->codec, samples);
 }

◆ ast_format_generate_sdp_fmtp()

void ast_format_generate_sdp_fmtp	(	const struct ast_format *	format,
		unsigned int	payload,
		struct ast_str **	str
	)

This function is used to produce an fmtp SDP line for an Asterisk format. The attributes present on the Asterisk format are translated into the SDP equivalent.

Parameters

format	to generate an fmtp line for
payload	numerical payload for the fmtp line
str	structure that the fmtp line will be appended to

Definition at line 305 of file format.c.

References ao2_find, ao2_ref, ast_format::codec, ast_codec::name, and OBJ_SEARCH_KEY.

Referenced by add_codec_to_sdp(), add_vcodec_to_sdp(), AST_TEST_DEFINE(), and generate_fmtp_attr().

 {
    const struct ast_format_interface *interface = format->interface;
 
    if (!interface) {
       struct format_interface *format_interface = ao2_find(interfaces, format->codec->name, OBJ_SEARCH_KEY);
       if (format_interface) {
          interface = format_interface->interface;
          ao2_ref(format_interface, -1);
       }
    }
 
    if (!interface || !interface->format_generate_sdp_fmtp) {
       return;
    }
 
    interface->format_generate_sdp_fmtp(format, payload, str);
 }

◆ ast_format_get_attribute_data()

void* ast_format_get_attribute_data ( const struct ast_format * format )

Get the attribute data on a format.

Parameters

format The media format

Returns: Currently set attribute data

Definition at line 125 of file format.c.

References ast_format::attribute_data.

 {
    return format->attribute_data;
 }

◆ ast_format_get_channel_count()

unsigned int ast_format_get_channel_count ( const struct ast_format * format )

Get the channel count on a format.

Parameters

The	media format

Returns: Currently set channel count

Definition at line 135 of file format.c.

References ast_format::channel_count.

Referenced by opus_clone(), opus_getjoint(), and softmix_bridge_join().

 {
    return format->channel_count;
 }

◆ ast_format_get_codec()

struct ast_codec* ast_format_get_codec ( const struct ast_format * format )

Get the codec associated with a format.

Parameters

format The media format

Returns: The codec

Note: The reference count of the returned codec is increased by 1 and must be decremented

Definition at line 324 of file format.c.

References ao2_bump, and ast_format::codec.

Referenced by ast_codec_samples_count(), ast_format_cache_get_by_codec(), and ast_format_cap_append_by_type().

 {
    return ao2_bump(format->codec);
 }

◆ ast_format_get_codec_id()

unsigned int ast_format_get_codec_id ( const struct ast_format * format )

Get the codec identifier associated with a format.

Parameters

format The media format

Returns: codec identifier

Definition at line 329 of file format.c.

References ast_format::codec, and ast_codec::id.

Referenced by ast_format_cap_get_compatible_format(), ast_format_cap_get_format_framing(), ast_format_cap_iscompatible_format(), ast_format_cap_remove(), ast_format_compatibility_codec2bitfield(), ast_slinfactory_feed(), AST_TEST_DEFINE(), format2index(), format_cap_framed_init(), format_cap_replace(), format_in_format_cap(), and payload_mapping_tx_is_present().

 {
    return format->codec->id;
 }

◆ ast_format_get_codec_name()

const char* ast_format_get_codec_name ( const struct ast_format * format )

Get the codec name associated with a format.

Parameters

format The media format

Returns: The codec name

Definition at line 339 of file format.c.

References ast_format::codec, and ast_codec::name.

Referenced by ast_rtp_engine_load_format().

 {
    return format->codec->name;
 }

◆ ast_format_get_default_ms()

unsigned int ast_format_get_default_ms ( const struct ast_format * format )

Get the default framing size (in milliseconds) for a format.

Parameters

format The media format

Returns: default framing size in milliseconds

Definition at line 359 of file format.c.

References ast_format::codec, and ast_codec::default_ms.

Referenced by __get_from_jb(), ast_format_cap_get_format_framing(), ast_rtp_write(), AST_TEST_DEFINE(), format_cap_framed_init(), jb_get_and_deliver(), and multicast_rtp_write().

 {
    return format->codec->default_ms;
 }

◆ ast_format_get_maximum_ms()

unsigned int ast_format_get_maximum_ms ( const struct ast_format * format )

Get the maximum amount of media carried in this format.

Parameters

format The media format

Returns: maximum framing size in milliseconds

Definition at line 369 of file format.c.

References ast_format::codec, and ast_codec::maximum_ms.

Referenced by add_codec_to_sdp(), and create_outgoing_sdp_stream().

 {
    return format->codec->maximum_ms;
 }

◆ ast_format_get_minimum_bytes()

unsigned int ast_format_get_minimum_bytes ( const struct ast_format * format )

Get the minimum number of bytes expected in a frame for this format.

Parameters

format The media format

Returns: minimum expected bytes in a frame for this format

Definition at line 374 of file format.c.

References ast_format::codec, and ast_codec::minimum_bytes.

Referenced by ast_rtp_write(), and multicast_rtp_write().

 {
    return format->codec->minimum_bytes;
 }

◆ ast_format_get_minimum_ms()

unsigned int ast_format_get_minimum_ms ( const struct ast_format * format )

Get the minimum amount of media carried in this format.

Parameters

format The media format

Returns: minimum framing size in milliseconds

Definition at line 364 of file format.c.

References ast_format::codec, and ast_codec::minimum_ms.

Referenced by ast_rtp_write(), and multicast_rtp_write().

 {
    return format->codec->minimum_ms;
 }

◆ ast_format_get_name()

const char* ast_format_get_name ( const struct ast_format * format )

Get the name associated with a format.

Parameters

format The media format

Returns: The name of the format

Examples:: /usr/src/asterisk-18.5.0/main/app.c.

Definition at line 334 of file format.c.

References ast_format::name.

Referenced by __ast_format_cap_get_names(), __ast_play_and_record(), __ast_smoother_feed(), add_codec_to_sdp(), add_format_information_cb(), add_sdp(), add_static_payload(), add_tcodec_to_sdp(), add_vcodec_to_sdp(), adsi_transmit_message_full(), agent_login_exec(), ast_bridge_channel_restore_formats(), ast_channel_make_compatible_helper(), ast_codec_samples_count(), ast_dsp_process(), ast_format_cache_set(), ast_frame_subclass2str(), ast_openvstream(), ast_rtp_write(), ast_set_read_format_path(), ast_set_write_format_path(), ast_slinfactory_feed(), ast_stopstream(), ast_streamfile(), ast_translator_build_path(), ast_write_stream(), ast_writestream(), background_detect_exec(), bridge_p2p_rtp_write(), chan_pjsip_read_stream(), chan_pjsip_write_stream(), channel_do_masquerade(), cli_channelstats_print_body(), create_outgoing_sdp_stream(), dahdi_write(), do_waiting(), eagi_exec(), format_cmp_cb(), format_hash_cb(), func_channel_read(), function_iaxpeer(), function_sippeer(), g719read(), g723_read(), g726_read(), g729_read(), generate_status(), generic_read(), gsm_read(), h263_read(), h264_read(), handle_capabilities_res_message(), handle_cli_core_show_file_formats(), handle_cli_moh_show_classes(), handle_core_show_image_formats(), handle_open_receive_channel_ack_message(), handle_showchan(), handle_streamfile(), iax2_codec_pref_string(), iax2_getformatname(), ilbc_read(), init_jack_data(), isAnsweringMachine(), jack_hook_callback(), jingle_read(), jingle_write(), linear_release(), media_offer_read_av(), mgcp_rtp_read(), mgcp_write(), misdn_write(), moh_alloc(), moh_files_release(), moh_release(), multicast_rtp_write(), ooh323_convertAsteriskCapToH323Cap(), ooh323_rtp_read(), ooh323_set_read_format(), ooh323_set_write_format(), ooh323_write(), pcm_read(), phone_setup(), phone_write(), print_frame(), process_cn_rfc3389(), rtp_codecs_assign_payload_code_rx(), send_start_rtp(), serialize_showchan(), set_format(), show_sound_info_cb(), sip_new(), sip_rtp_read(), sip_write(), siren14read(), siren7read(), skinny_new(), skinny_rtp_read(), skinny_set_rtp_peer(), skinny_write(), socket_process_helper(), softmix_bridge_write_voice(), spandsp_v21_detect(), start_rtp(), transmit_audio(), unistim_new(), unistim_rtp_read(), unistim_write(), vox_read(), and wav_read().

 {
    return format->name;
 }

◆ ast_format_get_sample_rate()

unsigned int ast_format_get_sample_rate ( const struct ast_format * format )

Get the sample rate of a media format.

Parameters

format The media format

Returns: sample rate

Definition at line 379 of file format.c.

References ast_format::codec, and ast_codec::sample_rate.

Referenced by __ast_read(), __get_from_jb(), ast_channel_make_compatible_helper(), ast_ratestream(), ast_read_generator_actions(), ast_readaudio_callback(), ast_readvideo_callback(), ast_rtp_engine_load_format(), ast_rtp_get_rate(), ast_rtp_interpret(), ast_smoother_read(), ast_translate(), ast_translator_best_choice(), ast_translator_build_path(), ast_write_stream(), audiohook_list_translate_to_slin(), audiohook_read_frame_helper(), calc_timestamp(), gather_softmix_stats(), generator_force(), hook_event_cb(), ilbc_samples(), init_jack_data(), mixmonitor_save_prep(), monmp3thread(), mp3_exec(), ogg_speex_open(), opus_samples(), pitch_shift(), rtp_get_rate(), schedule_delivery(), set_talk_detect(), silk_cmp(), silk_getjoint(), silk_samples(), snoop_determine_format(), speex_callback(), stasis_app_control_snoop(), waitstream_control(), waitstream_core(), wav_open(), and wav_rewrite().

 {
    return format->codec->sample_rate ?: 8000;
 }

◆ ast_format_get_smoother_flags()

int ast_format_get_smoother_flags ( const struct ast_format * format )

Get smoother flags for this format.

Since: 13.17.0

Parameters

format The media format

Returns: smoother flags for the provided format

Definition at line 349 of file format.c.

References ast_format::codec, and ast_codec::smoother_flags.

Referenced by ast_rtp_write(), and multicast_rtp_write().

 {
    return format->codec->smoother_flags;
 }

◆ ast_format_get_type()

enum ast_media_type ast_format_get_type ( const struct ast_format * format )

Get the media type of a format.

Parameters

format The media format

Returns: the media type

Definition at line 354 of file format.c.

References ast_format::codec, and ast_codec::type.

Referenced by __ast_read(), add_sdp(), ast_ari_recordings_get_stored_file(), ast_format_cap_append_from_cap(), ast_format_cap_get_best_by_type(), ast_format_cap_has_type(), ast_format_cap_remove_by_type(), ast_format_cap_replace_from_cap(), ast_openvstream(), ast_playstream(), ast_rtp_codecs_get_stream_type(), ast_rtp_engine_load_format(), ast_rtp_interpret(), ast_translator_best_choice(), ast_translator_build_path(), ast_write_stream(), ast_writestream(), check_translation_path(), codec_choose_from_prefs(), create_outgoing_sdp_stream(), filehelper(), filestream_close(), get_filestream(), jingle_add_payloads_to_description(), phone_read(), stream_echo_write(), stream_echo_write_error(), transmit_connect_with_sdp(), and transmit_modify_with_sdp().

 {
    return format->codec->type;
 }

◆ ast_format_init()

int ast_format_init ( void )

Initialize media format support.

Return values

0	success
-1	failure

Definition at line 77 of file format.c.

References AO2_ALLOC_OPT_LOCK_RWLOCK, ao2_container_alloc_hash, ast_register_cleanup(), FORMAT_INTERFACE_BUCKETS, format_shutdown(), and NULL.

Referenced by asterisk_daemon().

 {
    interfaces = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_RWLOCK, 0,
       FORMAT_INTERFACE_BUCKETS, format_interface_hash_fn, NULL, format_interface_cmp_fn);
    if (!interfaces) {
       return -1;
    }
 
    ast_register_cleanup(format_shutdown);
 
    return 0;
 }

◆ ast_format_joint()

struct ast_format* ast_format_joint	(	const struct ast_format *	format1,
		const struct ast_format *	format2
	)

Get a common joint capability between two formats.

Return values

non-NULL	if joint capability exists
NULL	if no joint capability exists

Note: The returned format must be treated as immutable.

Definition at line 226 of file format.c.

References ao2_bump, ast_format_cmp(), AST_FORMAT_CMP_EQUAL, ast_format::attribute_data, ast_format::codec, ast_format::interface, and NULL.

Referenced by ast_format_cap_get_compatible_format(), and AST_TEST_DEFINE().

 {
    const struct ast_format_interface *interface;
 
    if (format1->codec != format2->codec) {
       return NULL;
    }
 
    /* If the two formats are the same structure OR if the codec is the same and no attributes
     * exist we can immediately return a format with reference count bumped up, since they are
     * the same.
     */
    if ((ast_format_cmp(format1, format2) == AST_FORMAT_CMP_EQUAL && !format1->attribute_data && !format2->attribute_data)) {
       return ao2_bump((struct ast_format*)format1);
    }
 
    interface = format1->interface ? format1->interface : format2->interface;
 
    /* If there is attribute data on either there has to be an interface */
    return interface->format_get_joint(format1, format2);
 }

◆ ast_format_parse_sdp_fmtp()

struct ast_format* ast_format_parse_sdp_fmtp	(	const struct ast_format *	format,
		const char *	attributes
	)

This function is used to have a media format aware module parse and interpret SDP attribute information. Once interpreted this information is stored on the format itself using Asterisk format attributes.

Parameters

format	to set
attributes	string containing the fmtp line from the SDP

Return values

non-NULL	success, attribute values were valid
NULL	failure, values were not acceptable

Definition at line 286 of file format.c.

References ao2_bump, ao2_find, ao2_ref, ast_format::codec, ast_codec::name, and OBJ_SEARCH_KEY.

Referenced by ast_rtp_codecs_payloads_set_rtpmap_type_rate(), AST_TEST_DEFINE(), get_codecs(), process_sdp_a_audio(), and process_sdp_a_video().

 {
    const struct ast_format_interface *interface = format->interface;
 
    if (!interface) {
       struct format_interface *format_interface = ao2_find(interfaces, format->codec->name, OBJ_SEARCH_KEY);
       if (format_interface) {
          interface = format_interface->interface;
          ao2_ref(format_interface, -1);
       }
    }
 
    if (!interface || !interface->format_parse_sdp_fmtp) {
       return ao2_bump((struct ast_format*)format);
    }
 
    return interface->format_parse_sdp_fmtp(format, attributes);
 }

◆ ast_format_register_type()

struct stasis_message_type* ast_format_register_type ( void )

Get the message type used for signaling a format registration.

Since: 12

Return values

Stasis	message type for format registration
NULL	on error

Referenced by __ast_format_def_register(), ast_file_init(), and file_shutdown().

◆ ast_format_set_attribute_data()

void ast_format_set_attribute_data	(	struct ast_format *	format,
		void *	attribute_data
	)

Set the attribute data on a format.

Parameters

format	The media format
attribute_data	The attribute data

Definition at line 130 of file format.c.

References ast_format::attribute_data.

Referenced by celt_clone(), h263_clone(), h264_clone(), ilbc_clone(), opus_clone(), silk_clone(), test_core_format_clone(), and vp8_clone().

 {
    format->attribute_data = attribute_data;
 }

◆ ast_format_set_channel_count()

void ast_format_set_channel_count	(	struct ast_format *	format,
		unsigned int	channel_count
	)

Set the channel count on a format.

Parameters

format	The media format
channel_count	The number of audio channels used

Definition at line 140 of file format.c.

References ast_format::channel_count.

Referenced by opus_clone(), opus_getjoint(), and opus_parse_sdp_fmtp().

 {
    format->channel_count = channel_count;
 }

◆ ast_format_unregister_type()

struct stasis_message_type* ast_format_unregister_type ( void )

Get the message type used for signaling a format unregistration.

Since: 12

Return values

Stasis	message type for format unregistration
NULL	on error

Referenced by ast_file_init(), ast_format_def_unregister(), and file_shutdown().

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ast_format_interface_register

Enumeration Type Documentation

◆ ast_format_cmp_res

Function Documentation

◆ __ast_format_interface_register()

◆ ast_format_attribute_get()

◆ ast_format_attribute_set()

◆ ast_format_can_be_smoothed()

◆ ast_format_clone()

◆ ast_format_cmp()

◆ ast_format_create()

◆ ast_format_create_named()

◆ ast_format_determine_length()

◆ ast_format_generate_sdp_fmtp()

◆ ast_format_get_attribute_data()

◆ ast_format_get_channel_count()

◆ ast_format_get_codec()

◆ ast_format_get_codec_id()

◆ ast_format_get_codec_name()

◆ ast_format_get_default_ms()

◆ ast_format_get_maximum_ms()

◆ ast_format_get_minimum_bytes()

◆ ast_format_get_minimum_ms()

◆ ast_format_get_name()

◆ ast_format_get_sample_rate()

◆ ast_format_get_smoother_flags()

◆ ast_format_get_type()

◆ ast_format_init()

◆ ast_format_joint()

◆ ast_format_parse_sdp_fmtp()

◆ ast_format_register_type()

◆ ast_format_set_attribute_data()

◆ ast_format_set_channel_count()

◆ ast_format_unregister_type()