Asterisk - The Open Source Telephony Project  18.5.0
Data Structures | Macros | Enumerations | Functions
format.h File Reference

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:

Go to the source code of 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_formatast_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_formatast_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_formatast_format_create (struct ast_codec *codec)
 Create a new media format. More...
 
struct ast_formatast_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_codecast_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_formatast_format_joint (const struct ast_format *format1, const struct ast_format *format2)
 Get a common joint capability between two formats. More...
 
struct ast_formatast_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_typeast_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_typeast_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
codecThe name of codec the interface is applicable to
interfaceA pointer to the interface implementation
Return values
0success
-1failure

Definition at line 273 of file format.h.

Referenced by load_module().

Enumeration Type Documentation

◆ 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.

34  {
35  /*! Both formats are equivalent to each other */
37  /*! Both formats are completely different and not the same in any way */
39  /*! Both formats are similar but not equivalent */
41 };

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
codecThe name of codec the interface is applicable to
interfaceA pointer to the interface implementation
modThe module this format interface is provided by
Return values
0success
-1failure

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().

91 {
94 
95  if (!interface->format_clone || !interface->format_destroy) {
96  ast_log(LOG_ERROR, "Format interface for codec '%s' does not implement required callbacks\n", codec);
97  return -1;
98  }
99 
100  format_interface = ao2_find(interfaces, codec, OBJ_SEARCH_KEY | OBJ_NOLOCK);
101  if (format_interface) {
102  ast_log(LOG_ERROR, "A format interface is already present for codec '%s'\n", codec);
103  ao2_ref(format_interface, -1);
104  return -1;
105  }
106 
107  format_interface = ao2_alloc_options(sizeof(*format_interface) + strlen(codec) + 1,
109  if (!format_interface) {
110  return -1;
111  }
112  format_interface->interface = interface;
113  strcpy(format_interface->codec, codec); /* Safe */
114 
115  /* Once registered a format interface cannot be unregistered. */
117  ao2_link_flags(interfaces, format_interface, OBJ_NOLOCK);
118  ao2_ref(format_interface, -1);
119 
120  ast_verb(2, "Registered format interface for codec '%s'\n", codec);
121 
122  return 0;
123 }
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1105
const struct ast_format_interface * interface
Pointer to the format interface itself.
Definition: format.c:59
int(*const format_clone)(const struct ast_format *src, struct ast_format *dst)
Callback for when the format is cloned, used to clone attributes.
Definition: format.h:61
Assume that the ao2_container is already locked.
Definition: astobj2.h:1067
#define ao2_alloc_options(data_size, destructor_fn, options)
Definition: astobj2.h:406
#define ao2_link_flags(container, obj, flags)
Definition: astobj2.h:1572
#define NULL
Definition: resample.c:96
char codec[0]
Name of the codec the interface is for.
Definition: format.c:61
#define ast_verb(level,...)
Definition: logger.h:463
#define SCOPED_AO2WRLOCK(varname, obj)
scoped lock specialization for ao2 write locks.
Definition: lock.h:612
static struct ao2_container * interfaces
Container for registered format interfaces.
Definition: format.c:65
#define ast_log
Definition: astobj2.c:42
ast_mutex_t lock
Definition: app_meetme.c:1091
void(*const format_destroy)(struct ast_format *format)
Callback for when the format is destroyed, used to release attribute resources.
Definition: format.h:50
#define ao2_ref(o, delta)
Definition: astobj2.h:464
#define LOG_ERROR
Definition: logger.h:285
#define ast_module_shutdown_ref(mod)
Prevent unload of the module before shutdown.
Definition: module.h:464
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1756
Structure used when registering a format interface.
Definition: format.c:57

◆ ast_format_attribute_get()

const void* ast_format_attribute_get ( const struct ast_format format,
const char *  name 
)
Since
13.6.0
Parameters
formatThe format to retrieve the attribute from
nameAttribute name
Return values
non-NULLthe attribute value
NULLthe 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().

268 {
269  const struct ast_format_interface *interface = format->interface;
270 
271  if (!interface) {
273  if (format_interface) {
274  interface = format_interface->interface;
275  ao2_ref(format_interface, -1);
276  }
277  }
278 
280  return NULL;
281  }
282 
283  return interface->format_attribute_get(format, name);
284 }
const char * name
Name for this codec.
Definition: codec.h:46
Optional format interface to extend format operations.
Definition: format.h:44
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1105
const struct ast_format_interface * interface
Pointer to the format interface itself.
Definition: format.c:59
#define NULL
Definition: resample.c:96
static struct ao2_container * interfaces
Container for registered format interfaces.
Definition: format.c:65
#define ao2_ref(o, delta)
Definition: astobj2.h:464
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
const void *(*const format_attribute_get)(const struct ast_format *format, const char *name)
Retrieve a particular format attribute setting.
Definition: format.h:134
static const char name[]
Definition: cdr_mysql.c:74
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1756
Structure used when registering a format interface.
Definition: format.c:57

