diff options
| author | Matthew Jordan <mjordan@digium.com> | 2014-07-20 22:06:33 +0000 |
|---|---|---|
| committer | Matthew Jordan <mjordan@digium.com> | 2014-07-20 22:06:33 +0000 |
| commit | a2c912e9972c91973ea66902d217746133f96026 (patch) | |
| tree | 50e01d14ba62950e3f78766d5ba435ba51ca327d /include/asterisk/format.h | |
| parent | b299052e203807c9a2111eb2cd919246d7589cb3 (diff) | |
media formats: re-architect handling of media for performance improvements
In the old times media formats were represented using a bit field. This was
fast but had a few limitations.
1. Asterisk was limited in how many formats it could handle.
2. Formats, being a bit field, could not include any attribute information.
A format was strictly its type, e.g., "this is ulaw".
This was changed in Asterisk 10 (see
https://wiki.asterisk.org/wiki/display/AST/Media+Architecture+Proposal for
notes on that work) which led to the creation of the ast_format structure.
This structure allowed Asterisk to handle attributes and bundle information
with a format.
Additionally, ast_format_cap was created to act as a container for multiple
formats that, together, formed the capability of some entity. Another
mechanism was added to allow logic to be registered which performed format
attribute negotiation. Everywhere throughout the codebase Asterisk was
changed to use this strategy.
Unfortunately, in software, there is no free lunch. These new capabilities
came at a cost.
Performance analysis and profiling showed that we spend an inordinate
amount of time comparing, copying, and generally manipulating formats and
their related structures. Basic prototyping has shown that a reasonably
large performance improvement could be made in this area. This patch is the
result of that project, which overhauled the media format architecture
and its usage in Asterisk to improve performance.
Generally, the new philosophy for handling formats is as follows:
* The ast_format structure is reference counted. This removed a large amount
of the memory allocations and copying that was done in prior versions.
* In order to prevent race conditions while keeping things performant, the
ast_format structure is immutable by convention and lock-free. Violate this
tenet at your peril!
* Because formats are reference counted, codecs are also reference counted.
The Asterisk core generally provides built-in codecs and caches the
ast_format structures created to represent them. Generally, to prevent
inordinate amounts of module reference bumping, codecs and formats can be
added at run-time but cannot be removed.
* All compatibility with the bit field representation of codecs/formats has
been moved to a compatibility API. The primary user of this representation
is chan_iax2, which must continue to maintain its bit-field usage of formats
for interoperability concerns.
* When a format is negotiated with attributes, or when a format cannot be
represented by one of the cached formats, a new format object is created or
cloned from an existing format. That format may have the same codec
underlying it, but is a different format than a version of the format with
different attributes or without attributes.
* While formats are reference counted objects, the reference count maintained
on the format should be manipulated with care. Formats are generally cached
and will persist for the lifetime of Asterisk and do not explicitly need
to have their lifetime modified. An exception to this is when the user of a
format does not know where the format came from *and* the user may outlive
the provider of the format. This occurs, for example, when a format is read
from a channel: the channel may have a format with attributes (hence,
non-cached) and the user of the format may last longer than the channel (if
the reference to the channel is released prior to the format's reference).
For more information on this work, see the API design notes:
https://wiki.asterisk.org/wiki/display/AST/Media+Format+Rewrite
Finally, this work was the culmination of a large number of developer's
efforts. Extra thanks goes to Corey Farrell, who took on a large amount of the
work in the Asterisk core, chan_sip, and was an invaluable resource in peer
reviews throughout this project.
There were a substantial number of patches contributed during this work; the
following issues/patch names simply reflect some of the work (and will cause
the release scripts to give attribution to the individuals who work on them).
Reviews:
https://reviewboard.asterisk.org/r/3814
https://reviewboard.asterisk.org/r/3808
https://reviewboard.asterisk.org/r/3805
https://reviewboard.asterisk.org/r/3803
https://reviewboard.asterisk.org/r/3801
https://reviewboard.asterisk.org/r/3798
https://reviewboard.asterisk.org/r/3800
https://reviewboard.asterisk.org/r/3794
https://reviewboard.asterisk.org/r/3793
https://reviewboard.asterisk.org/r/3792
https://reviewboard.asterisk.org/r/3791
https://reviewboard.asterisk.org/r/3790
https://reviewboard.asterisk.org/r/3789
https://reviewboard.asterisk.org/r/3788
https://reviewboard.asterisk.org/r/3787
https://reviewboard.asterisk.org/r/3786
https://reviewboard.asterisk.org/r/3784
https://reviewboard.asterisk.org/r/3783
https://reviewboard.asterisk.org/r/3778
https://reviewboard.asterisk.org/r/3774
https://reviewboard.asterisk.org/r/3775
https://reviewboard.asterisk.org/r/3772
https://reviewboard.asterisk.org/r/3761
https://reviewboard.asterisk.org/r/3754
https://reviewboard.asterisk.org/r/3753
https://reviewboard.asterisk.org/r/3751
https://reviewboard.asterisk.org/r/3750
https://reviewboard.asterisk.org/r/3748
https://reviewboard.asterisk.org/r/3747
https://reviewboard.asterisk.org/r/3746
https://reviewboard.asterisk.org/r/3742
https://reviewboard.asterisk.org/r/3740
https://reviewboard.asterisk.org/r/3739
https://reviewboard.asterisk.org/r/3738
https://reviewboard.asterisk.org/r/3737
https://reviewboard.asterisk.org/r/3736
https://reviewboard.asterisk.org/r/3734
https://reviewboard.asterisk.org/r/3722
https://reviewboard.asterisk.org/r/3713
https://reviewboard.asterisk.org/r/3703
https://reviewboard.asterisk.org/r/3689
https://reviewboard.asterisk.org/r/3687
https://reviewboard.asterisk.org/r/3674
https://reviewboard.asterisk.org/r/3671
https://reviewboard.asterisk.org/r/3667
https://reviewboard.asterisk.org/r/3665
https://reviewboard.asterisk.org/r/3625
https://reviewboard.asterisk.org/r/3602
https://reviewboard.asterisk.org/r/3519
https://reviewboard.asterisk.org/r/3518
https://reviewboard.asterisk.org/r/3516
https://reviewboard.asterisk.org/r/3515
https://reviewboard.asterisk.org/r/3512
https://reviewboard.asterisk.org/r/3506
https://reviewboard.asterisk.org/r/3413
https://reviewboard.asterisk.org/r/3410
https://reviewboard.asterisk.org/r/3387
https://reviewboard.asterisk.org/r/3388
https://reviewboard.asterisk.org/r/3389
https://reviewboard.asterisk.org/r/3390
https://reviewboard.asterisk.org/r/3321
https://reviewboard.asterisk.org/r/3320
https://reviewboard.asterisk.org/r/3319
https://reviewboard.asterisk.org/r/3318
https://reviewboard.asterisk.org/r/3266
https://reviewboard.asterisk.org/r/3265
https://reviewboard.asterisk.org/r/3234
https://reviewboard.asterisk.org/r/3178
ASTERISK-23114 #close
Reported by: mjordan
media_formats_translation_core.diff uploaded by kharwell (License 6464)
rb3506.diff uploaded by mjordan (License 6283)
media_format_app_file.diff uploaded by kharwell (License 6464)
misc-2.diff uploaded by file (License 5000)
chan_mild-3.diff uploaded by file (License 5000)
chan_obscure.diff uploaded by file (License 5000)
jingle.diff uploaded by file (License 5000)
funcs.diff uploaded by file (License 5000)
formats.diff uploaded by file (License 5000)
core.diff uploaded by file (License 5000)
bridges.diff uploaded by file (License 5000)
mf-codecs-2.diff uploaded by file (License 5000)
mf-app_fax.diff uploaded by file (License 5000)
mf-apps-3.diff uploaded by file (License 5000)
media-formats-3.diff uploaded by file (License 5000)
ASTERISK-23715
rb3713.patch uploaded by coreyfarrell (License 5909)
rb3689.patch uploaded by mjordan (License 6283)
ASTERISK-23957
rb3722.patch uploaded by mjordan (License 6283)
mf-attributes-3.diff uploaded by file (License 5000)
ASTERISK-23958
Tested by: jrose
rb3822.patch uploaded by coreyfarrell (License 5909)
rb3800.patch uploaded by jrose (License 6182)
chan_sip.diff uploaded by mjordan (License 6283)
rb3747.patch uploaded by jrose (License 6182)
ASTERISK-23959 #close
Tested by: sgriepentrog, mjordan, coreyfarrell
sip_cleanup.diff uploaded by opticron (License 6273)
chan_sip_caps.diff uploaded by mjordan (License 6283)
rb3751.patch uploaded by coreyfarrell (License 5909)
chan_sip-3.diff uploaded by file (License 5000)
ASTERISK-23960 #close
Tested by: opticron
direct_media.diff uploaded by opticron (License 6273)
pjsip-direct-media.diff uploaded by file (License 5000)
format_cap_remove.diff uploaded by opticron (License 6273)
media_format_fixes.diff uploaded by opticron (License 6273)
chan_pjsip-2.diff uploaded by file (License 5000)
ASTERISK-23966 #close
Tested by: rmudgett
rb3803.patch uploaded by rmudgetti (License 5621)
chan_dahdi.diff uploaded by file (License 5000)
ASTERISK-24064 #close
Tested by: coreyfarrell, mjordan, opticron, file, rmudgett, sgriepentrog, jrose
rb3814.patch uploaded by rmudgett (License 5621)
moh_cleanup.diff uploaded by opticron (License 6273)
bridge_leak.diff uploaded by opticron (License 6273)
translate.diff uploaded by file (License 5000)
rb3795.patch uploaded by rmudgett (License 5621)
tls_fix.diff uploaded by mjordan (License 6283)
fax-mf-fix-2.diff uploaded by file (License 5000)
rtp_transfer_stuff uploaded by mjordan (License 6283)
rb3787.patch uploaded by rmudgett (License 5621)
media-formats-explicit-translate-format-3.diff uploaded by file (License 5000)
format_cache_case_fix.diff uploaded by opticron (License 6273)
rb3774.patch uploaded by rmudgett (License 5621)
rb3775.patch uploaded by rmudgett (License 5621)
rtp_engine_fix.diff uploaded by opticron (License 6273)
rtp_crash_fix.diff uploaded by opticron (License 6273)
rb3753.patch uploaded by mjordan (License 6283)
rb3750.patch uploaded by mjordan (License 6283)
rb3748.patch uploaded by rmudgett (License 5621)
media_format_fixes.diff uploaded by opticron (License 6273)
rb3740.patch uploaded by mjordan (License 6283)
rb3739.patch uploaded by mjordan (License 6283)
rb3734.patch uploaded by mjordan (License 6283)
rb3689.patch uploaded by mjordan (License 6283)
rb3674.patch uploaded by coreyfarrell (License 5909)
rb3671.patch uploaded by coreyfarrell (License 5909)
rb3667.patch uploaded by coreyfarrell (License 5909)
rb3665.patch uploaded by mjordan (License 6283)
rb3625.patch uploaded by coreyfarrell (License 5909)
rb3602.patch uploaded by coreyfarrell (License 5909)
format_compatibility-2.diff uploaded by file (License 5000)
core.diff uploaded by file (License 5000)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@419044 65c4cc65-6c06-0410-ace0-fbb531ad65f3
Diffstat (limited to 'include/asterisk/format.h')
| -rw-r--r-- | include/asterisk/format.h | 553 |
1 files changed, 222 insertions, 331 deletions
diff --git a/include/asterisk/format.h b/include/asterisk/format.h index 885c62b2d..32f9f2b40 100644 --- a/include/asterisk/format.h +++ b/include/asterisk/format.h @@ -1,9 +1,9 @@ /* * Asterisk -- An open source telephony toolkit. * - * Copyright (C) 2010, Digium, Inc. + * Copyright (C) 2014, Digium, Inc. * - * David Vossel <dvossel@digium.com> + * Joshua Colp <jcolp@digium.com> * * See http://www.asterisk.org for more information about * the Asterisk project. Please do not directly contact @@ -18,464 +18,354 @@ /*! * \file - * \brief Format API + * \brief Media Format API * - * \author David Vossel <dvossel@digium.com> + * \author Joshua Colp <jcolp@digium.com> */ +#include "asterisk/codec.h" + #ifndef _AST_FORMAT_H_ #define _AST_FORMAT_H_ -#include "asterisk/astobj2.h" -#include "asterisk/silk.h" -#include "asterisk/celt.h" -#include "asterisk/opus.h" -#define AST_FORMAT_ATTR_SIZE 64 -#define AST_FORMAT_INC 100000 - -/*! This is the value that ends a var list of format attribute - * key value pairs. */ -#define AST_FORMAT_ATTR_END -1 - -/* \brief Format Categories*/ -enum ast_format_type { - AST_FORMAT_TYPE_AUDIO = 1 * AST_FORMAT_INC, - AST_FORMAT_TYPE_VIDEO = 2 * AST_FORMAT_INC, - AST_FORMAT_TYPE_IMAGE = 3 * AST_FORMAT_INC, - AST_FORMAT_TYPE_TEXT = 4 * AST_FORMAT_INC, -}; - -enum ast_format_id { - /*! G.723.1 compression */ - AST_FORMAT_G723_1 = 1 + AST_FORMAT_TYPE_AUDIO, - /*! GSM compression */ - AST_FORMAT_GSM = 2 + AST_FORMAT_TYPE_AUDIO, - /*! Raw mu-law data (G.711) */ - AST_FORMAT_ULAW = 3 + AST_FORMAT_TYPE_AUDIO, - /*! Raw A-law data (G.711) */ - AST_FORMAT_ALAW = 4 + AST_FORMAT_TYPE_AUDIO, - /*! ADPCM (G.726, 32kbps, AAL2 codeword packing) */ - AST_FORMAT_G726_AAL2 = 5 + AST_FORMAT_TYPE_AUDIO, - /*! ADPCM (IMA) */ - AST_FORMAT_ADPCM = 6 + AST_FORMAT_TYPE_AUDIO, - /*! LPC10, 180 samples/frame */ - AST_FORMAT_LPC10 = 7 + AST_FORMAT_TYPE_AUDIO, - /*! G.729A audio */ - AST_FORMAT_G729A = 8 + AST_FORMAT_TYPE_AUDIO, - /*! SpeeX Free Compression */ - AST_FORMAT_SPEEX = 9 + AST_FORMAT_TYPE_AUDIO, - /*! iLBC Free Compression */ - AST_FORMAT_ILBC = 10 + AST_FORMAT_TYPE_AUDIO, - /*! ADPCM (G.726, 32kbps, RFC3551 codeword packing) */ - AST_FORMAT_G726 = 11 + AST_FORMAT_TYPE_AUDIO, - /*! G.722 */ - AST_FORMAT_G722 = 12 + AST_FORMAT_TYPE_AUDIO, - /*! G.722.1 (also known as Siren7, 32kbps assumed) */ - AST_FORMAT_SIREN7 = 13 + AST_FORMAT_TYPE_AUDIO, - /*! G.722.1 Annex C (also known as Siren14, 48kbps assumed) */ - AST_FORMAT_SIREN14 = 14 + AST_FORMAT_TYPE_AUDIO, - /*! G.719 (64 kbps assumed) */ - AST_FORMAT_G719 = 15 + AST_FORMAT_TYPE_AUDIO, - /*! SpeeX Wideband (16kHz) Free Compression */ - AST_FORMAT_SPEEX16 = 16 + AST_FORMAT_TYPE_AUDIO, - /*! Raw mu-law data (G.711) */ - AST_FORMAT_TESTLAW = 17 + AST_FORMAT_TYPE_AUDIO, - /*! SILK format */ - AST_FORMAT_SILK = 18 + AST_FORMAT_TYPE_AUDIO, - /*! Raw 16-bit Signed Linear (8000 Hz) PCM */ - AST_FORMAT_SLINEAR = 19 + AST_FORMAT_TYPE_AUDIO, - /*! Raw 16-bit Signed Linear (12000 Hz) PCM */ - AST_FORMAT_SLINEAR12 = 20 + AST_FORMAT_TYPE_AUDIO, - /*! Raw 16-bit Signed Linear (16000 Hz) PCM */ - AST_FORMAT_SLINEAR16 = 21 + AST_FORMAT_TYPE_AUDIO, - /*! Raw 16-bit Signed Linear (24000 Hz) PCM */ - AST_FORMAT_SLINEAR24 = 22 + AST_FORMAT_TYPE_AUDIO, - /*! Raw 16-bit Signed Linear (32000 Hz) PCM */ - AST_FORMAT_SLINEAR32 = 23 + AST_FORMAT_TYPE_AUDIO, - /*! Raw 16-bit Signed Linear (44100 Hz) PCM just because we can. */ - AST_FORMAT_SLINEAR44 = 24 + AST_FORMAT_TYPE_AUDIO, - /*! Raw 16-bit Signed Linear (48000 Hz) PCM */ - AST_FORMAT_SLINEAR48 = 25 + AST_FORMAT_TYPE_AUDIO, - /*! Raw 16-bit Signed Linear (96000 Hz) PCM */ - AST_FORMAT_SLINEAR96 = 26 + AST_FORMAT_TYPE_AUDIO, - /*! Raw 16-bit Signed Linear (192000 Hz) PCM. maybe we're taking this too far. */ - AST_FORMAT_SLINEAR192 = 27 + AST_FORMAT_TYPE_AUDIO, - AST_FORMAT_SPEEX32 = 28 + AST_FORMAT_TYPE_AUDIO, - AST_FORMAT_CELT = 29 + AST_FORMAT_TYPE_AUDIO, - /*! Opus */ - AST_FORMAT_OPUS = 30 + AST_FORMAT_TYPE_AUDIO, - - /*! H.261 Video */ - AST_FORMAT_H261 = 1 + AST_FORMAT_TYPE_VIDEO, - /*! H.263 Video */ - AST_FORMAT_H263 = 2 + AST_FORMAT_TYPE_VIDEO, - /*! H.263+ Video */ - AST_FORMAT_H263_PLUS = 3 + AST_FORMAT_TYPE_VIDEO, - /*! H.264 Video */ - AST_FORMAT_H264 = 4 + AST_FORMAT_TYPE_VIDEO, - /*! MPEG4 Video */ - AST_FORMAT_MP4_VIDEO = 5 + AST_FORMAT_TYPE_VIDEO, - /*! VP8 */ - AST_FORMAT_VP8 = 6 + AST_FORMAT_TYPE_VIDEO, - - /*! JPEG Images */ - AST_FORMAT_JPEG = 1 + AST_FORMAT_TYPE_IMAGE, - /*! PNG Images */ - AST_FORMAT_PNG = 2 + AST_FORMAT_TYPE_IMAGE, - - /*! T.140 RED Text format RFC 4103 */ - AST_FORMAT_T140RED = 1 + AST_FORMAT_TYPE_TEXT, - /*! T.140 Text format - ITU T.140, RFC 4103 */ - AST_FORMAT_T140 = 2 + AST_FORMAT_TYPE_TEXT, -}; - -/*! Determine what type of media a ast_format_id is. */ -#define AST_FORMAT_GET_TYPE(id) (((int) (id / AST_FORMAT_INC)) * AST_FORMAT_INC) - - -/*! \brief This structure contains the buffer used for format attributes */ -struct ast_format_attr { - /*! The buffer formats can use to represent attributes */ - uint32_t format_attr[AST_FORMAT_ATTR_SIZE]; - /*! If a format's payload needs to pass through that a new marker is required - * for RTP, this variable will be set. */ - uint8_t rtp_marker_bit; -}; - -/*! \brief Represents a media format within Asterisk. */ -struct ast_format { - /*! The unique id representing this format from all the other formats. */ - enum ast_format_id id; - /*! Attribute structure used to associate attributes with a format. */ - struct ast_format_attr fattr; -}; +struct ast_format; +/*! \brief Format comparison results */ enum ast_format_cmp_res { - /*! structure 1 is identical to structure 2. */ + /*! Both formats are equivalent to eachother */ AST_FORMAT_CMP_EQUAL = 0, - /*! structure 1 contains elements not in structure 2. */ + /*! Both formats are completely different and not the same in any way */ AST_FORMAT_CMP_NOT_EQUAL, - /*! structure 1 is a proper subset of the elements in structure 2.*/ + /*! Both formats are similar but not equivalent */ AST_FORMAT_CMP_SUBSET, }; -/*! \brief Definition of supported media formats (codecs) */ -struct ast_format_list { - struct ast_format format; /*!< The unique format. */ - char name[64]; /*!< short name */ - unsigned int samplespersecond; /*!< Number of samples per second (8000/16000) */ - char desc[128]; /*!< Description */ - int fr_len; /*!< Single frame length in bytes */ - int min_ms; /*!< Min value */ - int max_ms; /*!< Max value */ - int inc_ms; /*!< Increment */ - int def_ms; /*!< Default value */ - unsigned int flags; /*!< Smoother flags */ - int cur_ms; /*!< Current value */ - int custom_entry; -}; - -/*! \brief A format must register an attribute interface if it requires the use of the format attributes void pointer */ -struct ast_format_attr_interface { - /*! format type */ - enum ast_format_id id; - - /*! \brief Determine if format_attr 1 is a subset of format_attr 2. +/*! \brief Optional format interface to extend format operations */ +struct ast_format_interface { + /*! + * \brief Callback for when the format is destroyed, used to release attribute resources * - * \retval ast_format_cmp_res representing the result of comparing fattr1 and fattr2. + * \param format The format structure to destroy */ - enum ast_format_cmp_res (* const format_attr_cmp)(const struct ast_format_attr *fattr1, const struct ast_format_attr *fattr2); + void (*const format_destroy)(struct ast_format *format); - /*! \brief Get joint attributes of same format type if they exist. + /*! + * \brief Callback for when the format is cloned, used to clone attributes + * + * \param src Source format of attributes + * \param dst Destination format for attributes * - * \retval 0 if joint attributes exist - * \retval -1 if no joint attributes are present + * \retval 0 success + * \retval -1 failure */ - int (* const format_attr_get_joint)(const struct ast_format_attr *fattr1, const struct ast_format_attr *fattr2, struct ast_format_attr *result); - - /*! \brief Set format capabilities from a list of key value pairs ending with AST_FORMAT_ATTR_END. - * \note This function does not need to call va_end of the va_list. */ - void (* const format_attr_set)(struct ast_format_attr *format_attr, va_list ap); + int (*const format_clone)(const struct ast_format *src, struct ast_format *dst); /*! - * \brief Find out if format capabilities in va_list are in format. - * \note This function does not need to call va_end of the va_list. + * \brief Determine if format 1 is a subset of format 2. * - * \note This function is optional. In many cases the format_attr_cmp - * function can be used to derive these results. If it is possible - * that some format attributes have no bearing on the equality of two formats, this - * function must exist. + * \param format1 First format to compare + * \param format2 Second format which the first is compared against * - * \retval 0 if all attributes exist - * \retval -1 if any of the attributes not present + * \retval ast_format_cmp_res representing the result of comparing format1 and format2. */ - int (* const format_attr_isset)(const struct ast_format_attr *format_attr, va_list ap); + enum ast_format_cmp_res (* const format_cmp)(const struct ast_format *format1, + const struct ast_format *format2); - /* - * \brief Return a value for a specific format key. Return that value in the void pointer. + /*! + * \brief Get a format with the joint compatible attributes of both provided formats. + * + * \param format1 The first format + * \param format2 The second format + * + * \retval non-NULL if joint format + * \retval NULL if no joint format * - * \note It is not expected that all key value pairs can be returned, but those that can should - * be documented as such. + * \note The returned format has its reference count incremented and must be released using + * ao2_ref or ao2_cleanup. + */ + struct ast_format *(* const format_get_joint)(const struct ast_format *format1, + const struct ast_format *format2); + + /*! + * \brief Set an attribute on a format * - * \note This function is optional if key value pairs are not allowed to be accessed. This - * will result in -1 always being returned. + * \param name The name of the attribute + * \param value The value of the attribute * - * \retval 0 Success, value was found and copied into void pointer. - * \retval -1 failure, Value was either not found, or not allowed to be accessed. + * \retval non-NULL success + * \retval NULL failure */ - int (* const format_attr_get_val)(const struct ast_format_attr *format_attr, int key, void *val); + struct ast_format *(* const format_attribute_set)(const struct ast_format *format, + const char *name, const char *value); - /* - * \brief Parse SDP attribute information, interpret it, and store it in ast_format_attr structure. + /*! + * \brief Parse SDP attribute information, interpret it, and store it in the format structure. + * + * \param format Format to set attributes on + * \param attributes A string containing only the attributes from the fmtp line * - * \retval 0 Success, values were valid - * \retval -1 Failure, some values were not acceptable + * \retval non-NULL Success, values were valid + * \retval NULL Failure, some values were not acceptable */ - int (* const format_attr_sdp_parse)(struct ast_format_attr *format_attr, const char *attributes); + struct ast_format *(* const format_parse_sdp_fmtp)(const struct ast_format *format, const char *attributes); /*! * \brief Generate SDP attribute information from an ast_format_attr structure. * + * \param format The format containing attributes + * \param payload The payload number to place into the fmtp line + * \param str The generated fmtp line + * * \note This callback should generate a full fmtp line using the provided payload number. */ - void (* const format_attr_sdp_generate)(const struct ast_format_attr *format_attr, unsigned int payload, struct ast_str **str); + void (* const format_generate_sdp_fmtp)(const struct ast_format *format, unsigned int payload, + struct ast_str **str); }; /*! - * \brief 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. + * \brief Initialize media format support * - * \param format to set - * \param attributes string containing the fmtp line from the SDP - * - * \retval 0 success, attribute values were valid - * \retval -1 failure, values were not acceptable + * \retval 0 success + * \retval -1 failure */ -int ast_format_sdp_parse(struct ast_format *format, const char *attributes); +int ast_format_init(void); /*! - * \brief 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. + * \brief Create a new media format * - * \param format to generate an fmtp line for - * \param payload numerical payload for the fmtp line - * \param str structure that the fmtp line will be appended to + * \param codec The codec to use + * + * \retval non-NULL success + * \retval NULL failure + * + * \note The format is returned with reference count incremented. It must be released using + * ao2_ref or ao2_cleanup. */ -void ast_format_sdp_generate(const struct ast_format *format, unsigned int payload, struct ast_str **str); +struct ast_format *ast_format_create(struct ast_codec *codec); /*! - * \brief This function is used to set an ast_format object to represent a media format - * with optional format attributes represented by format specific key value pairs. - * - * \param format to set - * \param id format id to set on format - * \param set_attributes are there attributes to set on this format. 0 == false, 1 == True. - * \param ... var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END; + * \brief Create a new media format with a specific name * - * \details Example usage. - * ast_format_set(format, AST_FORMAT_ULAW, 0); // no capability attributes are needed for ULAW + * \param format_name The name to use for the format + * \param codec The codec to use * - * ast_format_set(format, AST_FORMAT_SILK, 1, // SILK has capability attributes. - * AST_FORMAT_SILK_ATTR_RATE, 24000, - * AST_FORMAT_SILK_ATTR_RATE, 16000, - * AST_FORMAT_SILK_ATTR_RATE, 12000, - * AST_FORMAT_SILK_ATTR_RATE, 8000, - * AST_FORMAT_ATTR_END); + * \note This creation function should be used when the name of the \c codec + * cannot be explicitly used for the name of the format. This is the case for + * codecs with multiple sample rates * - * \note This function will initialize the ast_format structure. + * \note The format is returned with reference count incremented. It must be released using + * ao2_ref or ao2_cleanup. * - * \return Pointer to ast_format object, same pointer that is passed in - * by the first argument. + * \retval non-NULL success + * \retval NULL failure */ -struct ast_format *ast_format_set(struct ast_format *format, enum ast_format_id id, int set_attributes, ... ); +struct ast_format *ast_format_create_named(const char *format_name, struct ast_codec *codec); /*! - * \brief After ast_format_set has been used on a function, this function can be used to - * set additional format attributes to the structure. + * \brief Clone an existing media format so it can be modified * - * \param format to set - * \param ... var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END; - * - * \details Example usage. - * ast_format_set(format, AST_FORMAT_SILK, 0); - * ast_format_append(format, // SILK has capability attributes. - * AST_FORMAT_SILK_ATTR_RATE, 24000, - * AST_FORMAT_SILK_ATTR_RATE, 16000, - * AST_FORMAT_SILK_ATTR_RATE, 12000, - * AST_FORMAT_SILK_ATTR_RATE, 8000, - * AST_FORMAT_ATTR_END); - * - * \return Pointer to ast_format object, same pointer that is passed in - * by the first argument. + * \param format The existing media format + * + * \note The returned format is a new ao2 object. It must be released using ao2_cleanup. + * + * \retval non-NULL success + * \retval NULL failure */ -struct ast_format *ast_format_append(struct ast_format *format, ... ); +struct ast_format *ast_format_clone(const struct ast_format *format); /*! - * \brief Clears the format stucture. + * \brief Compare two formats + * + * \retval ast_format_cmp_res representing the result of comparing format1 and format2. */ -void ast_format_clear(struct ast_format *format); +enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2); /*! - * \brief This function is used to set an ast_format object to represent a media format - * with optional capability attributes represented by format specific key value pairs. + * \brief Get a common joint capability between two formats * - * \details Example usage. Is this SILK format capable of 8khz - * is_8khz = ast_format_isset(format, AST_FORMAT_SILK_CAP_RATE, 8000); + * \retval non-NULL if joint capability exists + * \retval NULL if no joint capability exists * - * \return 0, The format key value pairs are within the capabilities defined in this structure. - * \return -1, The format key value pairs are _NOT_ within the capabilities of this structure. + * \note The returned format must be treated as immutable. */ -int ast_format_isset(const struct ast_format *format, ... ); +struct ast_format *ast_format_joint(const struct ast_format *format1, const struct ast_format *format2); /*! - * \brief Get a value from a format containing attributes. - * \note The key represents the format attribute to be retrieved, and the void pointer - * is to the structure that value will be stored in. It must be known what structure a - * key represents. + * \brief Set an attribute on a format to a specific value * - * \retval 0, success - * \retval -1, failure - */ -int ast_format_get_value(const struct ast_format *format, int key, void *value); - -/*! - * \brief Compare ast_formats structures + * \param format The format to set the attribute on + * \param name Attribute name + * \param value Attribute value * - * \retval ast_format_cmp_res representing the result of comparing format1 and format2. + * \retval non-NULL success + * \retval NULL failure */ -enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2); +struct ast_format *ast_format_attribute_set(const struct ast_format *format, const char *name, + const char *value); /*! - * \brief Find joint format attributes of two ast_format - * structures containing the same uid and return the intersection in the - * result structure. + * \brief 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. * - * retval 0, joint attribute capabilities exist. - * retval -1, no joint attribute capabilities exist. + * \param format to set + * \param attributes string containing the fmtp line from the SDP + * + * \retval non-NULL success, attribute values were valid + * \retval NULL failure, values were not acceptable */ -int ast_format_joint(const struct ast_format *format1, const struct ast_format *format2, struct ast_format *result); +struct ast_format *ast_format_parse_sdp_fmtp(const struct ast_format *format, const char *attributes); /*! - * \brief copy format src into format dst. + * \brief 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. + * + * \param format to generate an fmtp line for + * \param payload numerical payload for the fmtp line + * \param str structure that the fmtp line will be appended to */ -void ast_format_copy(struct ast_format *dst, const struct ast_format *src); +void ast_format_generate_sdp_fmtp(const struct ast_format *format, unsigned int payload, struct ast_str **str); /*! - * \brief Set the rtp mark value on the format to indicate to the interface - * writing this format's payload that a new RTP marker is necessary. + * \brief Register a format interface for use with the provided codec + * + * \param codec The name of codec the interface is applicable to + * \param interface A pointer to the interface implementation + * \param mod The module this format interface is provided by + * + * \retval 0 success + * \retval -1 failure */ -void ast_format_set_video_mark(struct ast_format *format); +int __ast_format_interface_register(const char *codec, const struct ast_format_interface *interface, struct ast_module *mod); /*! - * \brief Determine of the marker bit is set or not on this format. + * \brief Register a format interface for use with the provided codec * - * \retval 1, true - * \retval 0, false + * \param codec The name of codec the interface is applicable to + * \param interface A pointer to the interface implementation + * + * \retval 0 success + * \retval -1 failure */ -int ast_format_get_video_mark(const struct ast_format *format); +#define ast_format_interface_register(codec, interface) __ast_format_interface_register(codec, interface, ast_module_info->self) /*! - * \brief ast_format to old bitfield format represenatation + * \brief Get the attribute data on a format * - * \note This is only to be used for IAX2 compatibility + * \param format The media format * - * \retval iax2 representation of ast_format - * \retval 0, if no representation existis for iax2 + * \return Currently set attribute data */ -uint64_t ast_format_to_old_bitfield(const struct ast_format *format); +void *ast_format_get_attribute_data(const struct ast_format *format); /*! - * \brief ast_format_id to old bitfield format represenatation + * \brief Set the attribute data on a format * + * \param format The media format + * \param attribute_data The attribute data */ -uint64_t ast_format_id_to_old_bitfield(enum ast_format_id id); +void ast_format_set_attribute_data(struct ast_format *format, void *attribute_data); /*! - * \brief convert old bitfield format to ast_format represenatation - * \note This is only to be used for IAX2 compatibility + * \brief Get the name associated with a format * - * \retval on success, pointer to the dst format in the input parameters - * \retval on failure, NULL + * \param format The media format + * + * \return The name of the format */ -struct ast_format *ast_format_from_old_bitfield(struct ast_format *dst, uint64_t src); +const char *ast_format_get_name(const struct ast_format *format); /*! - * \brief convert old bitfield format to ast_format_id value + * \brief Get the codec identifier associated with a format + * + * \param format The media format + * + * \return codec identifier */ -enum ast_format_id ast_format_id_from_old_bitfield(uint64_t src); +unsigned int ast_format_get_codec_id(const struct ast_format *format); /*! - * \brief Retrieve the global format list in a read only array. - * \note ast_format_list_destroy must be called on every format - * list retrieved from this function. + * \brief Get the codec name associated with a format + * + * \param format The media format + * + * \return The codec name */ -const struct ast_format_list *ast_format_list_get(size_t *size); +const char *ast_format_get_codec_name(const struct ast_format *format); /*! - * \brief Destroy an ast_format_list gotten from ast_format_list_get() - */ -const struct ast_format_list *ast_format_list_destroy(const struct ast_format_list *list); - -/*! \brief Get the name of a format - * \param format id of format - * \return A static string containing the name of the format or "unknown" if unknown. - */ -const char* ast_getformatname(const struct ast_format *format); - -/*! \brief Returns a string containing all formats pertaining to an format id. - * \param buf a buffer for the output string - * \param size size of buf (bytes) - * \param id format id. - * \return The return value is buf. + * \brief Get whether or not the format can be smoothed + * + * \param format The media format + * + * \retval 0 the format cannot be smoothed + * \retval 1 the format can be smoothed */ -char* ast_getformatname_multiple_byid(char *buf, size_t size, enum ast_format_id id); +int ast_format_can_be_smoothed(const struct ast_format *format); /*! - * \brief Gets a format from a name. - * \param name string of format - * \param format structure to return the format in. - * \return This returns the format pointer given to it on success and NULL on failure + * \brief Get the media type of a format + * + * \param format The media format + * + * \return the media type */ -struct ast_format *ast_getformatbyname(const char *name, struct ast_format *format); +enum ast_media_type ast_format_get_type(const struct ast_format *format); /*! - * \brief Get a name from a format - * \param format to get name of - * \return This returns a static string identifying the format on success, 0 on error. + * \brief Get the default framing size (in milliseconds) for a format + * + * \param format The media format + * + * \return default framing size in milliseconds */ -const char *ast_codec2str(struct ast_format *format); +unsigned int ast_format_get_default_ms(const struct ast_format *format); /*! - * \brief Get the sample rate for a given format. + * \brief Get the minimum amount of media carried in this format + * + * \param format The media format + * + * \return minimum framing size in milliseconds */ -int ast_format_rate(const struct ast_format *format); +unsigned int ast_format_get_minimum_ms(const struct ast_format *format); /*! - * \brief register ast_format_attr_interface with core. + * \brief Get the maximum amount of media carried in this format * - * \retval 0 success - * \retval -1 failure + * \param format The media format + * + * \return maximum framing size in milliseconds */ -int ast_format_attr_reg_interface(const struct ast_format_attr_interface *interface); +unsigned int ast_format_get_maximum_ms(const struct ast_format *format); /*! - * \brief unregister format_attr interface with core. + * \brief Get the minimum number of bytes expected in a frame for this format * - * \retval 0 success - * \retval -1 failure + * \param format The media format + * + * \return minimum expected bytes in a frame for this format */ -int ast_format_attr_unreg_interface(const struct ast_format_attr_interface *interface); +unsigned int ast_format_get_minimum_bytes(const struct ast_format *format); /*! - * \brief Determine if a format is 16bit signed linear of any sample rate. + * \brief Get the sample rate of a media format + * + * \param format The media format + * + * \return sample rate */ -int ast_format_is_slinear(const struct ast_format *format); +unsigned int ast_format_get_sample_rate(const struct ast_format *format); /*! - * \brief Get the best slinear format id for a given sample rate + * \brief Get the length (in milliseconds) for the format with a given number of samples + * + * \param format The media format + * \param samples The number of samples + * + * \return length of media (in milliseconds) */ -enum ast_format_id ast_format_slin_by_rate(unsigned int rate); +unsigned int ast_format_determine_length(const struct ast_format *format, unsigned int samples); /*! * \since 12 @@ -494,4 +384,5 @@ struct stasis_message_type *ast_format_register_type(void); * \retval NULL on error */ struct stasis_message_type *ast_format_unregister_type(void); + #endif /* _AST_FORMAT_H */ |