Clean up doxygen warnings
[asterisk/asterisk.git] / include / asterisk / format_pref.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2010, Digium, Inc.
5  *
6  * Mark Spencer <markster@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 Format Preference API
22  */
23
24 #ifndef _AST_FORMATPREF_H_
25 #define _AST_FORMATPREF_H_
26
27 #include "asterisk/format.h"
28 #include "asterisk/format_cap.h"
29
30 #define AST_CODEC_PREF_SIZE 64
31 struct ast_codec_pref {
32         /*! This array represents the each format in the pref list */
33         struct ast_format formats[AST_CODEC_PREF_SIZE];
34         /*! This array represents the format id's index in the global format list. */
35         char order[AST_CODEC_PREF_SIZE];
36         /*! This array represents the format's framing size if present. */
37         int framing[AST_CODEC_PREF_SIZE];
38 };
39
40 /*! \page AudioCodecPref Audio Codec Preferences
41
42         In order to negotiate audio codecs in the order they are configured
43         in \<channel\>.conf for a device, we set up codec preference lists
44         in addition to the codec capabilities setting. The capabilities
45         setting is a bitmask of audio and video codecs with no internal
46         order. This will reflect the offer given to the other side, where
47         the prefered codecs will be added to the top of the list in the
48         order indicated by the "allow" lines in the device configuration.
49
50         Video codecs are not included in the preference lists since they
51         can't be transcoded and we just have to pick whatever is supported
52 */
53
54 /*!
55  *\brief Initialize an audio codec preference to "no preference".
56  * \arg \ref AudioCodecPref
57 */
58 void ast_codec_pref_init(struct ast_codec_pref *pref);
59
60 /*!
61  * \brief Codec located at a particular place in the preference index.
62  * \param pref preference structure to get the codec out of
63  * \param index to retrieve from
64  * \param result ast_format structure to store the index value in
65  * \return pointer to input ast_format on success, NULL on failure
66 */
67 struct ast_format *ast_codec_pref_index(struct ast_codec_pref *pref, int index, struct ast_format *result);
68
69 /*! \brief Remove audio a codec from a preference list */
70 void ast_codec_pref_remove(struct ast_codec_pref *pref, struct ast_format *format);
71
72 /*! \brief Append a audio codec to a preference list, removing it first if it was already there
73 */
74 int ast_codec_pref_append(struct ast_codec_pref *pref, struct ast_format *format);
75
76 /*! \brief Prepend an audio codec to a preference list, removing it first if it was already there
77 */
78 void ast_codec_pref_prepend(struct ast_codec_pref *pref, struct ast_format *format, int only_if_existing);
79
80 /*! \brief Select the best audio format according to preference list from supplied options.
81  * Best audio format is returned in the result format.
82  *
83  * \note If "find_best" is non-zero then if nothing is found, the "Best" format of
84  * the format list is selected and returned in the result structure, otherwise
85  * NULL is returned
86  *
87  * \retval ptr to result struture.
88  * \retval NULL, best codec was not found
89  */
90 struct ast_format *ast_codec_choose(struct ast_codec_pref *pref, struct ast_format_cap *cap, int find_best, struct ast_format *result);
91
92 /*! \brief Set packet size for codec
93 */
94 int ast_codec_pref_setsize(struct ast_codec_pref *pref, struct ast_format *format, int framems);
95
96 /*! \brief Get packet size for codec
97 */
98 struct ast_format_list ast_codec_pref_getsize(struct ast_codec_pref *pref, struct ast_format *format);
99
100 /*! \brief Dump audio codec preference list into a string */
101 int ast_codec_pref_string(struct ast_codec_pref *pref, char *buf, size_t size);
102
103 /*! \brief Shift an audio codec preference list up or down 65 bytes so that it becomes an ASCII string
104  * \note Due to a misunderstanding in how codec preferences are stored, this
105  * list starts at 'B', not 'A'.  For backwards compatibility reasons, this
106  * cannot change.
107  * \param pref A codec preference list structure
108  * \param buf A string denoting codec preference, appropriate for use in line transmission
109  * \param size Size of \a buf
110  * \param right Boolean:  if 0, convert from \a buf to \a pref; if 1, convert from \a pref to \a buf.
111  */
112 void ast_codec_pref_convert(struct ast_codec_pref *pref, char *buf, size_t size, int right);
113
114 #endif /* _AST_FORMATPREF_H */