chan_iax2: Several media format fixes.
[asterisk/asterisk.git] / channels / iax2 / include / codec_pref.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2014, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*!
20  * \file
21  * \brief Media Format Bitfield Compatibility API
22  *
23  * \author Joshua Colp <jcolp@digium.com>
24  */
25
26 #ifndef _IAX2_CODEC_PREF_H_
27 #define _IAX2_CODEC_PREF_H_
28
29 struct ast_format;
30 struct ast_codec;
31 struct ast_format_cap;
32
33 #define IAX2_CODEC_PREF_SIZE 64
34 struct iax2_codec_pref {
35         /*! Array is ordered by preference.  Contains the iax2_supported_formats[] index + 1. */
36         char order[IAX2_CODEC_PREF_SIZE];
37         /*! Framing size of the codec */
38         unsigned int framing[IAX2_CODEC_PREF_SIZE];
39 };
40
41 /*!
42  * \brief Convert an iax2_codec_pref order value into a format bitfield
43  *
44  * \param order_value value being converted
45  *
46  * \return the bitfield value of the order_value format
47  */
48 uint64_t iax2_codec_pref_order_value_to_format_bitfield(int order_value);
49
50 /*!
51  * \brief Convert a format bitfield into an iax2_codec_pref order value
52  *
53  * \param bitfield value being converted
54  *
55  * \return the iax2_codec_pref order value of the most significant format
56  *  in the bitfield.
57  *
58  * \note This is really meant to be used on single format bitfields.
59  *  It will work with multiformat bitfields, but it can only return the
60  *  index of the most significant one if that is the case.
61  */
62 int iax2_codec_pref_format_bitfield_to_order_value(uint64_t bitfield);
63
64 /*!
65  * \brief Codec located at a particular place in the preference index.
66  * \param pref preference structure to get the codec out of
67  * \param index to retrieve from
68  * \param result ast_format structure to store the index value in
69  * \return pointer to input ast_format on success, NULL on failure
70 */
71 struct ast_format *iax2_codec_pref_index(struct iax2_codec_pref *pref, int index, struct ast_format **result);
72
73 /*!
74  * \brief Convert a preference structure to a capabilities structure.
75  *
76  * \param pref Formats in preference order to build the capabilities.
77  * \param cap Capabilities structure to place formats into
78  *
79  * \retval 0 on success.
80  * \retval -1 on error.
81  *
82  * \note If failure occurs the capabilities structure may contain a partial set of formats
83  */
84 int iax2_codec_pref_to_cap(struct iax2_codec_pref *pref, struct ast_format_cap *cap);
85
86 /*!
87  * \brief Convert a bitfield to a format capabilities structure in the "best" order.
88  *
89  * \param bitfield The bitfield for the media formats
90  * \param prefs Format preference order to use as a guide. (May be NULL)
91  * \param cap Capabilities structure to place formats into
92  *
93  * \retval 0 on success.
94  * \retval -1 on error.
95  *
96  * \note If failure occurs the capabilities structure may contain a partial set of formats
97  */
98 int iax2_codec_pref_best_bitfield2cap(uint64_t bitfield, struct iax2_codec_pref *prefs, struct ast_format_cap *cap);
99
100 /*! \brief Removes format from the pref list that aren't in the bitfield */
101 void iax2_codec_pref_remove_missing(struct iax2_codec_pref *pref, uint64_t bitfield);
102
103 /*!
104  * \brief Dump audio codec preference list into a string
105  *
106  * \param pref preference structure to dump string representation of order for
107  * \param buf character buffer to put string into
108  * \param size size of the character buffer
109  *
110  * \return -1 on error. Otherwise returns the remaining spaaaaaace in the buffer.
111  *
112  * \note Format is (codec1|codec2|codec3|...) -- if the list is too long for the
113  *  size of the buffer, codecs will be written until they exceed the length
114  *  remaining in which case the list will be closed with '...)' after the last
115  *  writable codec.
116  */
117 int iax2_codec_pref_string(struct iax2_codec_pref *pref, char *buf, size_t size);
118
119 /*! \brief Append a audio codec to a preference list, removing it first if it was already there
120 */
121 void iax2_codec_pref_append(struct iax2_codec_pref *pref, struct ast_format *format, unsigned int framing);
122
123 /*! \brief Prepend an audio codec to a preference list, removing it first if it was already there
124 */
125 void iax2_codec_pref_prepend(struct iax2_codec_pref *pref, struct ast_format *format, unsigned int framing,
126         int only_if_existing);
127
128 /*! \brief Shift an audio codec preference list up or down 65 bytes so that it becomes an ASCII string
129  * \note Due to a misunderstanding in how codec preferences are stored, this
130  * list starts at 'B', not 'A'.  For backwards compatibility reasons, this
131  * cannot change.
132  * \param pref A codec preference list structure
133  * \param buf A string denoting codec preference, appropriate for use in line transmission
134  * \param size Size of \a buf
135  * \param right Boolean:  if 0, convert from \a buf to \a pref; if 1, convert from \a pref to \a buf.
136  */
137 void iax2_codec_pref_convert(struct iax2_codec_pref *pref, char *buf, size_t size, int right);
138
139 /*!
140  * \brief Create codec preference list from the given bitfield formats.
141  * \since 13.0.0
142  *
143  * \param pref Codec preference list to setup from the given bitfield.
144  * \param bitfield Format bitfield to guide preference list creation.
145  *
146  * \return Updated bitfield with any bits not mapped to a format cleared.
147  */
148 uint64_t iax2_codec_pref_from_bitfield(struct iax2_codec_pref *pref, uint64_t bitfield);
149
150 #endif /* _IAX2_CODEC_PREF_H_ */