mirror of
https://github.com/asterisk/asterisk.git
synced 2025-10-10 06:49:40 +00:00
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
This commit is contained in:
Matthew Jordan
@@ -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,217 +18,290 @@
|
||||
|
||||
/*!
|
||||
* \file
|
||||
* \brief Format Capability API
|
||||
* \brief Format Capabilities API
|
||||
*
|
||||
* \author David Vossel <dvossel@digium.com>
|
||||
* \author Joshua Colp <jcolp@digium.com>
|
||||
*/
|
||||
|
||||
#ifndef _AST_FORMATCAP_H_
|
||||
#define _AST_FORMATCAP_H_
|
||||
#ifndef _AST_FORMAT_CAP_H_
|
||||
#define _AST_FORMAT_CAP_H_
|
||||
|
||||
/*! Capabilities are represented by an opaque structure statically defined in format_capability.c */
|
||||
#include "asterisk/codec.h"
|
||||
|
||||
/*! Capabilities are represented by an opaque structure statically defined in format_cap.c */
|
||||
struct ast_format_cap;
|
||||
|
||||
enum ast_format_cap_flags {
|
||||
/*!
|
||||
* The ast_format_cap will be allocated with no lock.
|
||||
* Useful if there is a separate lock used to protect the structure
|
||||
* Default format capabilities settings
|
||||
*/
|
||||
AST_FORMAT_CAP_FLAG_NOLOCK = (1 << 0),
|
||||
/*!
|
||||
* String representations of the formats are cached on the structure.
|
||||
* Useful if string representation is frequently requested of the structure.
|
||||
*/
|
||||
AST_FORMAT_CAP_FLAG_CACHE_STRINGS = (1 << 1),
|
||||
AST_FORMAT_CAP_FLAG_DEFAULT = 0,
|
||||
};
|
||||
|
||||
/*!
|
||||
* \brief Allocate a new ast_format_cap structure
|
||||
*
|
||||
* \param flags Modifiers of struct behavior.
|
||||
*
|
||||
* \retval ast_format_cap object on success.
|
||||
* \retval NULL on failure.
|
||||
*/
|
||||
struct ast_format_cap *ast_format_cap_alloc(enum ast_format_cap_flags flags);
|
||||
struct ast_format_cap *__ast_format_cap_alloc(enum ast_format_cap_flags flags);
|
||||
struct ast_format_cap *__ast_format_cap_alloc_debug(enum ast_format_cap_flags flags, const char *tag, const char *file, int line, const char *func);
|
||||
|
||||
#ifdef REF_DEBUG
|
||||
#define ast_format_cap_alloc(flags) \
|
||||
__ast_format_cap_alloc_debug((flags), "", __FILE__, __LINE__, __PRETTY_FUNCTION__)
|
||||
#define ast_t_format_cap_alloc(flags, tag) \
|
||||
__ast_format_cap_alloc_debug((flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
|
||||
#else
|
||||
#define ast_format_cap_alloc(flags) \
|
||||
__ast_format_cap_alloc((flags))
|
||||
#define ast_t_format_cap_alloc(flags, tag) \
|
||||
__ast_format_cap_alloc((flags))
|
||||
#endif
|
||||
|
||||
/*!
|
||||
* \brief Destroy an ast_format_cap structure.
|
||||
* \brief Set the global framing.
|
||||
*
|
||||
* \return NULL
|
||||
* \param cap The capabilities structure.
|
||||
* \param framing The framing value (in milliseconds).
|
||||
*
|
||||
* \note This is used if a format does not provide a framing itself. Note that
|
||||
* adding subsequent formats to the \c ast_format_cap structure may
|
||||
* override this value, if the framing they require is less than the
|
||||
* value set by this function.
|
||||
*/
|
||||
void *ast_format_cap_destroy(struct ast_format_cap *cap);
|
||||
void ast_format_cap_set_framing(struct ast_format_cap *cap, unsigned int framing);
|
||||
|
||||
/*!
|
||||
* \brief Get the global framing.
|
||||
*
|
||||
* \param cap The capabilities structure.
|
||||
*
|
||||
* \retval 0 if no formats are in the structure and no framing has been provided
|
||||
* \retval The global framing value (in milliseconds)
|
||||
*
|
||||
* \note This will be the minimum framing allowed across all formats in the
|
||||
* capabilities structure, or an overridden value
|
||||
*/
|
||||
unsigned int ast_format_cap_get_framing(const struct ast_format_cap *cap);
|
||||
|
||||
/*!
|
||||
* \brief Add format capability to capabilities structure.
|
||||
*
|
||||
* \note A copy of the input format is made and that copy is
|
||||
* what is placed in the ast_format_cap structure. The actual
|
||||
* input format ptr is not stored.
|
||||
*/
|
||||
void ast_format_cap_add(struct ast_format_cap *cap, const struct ast_format *format);
|
||||
|
||||
/*!
|
||||
* \brief Add all formats Asterisk knows about for a specific type to
|
||||
* the capabilities structure. Formats with attributes are set, but their
|
||||
* attributes are initilized to 0's. An attribute structure of 0's should
|
||||
* indicate to the format attribute interface that the format has full
|
||||
* capabilities.
|
||||
* \param cap The capabilities structure to add to.
|
||||
* \param format The format to add.
|
||||
* \param framing The framing for the format (in milliseconds).
|
||||
*
|
||||
* \note A copy of the input format is made and that copy is
|
||||
* what is placed in the ast_format_cap structure. The actual
|
||||
* input format ptr is not stored.
|
||||
*/
|
||||
void ast_format_cap_add_all_by_type(struct ast_format_cap *cap, enum ast_format_type type);
|
||||
|
||||
/*!
|
||||
* \brief Add all known formats to the capabilities structure using default format attribute.
|
||||
*/
|
||||
void ast_format_cap_add_all(struct ast_format_cap *cap);
|
||||
|
||||
/*!
|
||||
* \brief Append the formats in src to dst
|
||||
*/
|
||||
void ast_format_cap_append(struct ast_format_cap *dst, const struct ast_format_cap *src);
|
||||
|
||||
/*!
|
||||
* \brief Copy all items in src to dst.
|
||||
* \note any items in dst will be removed before copying
|
||||
*/
|
||||
void ast_format_cap_copy(struct ast_format_cap *dst, const struct ast_format_cap *src);
|
||||
|
||||
/*!
|
||||
* \brief create a deep copy of an ast_format_cap structure
|
||||
* \retval 0 success
|
||||
* \retval -1 failure
|
||||
*
|
||||
* \retval cap on success
|
||||
* \retval NULL on failure
|
||||
* \note A reference to the format is taken and used in the capabilities structure.
|
||||
*
|
||||
* \note The order in which add is called determines the format preference order.
|
||||
*
|
||||
* \note If framing is specified here it overrides any global framing that has been set.
|
||||
*/
|
||||
struct ast_format_cap *ast_format_cap_dup(const struct ast_format_cap *src);
|
||||
int __ast_format_cap_append(struct ast_format_cap *cap, struct ast_format *format, unsigned int framing);
|
||||
int __ast_format_cap_append_debug(struct ast_format_cap *cap, struct ast_format *format, unsigned int framing, const char *tag, const char *file, int line, const char *func);
|
||||
|
||||
#ifdef REF_DEBUG
|
||||
#define ast_format_cap_append(cap, format, framing) \
|
||||
__ast_format_cap_append_debug((cap), (format), (framing), "", __FILE__, __LINE__, __PRETTY_FUNCTION__)
|
||||
#define ast_t_format_cap_append(cap, format, framing, tag) \
|
||||
__ast_format_cap_append_debug((cap), (format), (framing), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
|
||||
#else
|
||||
#define ast_format_cap_append(cap, format, framing) \
|
||||
__ast_format_cap_append((cap), (format), (framing))
|
||||
#define ast_t_format_cap_append(cap, format, framing, tag) \
|
||||
__ast_format_cap_append((cap), (format), (framing))
|
||||
#endif
|
||||
|
||||
/*!
|
||||
* \brief determine if a capabilities structure is empty or not
|
||||
* \brief Add all codecs Asterisk knows about for a specific type to
|
||||
* the capabilities structure.
|
||||
*
|
||||
* \retval 1, true is empty
|
||||
* \retval 0, false, not empty
|
||||
* \param cap The capabilities structure to add to.
|
||||
* \param type The type of formats to add.
|
||||
*
|
||||
* \retval 0 success
|
||||
* \retval -1 failure
|
||||
*
|
||||
* \note A generic format with no attributes is created using the codec.
|
||||
*
|
||||
* \note If AST_MEDIA_TYPE_UNKNOWN is passed as the type all known codecs will be added.
|
||||
*/
|
||||
int ast_format_cap_is_empty(const struct ast_format_cap *cap);
|
||||
int ast_format_cap_append_by_type(struct ast_format_cap *cap, enum ast_media_type type);
|
||||
|
||||
/*!
|
||||
* \brief Append the formats of provided type in src to dst
|
||||
*
|
||||
* \param dst The destination capabilities structure
|
||||
* \param src The source capabilities structure
|
||||
* \param type The type of formats to append.
|
||||
*
|
||||
* \retval 0 success
|
||||
* \retval -1 failure
|
||||
*
|
||||
* \note If AST_MEDIA_TYPE_UNKNOWN is passed as the type all known codecs will be added.
|
||||
*/
|
||||
int ast_format_cap_append_from_cap(struct ast_format_cap *dst, const struct ast_format_cap *src, enum ast_media_type type);
|
||||
|
||||
/*!
|
||||
* \brief Replace the formats of provided type in dst with equivalent formats from src
|
||||
*
|
||||
* \param dst The destination capabilities structure
|
||||
* \param src The source capabilities structure
|
||||
* \param type The type of formats to replace.
|
||||
*
|
||||
* \note If AST_MEDIA_TYPE_UNKNOWN is passed as the type all known codecs will be replaced.
|
||||
* \note Formats present in src but not dst will not be appended to dst.
|
||||
*/
|
||||
void ast_format_cap_replace_from_cap(struct ast_format_cap *dst, const struct ast_format_cap *src, enum ast_media_type type);
|
||||
|
||||
/*!
|
||||
* \brief Parse an "allow" or "deny" list and modify a format capabilities structure accordingly
|
||||
*
|
||||
* \param cap The capabilities structure to modify
|
||||
* \param list The list containing formats to append or remove
|
||||
* \param allowing If zero, start removing formats specified in the list. If non-zero,
|
||||
* start appending formats specified in the list.
|
||||
*
|
||||
* \retval 0 on success
|
||||
* \retval -1 on failure
|
||||
*/
|
||||
int ast_format_cap_update_by_allow_disallow(struct ast_format_cap *cap, const char *list, int allowing);
|
||||
|
||||
/*!
|
||||
* \brief Get the number of formats present within the capabilities structure
|
||||
*
|
||||
* \param cap The capabilities structure
|
||||
*
|
||||
* \return the number of formats
|
||||
*/
|
||||
size_t ast_format_cap_count(const struct ast_format_cap *cap);
|
||||
|
||||
/*!
|
||||
* \brief Get the format at a specific index
|
||||
*
|
||||
* \param cap The capabilities structure
|
||||
* \param position The position to get
|
||||
*
|
||||
* \retval non-NULL success
|
||||
* \retval NULL failure
|
||||
*
|
||||
* \note This is a zero based index.
|
||||
*
|
||||
* \note Formats are returned in order of preference.
|
||||
*
|
||||
* \note The reference count of the returned format is increased. It must be released using ao2_ref
|
||||
* or ao2_cleanup.
|
||||
*/
|
||||
struct ast_format *ast_format_cap_get_format(const struct ast_format_cap *cap, int position);
|
||||
|
||||
/*!
|
||||
* \brief Get the most preferred format for a particular media type
|
||||
*
|
||||
* \param cap The capabilities structure
|
||||
* \param type The type of media to get
|
||||
*
|
||||
* \retval non-NULL the preferred format
|
||||
* \retval NULL no media of \c type present
|
||||
*
|
||||
* \note The reference count of the returned format is increased. It must be released using ao2_ref
|
||||
* or ao2_cleanup.
|
||||
*/
|
||||
struct ast_format *ast_format_cap_get_best_by_type(const struct ast_format_cap *cap, enum ast_media_type type);
|
||||
|
||||
/*!
|
||||
* \brief Get the framing for a format
|
||||
*
|
||||
* \param cap The capabilities structure
|
||||
* \param format The format to retrieve
|
||||
*
|
||||
* \return the framing (in milliseconds)
|
||||
*/
|
||||
unsigned int ast_format_cap_get_format_framing(const struct ast_format_cap *cap, const struct ast_format *format);
|
||||
|
||||
/*!
|
||||
* \brief Remove format capability from capability structure.
|
||||
*
|
||||
* \note format must match Exactly to format in ast_format_cap object in order
|
||||
* to be removed.
|
||||
* \note format must be an exact pointer match to remove from capabilities structure.
|
||||
*
|
||||
* \retval 0, remove was successful
|
||||
* \retval -1, remove failed. Could not find format to remove
|
||||
*/
|
||||
int ast_format_cap_remove(struct ast_format_cap *cap, struct ast_format *format);
|
||||
|
||||
/*!
|
||||
* \brief Remove all format capabilities from capability
|
||||
* structure for a specific format id.
|
||||
*
|
||||
* \note This will remove _ALL_ formats matching the format id from the
|
||||
* capabilities structure.
|
||||
*
|
||||
* \retval 0, remove was successful
|
||||
* \retval -1, remove failed. Could not find formats to remove
|
||||
*/
|
||||
int ast_format_cap_remove_byid(struct ast_format_cap *cap, enum ast_format_id id);
|
||||
|
||||
/*!
|
||||
* \brief Remove all formats matching a specific format type.
|
||||
*
|
||||
* \param cap The capabilities structure
|
||||
* \param type The media type to remove formats of
|
||||
*
|
||||
* \note All formats can be removed by using the AST_MEDIA_TYPE_UNKNOWN type.
|
||||
*/
|
||||
void ast_format_cap_remove_bytype(struct ast_format_cap *cap, enum ast_format_type type);
|
||||
|
||||
/*!
|
||||
* \brief Remove all format capabilities from capability structure
|
||||
*/
|
||||
void ast_format_cap_remove_all(struct ast_format_cap *cap);
|
||||
|
||||
/*!
|
||||
* \brief Remove all previous formats and set a single new format.
|
||||
*/
|
||||
void ast_format_cap_set(struct ast_format_cap *cap, struct ast_format *format);
|
||||
void ast_format_cap_remove_by_type(struct ast_format_cap *cap, enum ast_media_type type);
|
||||
|
||||
/*!
|
||||
* \brief Find if input ast_format is within the capabilities of the ast_format_cap object
|
||||
* then return the compatible format from the capabilities structure in the result.
|
||||
*
|
||||
* \retval 1 format is compatible with formats held in ast_format_cap object.
|
||||
* \retval 0 format is not compatible with any formats in ast_format_cap object.
|
||||
* \retval non-NULL if format is compatible
|
||||
* \retval NULL if not compatible
|
||||
*
|
||||
* \note The reference count of the returned format is increased. It must be released using ao2_ref
|
||||
* or ao2_cleanup.
|
||||
*/
|
||||
int ast_format_cap_get_compatible_format(const struct ast_format_cap *cap, const struct ast_format *format, struct ast_format *result);
|
||||
struct ast_format *ast_format_cap_get_compatible_format(const struct ast_format_cap *cap, const struct ast_format *format);
|
||||
|
||||
/*!
|
||||
* \brief Find if ast_format is within the capabilities of the ast_format_cap object.
|
||||
*
|
||||
* \retval 1 format is compatible with formats held in ast_format_cap object.
|
||||
* \retval 0 format is not compatible with any formats in ast_format_cap object.
|
||||
* \retval ast_format_cmp_res representing the result of the compatibility check between cap and format.
|
||||
*/
|
||||
int ast_format_cap_iscompatible(const struct ast_format_cap *cap, const struct ast_format *format);
|
||||
enum ast_format_cmp_res ast_format_cap_iscompatible_format(const struct ast_format_cap *cap, const struct ast_format *format);
|
||||
|
||||
/*!
|
||||
* \brief Finds the best quality audio format for a given format id and returns it in result.
|
||||
* \brief Find the compatible formats between two capabilities structures
|
||||
*
|
||||
* \retval 1 format found and set to result structure.
|
||||
* \retval 0 no format found, result structure is cleared.
|
||||
* \param cap1 The first capabilities structure
|
||||
* \param cap2 The second capabilities structure
|
||||
* \param[out] result The capabilities structure to place the results into
|
||||
*
|
||||
* \retval 0 success
|
||||
* \retval -1 failure
|
||||
*
|
||||
* \note The preference order of cap1 is respected.
|
||||
*
|
||||
* \note If failure occurs the result format capabilities structure may contain a partial result.
|
||||
*/
|
||||
int ast_format_cap_best_byid(const struct ast_format_cap *cap, enum ast_format_id, struct ast_format *result);
|
||||
int ast_format_cap_get_compatible(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2,
|
||||
struct ast_format_cap *result);
|
||||
|
||||
/*!
|
||||
* \brief is cap1 identical to cap2
|
||||
* \brief Determine if any joint capabilities exist between two capabilities structures
|
||||
*
|
||||
* retval 1 true, identical
|
||||
* retval 0 false, not identical
|
||||
* \param cap1 The first capabilities structure
|
||||
* \param cap2 The second capabilities structure
|
||||
*
|
||||
* \retval 0 no joint capabilities exist
|
||||
* \retval 1 joint capabilities exist
|
||||
*/
|
||||
int ast_format_cap_iscompatible(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
|
||||
|
||||
/*!
|
||||
* \brief Determine if two capabilities structures are identical
|
||||
*
|
||||
* \param cap1 The first capabilities structure
|
||||
* \param cap2 The second capabilities structure
|
||||
*
|
||||
* \retval 0 capabilities are not identical
|
||||
* \retval 1 capabilities are identical
|
||||
*/
|
||||
int ast_format_cap_identical(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
|
||||
|
||||
/*!
|
||||
* \brief Get joint capability structure.
|
||||
*
|
||||
* \note returns an ast_format_cap object containing the joint capabilities on success. This new
|
||||
* capabilities structure is allocated with _NO_ locking enabled. If a joint structure requires
|
||||
* locking, allocate it and use the ast_format_cap_joint_copy function to fill it with the joint
|
||||
* capabilities.
|
||||
*
|
||||
* \retval !NULL success, joint capabilties structure with _NO_ locking enabled.
|
||||
* \retval NULL failure
|
||||
*/
|
||||
struct ast_format_cap *ast_format_cap_joint(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
|
||||
|
||||
/*!
|
||||
* \brief Get joint capability structure, copy into result capabilities structure
|
||||
*
|
||||
* \retval 1, joint capabilities exist
|
||||
* \retval 0, joint capabilities do not exist
|
||||
*/
|
||||
int ast_format_cap_joint_copy(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2, struct ast_format_cap *result);
|
||||
|
||||
/*!
|
||||
* \brief Get joint capability structure, append into result capabilities structure
|
||||
*
|
||||
* \retval 1, joint capabilities exist
|
||||
* \retval 0, joint capabilities do not exist
|
||||
*/
|
||||
int ast_format_cap_joint_append(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2, struct ast_format_cap *result);
|
||||
|
||||
/*!
|
||||
* \brief Find out if capability structures have any joint capabilities without
|
||||
* returning those capabilities.
|
||||
*
|
||||
* \retval 1 true, has joint capabilities
|
||||
* \retval 0 false, failure
|
||||
*/
|
||||
int ast_format_cap_has_joint(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
|
||||
|
||||
/*!
|
||||
* \brief Get all capabilities for a specific media type
|
||||
*
|
||||
* \retval !NULL success, new capabilities structure with _NO_ locking enabled on the new structure.
|
||||
* \retval NULL failure
|
||||
*/
|
||||
struct ast_format_cap *ast_format_cap_get_type(const struct ast_format_cap *cap, enum ast_format_type ftype);
|
||||
|
||||
/*!
|
||||
* \brief Find out if the capabilities structure has any formats
|
||||
* of a specific type.
|
||||
@@ -236,68 +309,16 @@ struct ast_format_cap *ast_format_cap_get_type(const struct ast_format_cap *cap,
|
||||
* \retval 1 true
|
||||
* \retval 0 false, no formats of specific type.
|
||||
*/
|
||||
int ast_format_cap_has_type(const struct ast_format_cap *cap, enum ast_format_type type);
|
||||
|
||||
/*! \brief Start iterating formats */
|
||||
void ast_format_cap_iter_start(struct ast_format_cap *cap);
|
||||
int ast_format_cap_has_type(const struct ast_format_cap *cap, enum ast_media_type type);
|
||||
|
||||
/*!
|
||||
* \brief Next format in interation
|
||||
* \brief Get the names of codecs of a set of formats
|
||||
*
|
||||
* \details
|
||||
* Here is how to use the ast_format_cap iterator.
|
||||
* \param cap The capabilities structure containing the formats
|
||||
* \param buf A \c ast_str buffer to populate with the names of the formats
|
||||
*
|
||||
* 1. call ast_format_cap_iter_start
|
||||
* 2. call ast_format_cap_iter_next in a loop until it returns -1
|
||||
* 3. call ast_format_cap_iter_end to terminate the iterator.
|
||||
*
|
||||
* example:
|
||||
*
|
||||
* ast_format_cap_iter_start(cap);
|
||||
* while (!ast_format_cap_iter_next(cap, &format)) {
|
||||
* }
|
||||
* ast_format_cap_iter_end(Cap);
|
||||
*
|
||||
* \note Unless the container was alloced using no_lock, the container
|
||||
* will be locked during the entire iteration until ast_format_cap_iter_end
|
||||
* is called. XXX Remember this, and do not attempt to lock any containers
|
||||
* within this iteration that will violate locking order.
|
||||
*
|
||||
* \retval 0 on success, new format is copied into input format struct
|
||||
* \retval -1, no more formats are present.
|
||||
* \return The contents of the buffer in \c buf
|
||||
*/
|
||||
int ast_format_cap_iter_next(struct ast_format_cap *cap, struct ast_format *format);
|
||||
const char *ast_format_cap_get_names(struct ast_format_cap *cap, struct ast_str **buf);
|
||||
|
||||
/*!
|
||||
* \brief Ends ast_format_cap iteration.
|
||||
* \note this must be call after every ast_format_cap_iter_start
|
||||
*/
|
||||
void ast_format_cap_iter_end(struct ast_format_cap *cap);
|
||||
|
||||
/*!
|
||||
* \brief ast_format_cap to old bitfield format represenatation
|
||||
*
|
||||
* \note This is only to be used for IAX2 compatibility
|
||||
*
|
||||
* \retval old bitfield representation of ast_format_cap
|
||||
* \retval 0, if no old bitfield capabilities are present in ast_format_cap
|
||||
*/
|
||||
uint64_t ast_format_cap_to_old_bitfield(const struct ast_format_cap *cap);
|
||||
|
||||
/*!
|
||||
* \brief convert old bitfield format to ast_format_cap represenatation
|
||||
* \note This is only to be used for IAX2 compatibility
|
||||
*/
|
||||
void ast_format_cap_from_old_bitfield(struct ast_format_cap *dst, uint64_t src);
|
||||
|
||||
/*! \brief Get the names of a set of formats
|
||||
* \param buf a buffer for the output string
|
||||
* \param size size of buf (bytes)
|
||||
* \param cap format the format (combined IDs of codecs)
|
||||
* Prints a list of readable codec names corresponding to "format".
|
||||
* ex: for format=AST_FORMAT_GSM|AST_FORMAT_SPEEX|AST_FORMAT_ILBC it will return "0x602 (GSM|SPEEX|ILBC)"
|
||||
* \return The return value is buf.
|
||||
*/
|
||||
char *ast_getformatname_multiple(char *buf, size_t size, struct ast_format_cap *cap);
|
||||
|
||||
#endif /* _AST_FORMATCAP_H */
|
||||
#endif /* _AST_FORMAT_CAP_H */
|
||||
|
||||
Reference in New Issue
Block a user