◆ 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
formatThe format to set the attribute on
nameAttribute name
valueAttribute value
Return values
non-NULLsuccess
NULLfailure

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().

249 {
250  const struct ast_format_interface *interface = format->interface;
251 
252  if (!interface) {
254  if (format_interface) {
255  interface = format_interface->interface;
256  ao2_ref(format_interface, -1);
257  }
258  }
259 
261  return ao2_bump((struct ast_format*)format);
262  }
263 
264  return interface->format_attribute_set(format, name, value);
265 }
const char * name
Name for this codec.
Definition: codec.h:46
Optional format interface to extend format operations.
Definition: format.h:44
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1105
const struct ast_format_interface * interface
Pointer to the format interface itself.
Definition: format.c:59
struct ast_format *(*const format_attribute_set)(const struct ast_format *format, const char *name, const char *value)
Set an attribute on a format.
Definition: format.h:98
Definition of a media format.
Definition: format.c:43
int value
Definition: syslog.c:37
static struct ao2_container * interfaces
Container for registered format interfaces.
Definition: format.c:65
#define ao2_bump(obj)
Definition: astobj2.h:491
#define ao2_ref(o, delta)
Definition: astobj2.h:464
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
static const char name[]
Definition: cdr_mysql.c:74
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1756
Structure used when registering a format interface.
Definition: format.c:57

◆ 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
formatThe media format
Return values
0the format cannot be smoothed
1the 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().

345 {
346  return format->codec->smooth;
347 }
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
unsigned int smooth
Whether the media can be smoothed or not.
Definition: codec.h:78

◆ 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
formatThe existing media format
Note
The returned format is a new ao2 object. It must be released using ao2_cleanup.
Return values
non-NULLsuccess
NULLfailure

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().

181 {
182  struct ast_format *cloned = ast_format_create_named(format->name, format->codec);
183 
184  if (!cloned) {
185  return NULL;
186  }
187 
188  if (cloned->interface && cloned->interface->format_clone(format, cloned)) {
189  ao2_ref(cloned, -1);
190  return NULL;
191  }
192 
193  return cloned;
194 }
const char * name
Definition: format.c:45
int(*const format_clone)(const struct ast_format *src, struct ast_format *dst)
Callback for when the format is cloned, used to clone attributes.
Definition: format.h:61
Definition of a media format.
Definition: format.c:43
#define NULL
Definition: resample.c:96
#define ao2_ref(o, delta)
Definition: astobj2.h:464
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
const struct ast_format_interface * interface
Pointer to the optional format interface.
Definition: format.c:51
struct ast_format * ast_format_create_named(const char *format_name, struct ast_codec *codec)
Create a new media format with a specific name.
Definition: format.c:157

◆ 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_resrepresenting 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().

202 {
203  const struct ast_format_interface *interface;
204 
205  if (format1 == NULL || format2 == NULL) {
207  }
208 
209  if (format1 == format2) {
210  return AST_FORMAT_CMP_EQUAL;
211  }
212 
213  if (format1->codec != format2->codec) {
215  }
216 
217  interface = format1->interface ? format1->interface : format2->interface;
218 
219  if (interface && interface->format_cmp) {
220  return interface->format_cmp(format1, format2);
221  }
222 
223  return AST_FORMAT_CMP_EQUAL;
224 }
Optional format interface to extend format operations.
Definition: format.h:44
if(!yyg->yy_init)
Definition: ast_expr2f.c:868
#define NULL
Definition: resample.c:96
enum ast_format_cmp_res(*const format_cmp)(const struct ast_format *format1, const struct ast_format *format2)
Determine if format 1 is a subset of format 2.
Definition: format.h:71
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47

◆ ast_format_create()

struct ast_format* ast_format_create ( struct ast_codec codec)

Create a new media format.

Parameters
codecThe codec to use
Return values
non-NULLsuccess
NULLfailure
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().

197 {
198  return ast_format_create_named(codec->name, codec);
199 }
const char * name
Name for this codec.
Definition: codec.h:46
struct ast_format * ast_format_create_named(const char *format_name, struct ast_codec *codec)
Create a new media format with a specific name.
Definition: format.c:157

◆ 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_nameThe name to use for the format
codecThe 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-NULLsuccess
NULLfailure

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().

