codec_pref.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2014, Digium, Inc.
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*!
00020  * \file
00021  * \brief Media Format Bitfield Compatibility API
00022  *
00023  * \author Joshua Colp <jcolp@digium.com>
00024  */
00025 
00026 #ifndef _IAX2_CODEC_PREF_H_
00027 #define _IAX2_CODEC_PREF_H_
00028 
00029 struct ast_format;
00030 struct ast_codec;
00031 struct ast_format_cap;
00032 
00033 #define IAX2_CODEC_PREF_SIZE 64
00034 struct iax2_codec_pref {
00035    /*! Array is ordered by preference.  Contains the iax2_supported_formats[] index + 1. */
00036    char order[IAX2_CODEC_PREF_SIZE];
00037    /*! Framing size of the codec */
00038    unsigned int framing[IAX2_CODEC_PREF_SIZE];
00039 };
00040 
00041 /*!
00042  * \brief Convert an iax2_codec_pref order value into a format bitfield
00043  *
00044  * \param order_value value being converted
00045  *
00046  * \return the bitfield value of the order_value format
00047  */
00048 uint64_t iax2_codec_pref_order_value_to_format_bitfield(int order_value);
00049 
00050 /*!
00051  * \brief Convert a format bitfield into an iax2_codec_pref order value
00052  *
00053  * \param bitfield value being converted
00054  *
00055  * \return the iax2_codec_pref order value of the most significant format
00056  *  in the bitfield.
00057  *
00058  * \note This is really meant to be used on single format bitfields.
00059  *  It will work with multiformat bitfields, but it can only return the
00060  *  index of the most significant one if that is the case.
00061  */
00062 int iax2_codec_pref_format_bitfield_to_order_value(uint64_t bitfield);
00063 
00064 /*!
00065  * \brief Codec located at a particular place in the preference index.
00066  * \param pref preference structure to get the codec out of
00067  * \param index to retrieve from
00068  * \param result ast_format structure to store the index value in
00069  * \return pointer to input ast_format on success, NULL on failure
00070 */
00071 struct ast_format *iax2_codec_pref_index(struct iax2_codec_pref *pref, int index, struct ast_format **result);
00072 
00073 /*!
00074  * \brief Convert a preference structure to a capabilities structure.
00075  *
00076  * \param pref Formats in preference order to build the capabilities.
00077  * \param cap Capabilities structure to place formats into
00078  *
00079  * \retval 0 on success.
00080  * \retval -1 on error.
00081  *
00082  * \note If failure occurs the capabilities structure may contain a partial set of formats
00083  */
00084 int iax2_codec_pref_to_cap(struct iax2_codec_pref *pref, struct ast_format_cap *cap);
00085 
00086 /*!
00087  * \brief Convert a bitfield to a format capabilities structure in the "best" order.
00088  *
00089  * \param bitfield The bitfield for the media formats
00090  * \param prefs Format preference order to use as a guide. (May be NULL)
00091  * \param cap Capabilities structure to place formats into
00092  *
00093  * \retval 0 on success.
00094  * \retval -1 on error.
00095  *
00096  * \note If failure occurs the capabilities structure may contain a partial set of formats
00097  */
00098 int iax2_codec_pref_best_bitfield2cap(uint64_t bitfield, struct iax2_codec_pref *prefs, struct ast_format_cap *cap);
00099 
00100 /*! \brief Removes format from the pref list that aren't in the bitfield */
00101 void iax2_codec_pref_remove_missing(struct iax2_codec_pref *pref, uint64_t bitfield);
00102 
00103 /*!
00104  * \brief Dump audio codec preference list into a string
00105  *
00106  * \param pref preference structure to dump string representation of order for
00107  * \param buf character buffer to put string into
00108  * \param size size of the character buffer
00109  *
00110  * \return -1 on error. Otherwise returns the remaining spaaaaaace in the buffer.
00111  *
00112  * \note Format is (codec1|codec2|codec3|...) -- if the list is too long for the
00113  *  size of the buffer, codecs will be written until they exceed the length
00114  *  remaining in which case the list will be closed with '...)' after the last
00115  *  writable codec.
00116  */
00117 int iax2_codec_pref_string(struct iax2_codec_pref *pref, char *buf, size_t size);
00118 
00119 /*! \brief Append a audio codec to a preference list, removing it first if it was already there
00120 */
00121 void iax2_codec_pref_append(struct iax2_codec_pref *pref, struct ast_format *format, unsigned int framing);
00122 
00123 /*! \brief Prepend an audio codec to a preference list, removing it first if it was already there
00124 */
00125 void iax2_codec_pref_prepend(struct iax2_codec_pref *pref, struct ast_format *format, unsigned int framing,
00126    int only_if_existing);
00127 
00128 /*! \brief Shift an audio codec preference list up or down 65 bytes so that it becomes an ASCII string
00129  * \note Due to a misunderstanding in how codec preferences are stored, this
00130  * list starts at 'B', not 'A'.  For backwards compatibility reasons, this
00131  * cannot change.
00132  * \param pref A codec preference list structure
00133  * \param buf A string denoting codec preference, appropriate for use in line transmission
00134  * \param size Size of \a buf
00135  * \param right Boolean:  if 0, convert from \a buf to \a pref; if 1, convert from \a pref to \a buf.
00136  */
00137 void iax2_codec_pref_convert(struct iax2_codec_pref *pref, char *buf, size_t size, int right);
00138 
00139 /*!
00140  * \brief Create codec preference list from the given bitfield formats.
00141  * \since 13.0.0
00142  *
00143  * \param pref Codec preference list to setup from the given bitfield.
00144  * \param bitfield Format bitfield to guide preference list creation.
00145  *
00146  * \return Updated bitfield with any bits not mapped to a format cleared.
00147  */
00148 uint64_t iax2_codec_pref_from_bitfield(struct iax2_codec_pref *pref, uint64_t bitfield);
00149 
00150 #endif /* _IAX2_CODEC_PREF_H_ */

Generated on Thu Apr 16 06:27:30 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6