c99c8f3e86c5b63cd5badde0fce95317813e2894
[asterisk/asterisk.git] / include / asterisk / format.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 API
22  *
23  * \author Joshua Colp <jcolp@digium.com>
24  */
25
26 #include "asterisk/codec.h"
27
28 #ifndef _AST_FORMAT_H_
29 #define _AST_FORMAT_H_
30
31 struct ast_format;
32
33 /*! \brief Format comparison results */
34 enum ast_format_cmp_res {
35         /*! Both formats are equivalent to eachother */
36         AST_FORMAT_CMP_EQUAL = 0,
37         /*! Both formats are completely different and not the same in any way */
38         AST_FORMAT_CMP_NOT_EQUAL,
39         /*! Both formats are similar but not equivalent */
40         AST_FORMAT_CMP_SUBSET,
41 };
42
43 /*! \brief Optional format interface to extend format operations */
44 struct ast_format_interface {
45         /*!
46          * \brief Callback for when the format is destroyed, used to release attribute resources
47          *
48          * \param format The format structure to destroy
49          */
50         void (*const format_destroy)(struct ast_format *format);
51
52         /*!
53          * \brief Callback for when the format is cloned, used to clone attributes
54          *
55          * \param src Source format of attributes
56          * \param dst Destination format for attributes
57          *
58          * \retval 0 success
59          * \retval -1 failure
60          */
61         int (*const format_clone)(const struct ast_format *src, struct ast_format *dst);
62
63         /*!
64          * \brief Determine if format 1 is a subset of format 2.
65          *
66          * \param format1 First format to compare
67          * \param format2 Second format which the first is compared against
68          *
69          * \retval ast_format_cmp_res representing the result of comparing format1 and format2.
70          */
71         enum ast_format_cmp_res (* const format_cmp)(const struct ast_format *format1,
72                 const struct ast_format *format2);
73
74         /*! 
75          * \brief Get a format with the joint compatible attributes of both provided formats.
76          *
77          * \param format1 The first format
78          * \param format2 The second format
79          *
80          * \retval non-NULL if joint format
81          * \retval NULL if no joint format
82          *
83          * \note The returned format has its reference count incremented and must be released using
84          * ao2_ref or ao2_cleanup.
85          */
86         struct ast_format *(* const format_get_joint)(const struct ast_format *format1,
87                 const struct ast_format *format2);
88
89         /*!
90          * \brief Set an attribute on a format
91          *
92          * \param name The name of the attribute
93          * \param value The value of the attribute
94          *
95          * \retval non-NULL success
96          * \retval NULL failure
97          */
98         struct ast_format *(* const format_attribute_set)(const struct ast_format *format,
99                 const char *name, const char *value);
100
101         /*!
102          * \brief Parse SDP attribute information, interpret it, and store it in the format structure.
103          *
104          * \param format Format to set attributes on
105          * \param attributes A string containing only the attributes from the fmtp line
106          *
107          * \retval non-NULL Success, values were valid
108          * \retval NULL Failure, some values were not acceptable
109          */
110         struct ast_format *(* const format_parse_sdp_fmtp)(const struct ast_format *format, const char *attributes);
111
112         /*!
113          * \brief Generate SDP attribute information from an ast_format_attr structure.
114          *
115          * \param format The format containing attributes
116          * \param payload The payload number to place into the fmtp line
117          * \param str The generated fmtp line
118          *
119          * \note This callback should generate a full fmtp line using the provided payload number.
120          */
121         void (* const format_generate_sdp_fmtp)(const struct ast_format *format, unsigned int payload,
122                 struct ast_str **str);
123 };
124
125 /*!
126  * \brief Initialize media format support
127  *
128  * \retval 0 success
129  * \retval -1 failure
130  */
131 int ast_format_init(void);
132
133 /*!
134  * \brief Create a new media format
135  *
136  * \param codec The codec to use
137  *
138  * \retval non-NULL success
139  * \retval NULL failure
140  *
141  * \note The format is returned with reference count incremented. It must be released using
142  * ao2_ref or ao2_cleanup.
143  */
144 struct ast_format *ast_format_create(struct ast_codec *codec);
145
146 /*!
147  * \brief Create a new media format with a specific name
148  *
149  * \param format_name The name to use for the format
150  * \param codec The codec to use
151  *
152  * \note This creation function should be used when the name of the \c codec
153  * cannot be explicitly used for the name of the format. This is the case for
154  * codecs with multiple sample rates
155  *
156  * \note The format is returned with reference count incremented. It must be released using
157  * ao2_ref or ao2_cleanup.
158  *
159  * \retval non-NULL success
160  * \retval NULL failure
161  */
162 struct ast_format *ast_format_create_named(const char *format_name, struct ast_codec *codec);
163
164 /*!
165  * \brief Clone an existing media format so it can be modified
166  *
167  * \param format The existing media format
168  *
169  * \note The returned format is a new ao2 object. It must be released using ao2_cleanup.
170  *
171  * \retval non-NULL success
172  * \retval NULL failure
173  */
174 struct ast_format *ast_format_clone(const struct ast_format *format);
175
176 /*!
177  * \brief Compare two formats
178  *
179  * \retval ast_format_cmp_res representing the result of comparing format1 and format2.
180  */
181 enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2);
182
183 /*!
184  * \brief Get a common joint capability between two formats
185  *
186  * \retval non-NULL if joint capability exists
187  * \retval NULL if no joint capability exists
188  *
189  * \note The returned format must be treated as immutable.
190  */
191 struct ast_format *ast_format_joint(const struct ast_format *format1, const struct ast_format *format2);
192
193 /*!
194  * \brief Set an attribute on a format to a specific value
195  *
196  * \param format The format to set the attribute on
197  * \param name Attribute name
198  * \param value Attribute value
199  *
200  * \retval non-NULL success
201  * \retval NULL failure
202  */
203 struct ast_format *ast_format_attribute_set(const struct ast_format *format, const char *name,
204         const char *value);
205
206 /*!
207  * \brief This function is used to have a media format aware module parse and interpret
208  * SDP attribute information. Once interpreted this information is stored on the format
209  * itself using Asterisk format attributes.
210  *
211  * \param format to set
212  * \param attributes string containing the fmtp line from the SDP
213  *
214  * \retval non-NULL success, attribute values were valid
215  * \retval NULL failure, values were not acceptable
216  */
217 struct ast_format *ast_format_parse_sdp_fmtp(const struct ast_format *format, const char *attributes);
218
219 /*!
220  * \brief This function is used to produce an fmtp SDP line for an Asterisk format. The
221  * attributes present on the Asterisk format are translated into the SDP equivalent.
222  *
223  * \param format to generate an fmtp line for
224  * \param payload numerical payload for the fmtp line
225  * \param str structure that the fmtp line will be appended to
226  */
227 void ast_format_generate_sdp_fmtp(const struct ast_format *format, unsigned int payload, struct ast_str **str);
228
229 /*!
230  * \brief Register a format interface for use with the provided codec
231  *
232  * \param codec The name of codec the interface is applicable to
233  * \param interface A pointer to the interface implementation
234  * \param mod The module this format interface is provided by
235  *
236  * \retval 0 success
237  * \retval -1 failure
238  */
239 int __ast_format_interface_register(const char *codec, const struct ast_format_interface *interface, struct ast_module *mod);
240
241 /*!
242  * \brief Register a format interface for use with the provided codec
243  *
244  * \param codec The name of codec the interface is applicable to
245  * \param interface A pointer to the interface implementation
246  *
247  * \retval 0 success
248  * \retval -1 failure
249  */
250 #define ast_format_interface_register(codec, interface) __ast_format_interface_register(codec, interface, AST_MODULE_SELF)
251
252 /*!
253  * \brief Get the attribute data on a format
254  *
255  * \param format The media format
256  *
257  * \return Currently set attribute data
258  */
259 void *ast_format_get_attribute_data(const struct ast_format *format);
260
261 /*!
262  * \brief Set the attribute data on a format
263  *
264  * \param format The media format
265  * \param attribute_data The attribute data
266  */
267 void ast_format_set_attribute_data(struct ast_format *format, void *attribute_data);
268
269 /*!
270  * \brief Get the name associated with a format
271  *
272  * \param format The media format
273  *
274  * \return The name of the format
275  */
276 const char *ast_format_get_name(const struct ast_format *format);
277
278 /*!
279  * \brief Get the codec associated with a format
280  *
281  * \param format The media format
282  *
283  * \return The codec
284  *
285  * \note The reference count of the returned codec is increased by 1 and must be decremented
286  */
287 struct ast_codec *ast_format_get_codec(const struct ast_format *format);
288
289 /*!
290  * \brief Get the codec identifier associated with a format
291  *
292  * \param format The media format
293  *
294  * \return codec identifier
295  */
296 unsigned int ast_format_get_codec_id(const struct ast_format *format);
297
298 /*!
299  * \brief Get the codec name associated with a format
300  *
301  * \param format The media format
302  *
303  * \return The codec name
304  */
305 const char *ast_format_get_codec_name(const struct ast_format *format);
306
307 /*!
308  * \brief Get whether or not the format can be smoothed
309  *
310  * \param format The media format
311  *
312  * \retval 0 the format cannot be smoothed
313  * \retval 1 the format can be smoothed
314  */
315 int ast_format_can_be_smoothed(const struct ast_format *format);
316
317 /*!
318  * \brief Get the media type of a format
319  *
320  * \param format The media format
321  *
322  * \return the media type
323  */
324 enum ast_media_type ast_format_get_type(const struct ast_format *format);
325
326 /*!
327  * \brief Get the default framing size (in milliseconds) for a format
328  *
329  * \param format The media format
330  *
331  * \return default framing size in milliseconds
332  */
333 unsigned int ast_format_get_default_ms(const struct ast_format *format);
334
335 /*!
336  * \brief Get the minimum amount of media carried in this format
337  *
338  * \param format The media format
339  *
340  * \return minimum framing size in milliseconds
341  */
342 unsigned int ast_format_get_minimum_ms(const struct ast_format *format);
343
344 /*!
345  * \brief Get the maximum amount of media carried in this format
346  *
347  * \param format The media format
348  *
349  * \return maximum framing size in milliseconds
350  */
351 unsigned int ast_format_get_maximum_ms(const struct ast_format *format);
352
353 /*!
354  * \brief Get the minimum number of bytes expected in a frame for this format
355  *
356  * \param format The media format
357  *
358  * \return minimum expected bytes in a frame for this format
359  */
360 unsigned int ast_format_get_minimum_bytes(const struct ast_format *format);
361
362 /*!
363  * \brief Get the sample rate of a media format
364  *
365  * \param format The media format
366  *
367  * \return sample rate
368  */
369 unsigned int ast_format_get_sample_rate(const struct ast_format *format);
370
371 /*!
372  * \brief Get the length (in milliseconds) for the format with a given number of samples
373  *
374  * \param format The media format
375  * \param samples The number of samples
376  *
377  * \return length of media (in milliseconds)
378  */
379 unsigned int ast_format_determine_length(const struct ast_format *format, unsigned int samples);
380
381 /*!
382  * \since 12
383  * \brief Get the message type used for signaling a format registration
384  *
385  * \retval Stasis message type for format registration
386  * \retval NULL on error
387  */
388 struct stasis_message_type *ast_format_register_type(void);
389
390 /*!
391  * \since 12
392  * \brief Get the message type used for signaling a format unregistration
393  *
394  * \retval Stasis message type for format unregistration
395  * \retval NULL on error
396  */
397 struct stasis_message_type *ast_format_unregister_type(void);
398
399 #endif /* _AST_FORMAT_H */