158 {
159  struct ast_format *format;
161 
162  format = ao2_t_alloc_options(sizeof(*format), format_destroy,
164  if (!format) {
165  return NULL;
166  }
167  format->name = format_name;
168  format->codec = ao2_bump(codec);
169  format->channel_count = 1;
170 
171  format_interface = ao2_find(interfaces, codec->name, OBJ_SEARCH_KEY);
172  if (format_interface) {
173  format->interface = format_interface->interface;
174  ao2_ref(format_interface, -1);
175  }
176 
177  return format;
178 }
const char * name
Name for this codec.
Definition: codec.h:46
const char * name
Definition: format.c:45
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1105
const struct ast_format_interface * interface
Pointer to the format interface itself.
Definition: format.c:59
Definition of a media format.
Definition: format.c:43
#define ao2_t_alloc_options(data_size, destructor_fn, options, debug_msg)
Allocate and initialize an object.
Definition: astobj2.h:404
#define NULL
Definition: resample.c:96
static struct ao2_container * interfaces
Container for registered format interfaces.
Definition: format.c:65
#define ao2_bump(obj)
Definition: astobj2.h:491
static void format_destroy(void *obj)
Destructor for media formats.
Definition: format.c:146
#define ao2_ref(o, delta)
Definition: astobj2.h:464
const char * description
Brief description.
Definition: codec.h:48
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1756
Structure used when registering a format interface.
Definition: format.c:57
const struct ast_format_interface * interface
Pointer to the optional format interface.
Definition: format.c:51
unsigned int channel_count
The number if audio channels used, if more than one an interleaved format is required.
Definition: format.c:53
#define S_OR(a, b)
returns the equivalent of logic or for strings: first one if not empty, otherwise second one...
Definition: strings.h:79
static snd_pcm_format_t format
Definition: chan_alsa.c:102

◆ 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
formatThe media format
samplesThe 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().

385 {
386  return ast_codec_determine_length(format->codec, samples);
387 }
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
unsigned int ast_codec_determine_length(const struct ast_codec *codec, unsigned int samples)
Get the length of media (in milliseconds) given a number of samples.
Definition: codec.c:407

◆ 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
formatto generate an fmtp line for
payloadnumerical payload for the fmtp line
strstructure 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().

306 {
307  const struct ast_format_interface *interface = format->interface;
308 
309  if (!interface) {
311  if (format_interface) {
312  interface = format_interface->interface;
313  ao2_ref(format_interface, -1);
314  }
315  }
316 
318  return;
319  }
320 
321  interface->format_generate_sdp_fmtp(format, payload, str);
322 }
const char * name
Name for this codec.
Definition: codec.h:46
Optional format interface to extend format operations.
Definition: format.h:44
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1105
const struct ast_format_interface * interface
Pointer to the format interface itself.
Definition: format.c:59
static struct ao2_container * interfaces
Container for registered format interfaces.
Definition: format.c:65
void(*const format_generate_sdp_fmtp)(const struct ast_format *format, unsigned int payload, struct ast_str **str)
Generate SDP attribute information from an ast_format structure.
Definition: format.h:121
#define ao2_ref(o, delta)
Definition: astobj2.h:464
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1756
Structure used when registering a format interface.
Definition: format.c:57

◆ ast_format_get_attribute_data()

void* ast_format_get_attribute_data ( const struct ast_format format)

◆ 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
Themedia 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().

136 {
137  return format->channel_count;
138 }
unsigned int channel_count
The number if audio channels used, if more than one an interleaved format is required.
Definition: format.c:53

◆ ast_format_get_codec()

struct ast_codec* ast_format_get_codec ( const struct ast_format format)

Get the codec associated with a format.

Parameters
formatThe 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().

325 {
326  return ao2_bump(format->codec);
327 }
#define ao2_bump(obj)
Definition: astobj2.h:491
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47

◆ 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
formatThe 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().

330 {
331  return format->codec->id;
332 }
unsigned int id
Internal unique identifier for this codec, set at registration time (starts at 1) ...
Definition: codec.h:44
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47

◆ 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
formatThe 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().

340 {
341  return format->codec->name;
342 }
const char * name
Name for this codec.
Definition: codec.h:46
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47

◆ 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
formatThe 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().

360 {
361  return format->codec->default_ms;
362 }
unsigned int default_ms
Default length of media carried (in milliseconds) in a frame.
Definition: codec.h:58
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47

◆ 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
formatThe 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().

370 {
371  return format->codec->maximum_ms;
372 }
unsigned int maximum_ms
Maximum length of media that can be carried (in milliseconds) in a frame.
Definition: codec.h:56
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47

◆ 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
formatThe 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().

375 {
376  return format->codec->minimum_bytes;
377 }
unsigned int minimum_bytes
Length in bytes of the data payload of a minimum_ms frame.
Definition: codec.h:60
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47

◆ 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
formatThe 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().

365 {
366  return format->codec->minimum_ms;
367 }
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
unsigned int minimum_ms
Minimum length of media that can be carried (in milliseconds) in a frame.
Definition: codec.h:54

