09212abc8167b0e56169397abcee8a9426d4ff67
[asterisk/asterisk.git] / include / asterisk / format.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2010, Digium, Inc.
5  *
6  * David Vossel <dvossel@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 API
22  *
23  * \author David Vossel <dvossel@digium.com>
24  */
25
26 #ifndef _AST_FORMAT_H_
27 #define _AST_FORMAT_H_
28
29 #define AST_FORMAT_ATTR_SIZE 128
30
31 #define AST_FORMAT_INC 100000
32
33 /*! This is the value that ends a var list of format attribute
34  * key value pairs. */
35 #define AST_FORMAT_ATTR_END -1
36
37 /* \brief Format Categories*/
38 enum ast_format_type {
39         AST_FORMAT_TYPE_AUDIO = 1 * AST_FORMAT_INC,
40         AST_FORMAT_TYPE_VIDEO = 2 * AST_FORMAT_INC,
41         AST_FORMAT_TYPE_IMAGE = 3 * AST_FORMAT_INC,
42         AST_FORMAT_TYPE_TEXT  = 4 * AST_FORMAT_INC,
43 };
44
45 enum ast_format_id {
46         /*! G.723.1 compression */
47         AST_FORMAT_G723_1           = 1 + AST_FORMAT_TYPE_AUDIO,
48         /*! GSM compression */
49         AST_FORMAT_GSM              = 2 + AST_FORMAT_TYPE_AUDIO,
50         /*! Raw mu-law data (G.711) */
51         AST_FORMAT_ULAW             = 3 + AST_FORMAT_TYPE_AUDIO,
52         /*! Raw A-law data (G.711) */
53         AST_FORMAT_ALAW             = 4 + AST_FORMAT_TYPE_AUDIO,
54         /*! ADPCM (G.726, 32kbps, AAL2 codeword packing) */
55         AST_FORMAT_G726_AAL2        = 5 + AST_FORMAT_TYPE_AUDIO,
56         /*! ADPCM (IMA) */
57         AST_FORMAT_ADPCM            = 6 + AST_FORMAT_TYPE_AUDIO,
58         /*! Raw 16-bit Signed Linear (8000 Hz) PCM */
59         AST_FORMAT_SLINEAR          = 7 + AST_FORMAT_TYPE_AUDIO,
60         /*! LPC10, 180 samples/frame */
61         AST_FORMAT_LPC10            = 8 + AST_FORMAT_TYPE_AUDIO,
62         /*! G.729A audio */
63         AST_FORMAT_G729A            = 9 + AST_FORMAT_TYPE_AUDIO,
64         /*! SpeeX Free Compression */
65         AST_FORMAT_SPEEX            = 10 + AST_FORMAT_TYPE_AUDIO,
66         /*! iLBC Free Compression */
67         AST_FORMAT_ILBC             = 11 + AST_FORMAT_TYPE_AUDIO,
68         /*! ADPCM (G.726, 32kbps, RFC3551 codeword packing) */
69         AST_FORMAT_G726             = 12 + AST_FORMAT_TYPE_AUDIO,
70         /*! G.722 */
71         AST_FORMAT_G722             = 13 + AST_FORMAT_TYPE_AUDIO,
72         /*! G.722.1 (also known as Siren7, 32kbps assumed) */
73         AST_FORMAT_SIREN7           = 14 + AST_FORMAT_TYPE_AUDIO,
74         /*! G.722.1 Annex C (also known as Siren14, 48kbps assumed) */
75         AST_FORMAT_SIREN14          = 15 + AST_FORMAT_TYPE_AUDIO,
76         /*! Raw 16-bit Signed Linear (16000 Hz) PCM */
77         AST_FORMAT_SLINEAR16        = 16 + AST_FORMAT_TYPE_AUDIO,
78         /*! G.719 (64 kbps assumed) */
79         AST_FORMAT_G719             = 17 + AST_FORMAT_TYPE_AUDIO,
80         /*! SpeeX Wideband (16kHz) Free Compression */
81         AST_FORMAT_SPEEX16          = 18 + AST_FORMAT_TYPE_AUDIO,
82         /*! Raw mu-law data (G.711) */
83         AST_FORMAT_TESTLAW          = 19 + AST_FORMAT_TYPE_AUDIO,
84
85         /*! H.261 Video */
86         AST_FORMAT_H261             = 1 + AST_FORMAT_TYPE_VIDEO,
87         /*! H.263 Video */
88         AST_FORMAT_H263             = 2 + AST_FORMAT_TYPE_VIDEO,
89         /*! H.263+ Video */
90         AST_FORMAT_H263_PLUS        = 3 + AST_FORMAT_TYPE_VIDEO,
91         /*! H.264 Video */
92         AST_FORMAT_H264             = 4 + AST_FORMAT_TYPE_VIDEO,
93         /*! MPEG4 Video */
94         AST_FORMAT_MP4_VIDEO        = 5 + AST_FORMAT_TYPE_VIDEO,
95
96         /*! JPEG Images */
97         AST_FORMAT_JPEG             = 1 + AST_FORMAT_TYPE_IMAGE,
98         /*! PNG Images */
99         AST_FORMAT_PNG              = 2 + AST_FORMAT_TYPE_IMAGE,
100
101         /*! T.140 RED Text format RFC 4103 */
102         AST_FORMAT_T140RED          = 1 + AST_FORMAT_TYPE_TEXT,
103         /*! T.140 Text format - ITU T.140, RFC 4103 */
104         AST_FORMAT_T140             = 2 + AST_FORMAT_TYPE_TEXT,
105 };
106
107 /*! Determine what type of media a ast_format_id is. */
108 #define AST_FORMAT_GET_TYPE(id) (((int) (id / AST_FORMAT_INC)) * AST_FORMAT_INC)
109
110 /*! \brief This structure contains the buffer used for format attributes */
111 struct ast_format_attr {
112         /*! The buffer formats can use to represent attributes */
113         uint8_t format_attr[AST_FORMAT_ATTR_SIZE];
114         /*! If a format's payload needs to pass through that a new marker is required
115          * for RTP, this variable will be set. */
116         uint8_t rtp_marker_bit;
117 };
118
119 /*! \brief Represents a media format within Asterisk. */
120 struct ast_format {
121         /*! The unique id representing this format from all the other formats. */
122         enum ast_format_id id;
123         /*!  Attribute structure used to associate attributes with a format. */
124         struct ast_format_attr fattr;
125 };
126
127 enum ast_format_cmp_res {
128         /*! structure 1 is identical to structure 2. */
129         AST_FORMAT_CMP_EQUAL = 0,
130         /*! structure 1 contains elements not in structure 2. */
131         AST_FORMAT_CMP_NOT_EQUAL,
132         /*! structure 1 is a proper subset of the elements in structure 2.*/
133         AST_FORMAT_CMP_SUBSET,
134 };
135
136 /*! \brief A format must register an attribute interface if it requires the use of the format attributes void pointer */
137 struct ast_format_attr_interface {
138         /*! format type */
139         enum ast_format_id id;
140
141         /*! \brief Determine if format_attr 1 is a subset of format_attr 2.
142          *
143          * \retval ast_format_cmp_res representing the result of comparing fattr1 and fattr2.
144          */
145         enum ast_format_cmp_res (* const format_attr_cmp)(const struct ast_format_attr *fattr1, const struct ast_format_attr *fattr2);
146
147         /*! \brief Get joint attributes of same format type if they exist.
148          *
149          * \retval 0 if joint attributes exist
150          * \retval -1 if no joint attributes are present
151          */
152         int (* const format_attr_get_joint)(const struct ast_format_attr *fattr1, const struct ast_format_attr *fattr2, struct ast_format_attr *result);
153
154         /*! \brief Set format capabilities from a list of key value pairs ending with AST_FORMAT_ATTR_END.
155          * \note This function does not need to call va_end of the va_list. */
156         void (* const format_attr_set)(struct ast_format_attr *format_attr, va_list ap);
157 };
158
159 /*!
160  * \brief This function is used to set an ast_format object to represent a media format
161  * with optional format attributes represented by format specific key value pairs.
162  *
163  * \param format to set
164  * \param id, format id to set on format
165  * \param set_attributes, are there attributes to set on this format. 0 == false, 1 == True.
166  * \param var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END;
167  *
168  * \details Example usage.
169  * ast_format_set(format, AST_FORMAT_ULAW, 0); // no capability attributes are needed for ULAW
170  *
171  * ast_format_set(format, AST_FORMAT_SILK, 1, // SILK has capability attributes.
172  *        AST_FORMAT_SILK_ATTR_RATE, 24000,
173  *        AST_FORMAT_SILK_ATTR_RATE, 16000,
174  *        AST_FORMAT_SILK_ATTR_RATE, 12000,
175  *        AST_FORMAT_SILK_ATTR_RATE, 8000,
176  *        AST_FORMAT_ATTR_END);
177  *
178  * \note This function will initialize the ast_format structure.
179  *
180  * \return Pointer to ast_format object, same pointer that is passed in
181  * by the first argument.
182  */
183 struct ast_format *ast_format_set(struct ast_format *format, enum ast_format_id id, int set_attributes, ... );
184
185 /*!
186  * \brief After ast_format_set has been used on a function, this function can be used to
187  * set additional format attributes to the structure.
188  *
189  * \param format to set
190  * \param var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END;
191  *
192  * \details Example usage.
193  * ast_format_set(format, AST_FORMAT_SILK, 0);
194  * ast_format_append(format, // SILK has capability attributes.
195  *        AST_FORMAT_SILK_ATTR_RATE, 24000,
196  *        AST_FORMAT_SILK_ATTR_RATE, 16000,
197  *        AST_FORMAT_SILK_ATTR_RATE, 12000,
198  *        AST_FORMAT_SILK_ATTR_RATE, 8000,
199  *        AST_FORMAT_ATTR_END);
200  *
201  * \return Pointer to ast_format object, same pointer that is passed in
202  * by the first argument.
203  */
204 struct ast_format *ast_format_append(struct ast_format *format, ... );
205
206 /*!
207  * \brief Clears the format stucture.
208  */
209 void ast_format_clear(struct ast_format *format);
210
211 /*!
212  * \brief This function is used to set an ast_format object to represent a media format
213  * with optional capability attributes represented by format specific key value pairs.
214  *
215  * \details Example usage. Is this SILK format capable of 8khz
216  * is_8khz = ast_format_isset(format, AST_FORMAT_SILK_CAP_RATE, 8000);
217  *
218  * \return 0, The format key value pairs are within the capabilities defined in this structure.
219  * \return -1, The format key value pairs are _NOT_ within the capabilities of this structure.
220  */
221 int ast_format_isset(struct ast_format *format, ... );
222
223 /*!
224  * \brief Compare ast_formats structures
225  *
226  * \retval ast_format_cmp_res representing the result of comparing format1 and format2.
227  */
228 enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2);
229
230 /*!
231  * \brief Find joint format attributes of two ast_format
232  * structures containing the same uid and return the intersection in the
233  * result structure.
234  *
235  * retval 0, joint attribute capabilities exist.
236  * retval -1, no joint attribute capabilities exist.
237  */
238 int ast_format_joint(const struct ast_format *format1, const struct ast_format *format2, struct ast_format *result);
239
240 /*!
241  * \brief copy format src into format dst.
242  */
243 void ast_format_copy(struct ast_format *dst, const struct ast_format *src);
244
245 /*!
246  * \brief Set the rtp mark value on the format to indicate to the interface
247  * writing this format's payload that a new RTP marker is necessary.
248  */
249 void ast_format_set_video_mark(struct ast_format *format);
250
251 /*!
252  * \brief Determine of the marker bit is set or not on this format.
253  *
254  * \retval 1, true
255  * \retval 0, false
256  */
257 int ast_format_get_video_mark(const struct ast_format *format);
258
259 /*!
260  * \brief ast_format to old bitfield format represenatation
261  *
262  * \note This is only to be used for IAX2 compatibility 
263  *
264  * \retval iax2 representation of ast_format
265  * \retval 0, if no representation existis for iax2
266  */
267 uint64_t ast_format_to_old_bitfield(const struct ast_format *format);
268
269 /*!
270  * \brief ast_format_id to old bitfield format represenatation
271  *
272  */
273 uint64_t ast_format_id_to_old_bitfield(enum ast_format_id id);
274
275 /*!
276  * \brief convert old bitfield format to ast_format represenatation
277  * \note This is only to be used for IAX2 compatibility 
278  *
279  * \retval on success, pointer to the dst format in the input parameters
280  * \retval on failure, NULL
281  */
282 struct ast_format *ast_format_from_old_bitfield(struct ast_format *dst, uint64_t src);
283
284 /*!
285  * \brief convert old bitfield format to ast_format_id value
286  */
287 enum ast_format_id ast_format_id_from_old_bitfield(uint64_t src);
288
289 /*!
290  * \brief register ast_format_attr_interface with core.
291  *
292  * \retval 0 success
293  * \retval -1 failure
294  */
295 int ast_format_attr_reg_interface(const struct ast_format_attr_interface *interface);
296
297 /*!
298  * \brief unregister format_attr interface with core.
299  *
300  * \retval 0 success
301  * \retval -1 failure
302  */
303 int ast_format_attr_unreg_interface(const struct ast_format_attr_interface *interface);
304
305 /*!
306  * \brief Init the ast_format attribute interface register container.
307  */
308 int ast_format_attr_init(void);
309
310 #endif /* _AST_FORMAT_H */