ari: Add a copy operation for stored recordings
[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 all codecs to a preference list, without disturbing existing order */
73 void ast_codec_pref_append_all(struct ast_codec_pref *pref);
74
75 /*! \brief Append a audio codec to a preference list, removing it first if it was already there
76 */
77 int ast_codec_pref_append(struct ast_codec_pref *pref, struct ast_format *format);
78
79 /*! \brief Prepend an audio codec to a preference list, removing it first if it was already there
80 */
81 void ast_codec_pref_prepend(struct ast_codec_pref *pref, struct ast_format *format, int only_if_existing);
82
83 /*! \brief Select the best audio format according to preference list from supplied options.
84  * Best audio format is returned in the result format.
85  *
86  * \note If "find_best" is non-zero then if nothing is found, the "Best" format of
87  * the format list is selected and returned in the result structure, otherwise
88  * NULL is returned
89  *
90  * \retval ptr to result struture.
91  * \retval NULL, best codec was not found
92  */
93 struct ast_format *ast_codec_choose(struct ast_codec_pref *pref, struct ast_format_cap *cap, int find_best, struct ast_format *result);
94
95 /*! \brief Set packet size for codec
96 */
97 int ast_codec_pref_setsize(struct ast_codec_pref *pref, struct ast_format *format, int framems);
98
99 /*! \brief Get packet size for codec
100 */
101 struct ast_format_list ast_codec_pref_getsize(struct ast_codec_pref *pref, struct ast_format *format);
102
103 /*! \brief Dump audio codec preference list into a string */
104 int ast_codec_pref_string(struct ast_codec_pref *pref, char *buf, size_t size);
105
106 /*! \brief Shift an audio codec preference list up or down 65 bytes so that it becomes an ASCII string
107  * \note Due to a misunderstanding in how codec preferences are stored, this
108  * list starts at 'B', not 'A'.  For backwards compatibility reasons, this
109  * cannot change.
110  * \param pref A codec preference list structure
111  * \param buf A string denoting codec preference, appropriate for use in line transmission
112  * \param size Size of \a buf
113  * \param right Boolean:  if 0, convert from \a buf to \a pref; if 1, convert from \a pref to \a buf.
114  */
115 void ast_codec_pref_convert(struct ast_codec_pref *pref, char *buf, size_t size, int right);
116
117 #endif /* _AST_FORMATPREF_H */