◆ ast_format_get_name()

const char* ast_format_get_name ( const struct ast_format format)

Get the name associated with a format.

Parameters
formatThe 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().

335 {
336  return format->name;
337 }
const char * name
Definition: format.c:45

◆ ast_format_get_sample_rate()

unsigned int ast_format_get_sample_rate ( const struct ast_format format)

◆ 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
formatThe 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().

350 {
351  return format->codec->smoother_flags;
352 }
unsigned int smoother_flags
Flags to be passed to the smoother.
Definition: codec.h:80
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47

◆ ast_format_get_type()

enum ast_media_type ast_format_get_type ( const struct ast_format format)

◆ ast_format_init()

int ast_format_init ( void  )

Initialize media format support.

Return values
0success
-1failure

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().

78 {
80  FORMAT_INTERFACE_BUCKETS, format_interface_hash_fn, NULL, format_interface_cmp_fn);
81  if (!interfaces) {
82  return -1;
83  }
84 
86 
87  return 0;
88 }
#define NULL
Definition: resample.c:96
static struct ao2_container * interfaces
Container for registered format interfaces.
Definition: format.c:65
int ast_register_cleanup(void(*func)(void))
Register a function to be executed before Asterisk gracefully exits.
Definition: clicompat.c:19
#define FORMAT_INTERFACE_BUCKETS
Number of buckets to use for format interfaces (should be prime for performance reasons) ...
Definition: format.c:40
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Definition: astobj2.h:1310
static void format_shutdown(void)
Function called when the process is shutting down.
Definition: format.c:71

◆ 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-NULLif joint capability exists
NULLif 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().

227 {
228  const struct ast_format_interface *interface;
229 
230  if (format1->codec != format2->codec) {
231  return NULL;
232  }
233 
234  /* If the two formats are the same structure OR if the codec is the same and no attributes
235  * exist we can immediately return a format with reference count bumped up, since they are
236  * the same.
237  */
238  if ((ast_format_cmp(format1, format2) == AST_FORMAT_CMP_EQUAL && !format1->attribute_data && !format2->attribute_data)) {
239  return ao2_bump((struct ast_format*)format1);
240  }
241 
242  interface = format1->interface ? format1->interface : format2->interface;
243 
244  /* If there is attribute data on either there has to be an interface */
245  return interface->format_get_joint(format1, format2);
246 }
Optional format interface to extend format operations.
Definition: format.h:44
Definition of a media format.
Definition: format.c:43
#define NULL
Definition: resample.c:96
#define ao2_bump(obj)
Definition: astobj2.h:491
void * attribute_data
Attribute specific data, implementation specific.
Definition: format.c:49
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2)
Compare two formats.
Definition: format.c:201

◆ 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
formatto set
attributesstring containing the fmtp line from the SDP
Return values
non-NULLsuccess, attribute values were valid
NULLfailure, 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().

287 {
288  const struct ast_format_interface *interface = format->interface;
289 
290  if (!interface) {
292  if (format_interface) {
293  interface = format_interface->interface;
294  ao2_ref(format_interface, -1);
295  }
296  }
297 
299  return ao2_bump((struct ast_format*)format);
300  }
301 
302  return interface->format_parse_sdp_fmtp(format, attributes);
303 }
const char * name
Name for this codec.
Definition: codec.h:46
Optional format interface to extend format operations.
Definition: format.h:44
The arg parameter is a search key, but is not an object.
Definition: astobj2.h:1105
const struct ast_format_interface * interface
Pointer to the format interface itself.
Definition: format.c:59
Definition of a media format.
Definition: format.c:43
static struct ao2_container * interfaces
Container for registered format interfaces.
Definition: format.c:65
#define ao2_bump(obj)
Definition: astobj2.h:491
#define ao2_ref(o, delta)
Definition: astobj2.h:464
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
struct ast_format *(*const format_parse_sdp_fmtp)(const struct ast_format *format, const char *attributes)
Parse SDP attribute information, interpret it, and store it in the format structure.
Definition: format.h:110
#define ao2_find(container, arg, flags)
Definition: astobj2.h:1756
Structure used when registering a format interface.
Definition: format.c:57

◆ 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
Stasismessage type for format registration
NULLon 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
formatThe media format
attribute_dataThe 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().

131 {
132  format->attribute_data = attribute_data;
133 }
void * attribute_data
Attribute specific data, implementation specific.
Definition: format.c:49

◆ 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
formatThe media format
channel_countThe 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().

141 {
142  format->channel_count = channel_count;
143 }
unsigned int channel_count
The number if audio channels used, if more than one an interleaved format is required.
Definition: format.c:53

◆ 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
Stasismessage type for format unregistration
NULLon error

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