a5ca038183a2d4442430bcd4191b56e545a96145
[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          * \since 13.6.0
126          * \brief Retrieve a particular format attribute setting
127          *
128          * \param format The format containing attributes
129          * \param name The name of the attribute to retrieve
130          *
131          * \retval NULL if the parameter is not set on the format
132          * \retval non-NULL the format attribute value
133          */
134         const void *(* const format_attribute_get)(const struct ast_format *format, const char *name);
135 };
136
137 /*!
138  * \brief Initialize media format support
139  *
140  * \retval 0 success
141  * \retval -1 failure
142  */
143 int ast_format_init(void);
144
145 /*!
146  * \brief Create a new media format
147  *
148  * \param codec The codec to use
149  *
150  * \retval non-NULL success
151  * \retval NULL failure
152  *
153  * \note The format is returned with reference count incremented. It must be released using
154  * ao2_ref or ao2_cleanup.
155  */
156 struct ast_format *ast_format_create(struct ast_codec *codec);
157
158 /*!
159  * \brief Create a new media format with a specific name
160  *
161  * \param format_name The name to use for the format
162  * \param codec The codec to use
163  *
164  * \note This creation function should be used when the name of the \c codec
165  * cannot be explicitly used for the name of the format. This is the case for
166  * codecs with multiple sample rates
167  *
168  * \note The format is returned with reference count incremented. It must be released using
169  * ao2_ref or ao2_cleanup.
170  *
171  * \retval non-NULL success
172  * \retval NULL failure
173  */
174 struct ast_format *ast_format_create_named(const char *format_name, struct ast_codec *codec);
175
176 /*!
177  * \brief Clone an existing media format so it can be modified
178  *
179  * \param format The existing media format
180  *
181  * \note The returned format is a new ao2 object. It must be released using ao2_cleanup.
182  *
183  * \retval non-NULL success
184  * \retval NULL failure
185  */
186 struct ast_format *ast_format_clone(const struct ast_format *format);
187
188 /*!
189  * \brief Compare two formats
190  *
191  * \retval ast_format_cmp_res representing the result of comparing format1 and format2.
192  */
193 enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2);
194
195 /*!
196  * \brief Get a common joint capability between two formats
197  *
198  * \retval non-NULL if joint capability exists
199  * \retval NULL if no joint capability exists
200  *
201  * \note The returned format must be treated as immutable.
202  */
203 struct ast_format *ast_format_joint(const struct ast_format *format1, const struct ast_format *format2);
204
205 /*!
206  * \brief Set an attribute on a format to a specific value
207  *
208  * \param format The format to set the attribute on
209  * \param name Attribute name
210  * \param value Attribute value
211  *
212  * \retval non-NULL success
213  * \retval NULL failure
214  */
215 struct ast_format *ast_format_attribute_set(const struct ast_format *format, const char *name,
216         const char *value);
217
218 /*!
219  * \since 13.6.0
220  *
221  * \param format The format to retrieve the attribute from
222  * \param name Attribute name
223  *
224  * \retval non-NULL the attribute value
225  * \retval NULL the attribute does not exist or is unset
226  */
227 const void *ast_format_attribute_get(const struct ast_format *format, const char *name);
228
229 /*!
230  * \brief This function is used to have a media format aware module parse and interpret
231  * SDP attribute information. Once interpreted this information is stored on the format
232  * itself using Asterisk format attributes.
233  *
234  * \param format to set
235  * \param attributes string containing the fmtp line from the SDP
236  *
237  * \retval non-NULL success, attribute values were valid
238  * \retval NULL failure, values were not acceptable
239  */
240 struct ast_format *ast_format_parse_sdp_fmtp(const struct ast_format *format, const char *attributes);
241
242 /*!
243  * \brief This function is used to produce an fmtp SDP line for an Asterisk format. The
244  * attributes present on the Asterisk format are translated into the SDP equivalent.
245  *
246  * \param format to generate an fmtp line for
247  * \param payload numerical payload for the fmtp line
248  * \param str structure that the fmtp line will be appended to
249  */
250 void ast_format_generate_sdp_fmtp(const struct ast_format *format, unsigned int payload, struct ast_str **str);
251
252 /*!
253  * \brief Register a format interface for use with the provided codec
254  *
255  * \param codec The name of codec the interface is applicable to
256  * \param interface A pointer to the interface implementation
257  * \param mod The module this format interface is provided by
258  *
259  * \retval 0 success
260  * \retval -1 failure
261  */
262 int __ast_format_interface_register(const char *codec, const struct ast_format_interface *interface, struct ast_module *mod);
263
264 /*!
265  * \brief Register a format interface for use with the provided codec
266  *
267  * \param codec The name of codec the interface is applicable to
268  * \param interface A pointer to the interface implementation
269  *
270  * \retval 0 success
271  * \retval -1 failure
272  */
273 #define ast_format_interface_register(codec, interface) __ast_format_interface_register(codec, interface, AST_MODULE_SELF)
274
275 /*!
276  * \brief Get the attribute data on a format
277  *
278  * \param format The media format
279  *
280  * \return Currently set attribute data
281  */
282 void *ast_format_get_attribute_data(const struct ast_format *format);
283
284 /*!
285  * \brief Set the attribute data on a format
286  *
287  * \param format The media format
288  * \param attribute_data The attribute data
289  */
290 void ast_format_set_attribute_data(struct ast_format *format, void *attribute_data);
291
292 /*!
293  * \brief Get the name associated with a format
294  *
295  * \param format The media format
296  *
297  * \return The name of the format
298  */
299 const char *ast_format_get_name(const struct ast_format *format);
300
301 /*!
302  * \brief Get the codec associated with a format
303  *
304  * \param format The media format
305  *
306  * \return The codec
307  *
308  * \note The reference count of the returned codec is increased by 1 and must be decremented
309  */
310 struct ast_codec *ast_format_get_codec(const struct ast_format *format);
311
312 /*!
313  * \brief Get the codec identifier associated with a format
314  *
315  * \param format The media format
316  *
317  * \return codec identifier
318  */
319 unsigned int ast_format_get_codec_id(const struct ast_format *format);
320
321 /*!
322  * \brief Get the codec name associated with a format
323  *
324  * \param format The media format
325  *
326  * \return The codec name
327  */
328 const char *ast_format_get_codec_name(const struct ast_format *format);
329
330 /*!
331  * \brief Get whether or not the format can be smoothed
332  *
333  * \param format The media format
334  *
335  * \retval 0 the format cannot be smoothed
336  * \retval 1 the format can be smoothed
337  */
338 int ast_format_can_be_smoothed(const struct ast_format *format);
339
340 /*!
341  * \brief Get the media type of a format
342  *
343  * \param format The media format
344  *
345  * \return the media type
346  */
347 enum ast_media_type ast_format_get_type(const struct ast_format *format);
348
349 /*!
350  * \brief Get the default framing size (in milliseconds) for a format
351  *
352  * \param format The media format
353  *
354  * \return default framing size in milliseconds
355  */
356 unsigned int ast_format_get_default_ms(const struct ast_format *format);
357
358 /*!
359  * \brief Get the minimum amount of media carried in this format
360  *
361  * \param format The media format
362  *
363  * \return minimum framing size in milliseconds
364  */
365 unsigned int ast_format_get_minimum_ms(const struct ast_format *format);
366
367 /*!
368  * \brief Get the maximum amount of media carried in this format
369  *
370  * \param format The media format
371  *
372  * \return maximum framing size in milliseconds
373  */
374 unsigned int ast_format_get_maximum_ms(const struct ast_format *format);
375
376 /*!
377  * \brief Get the minimum number of bytes expected in a frame for this format
378  *
379  * \param format The media format
380  *
381  * \return minimum expected bytes in a frame for this format
382  */
383 unsigned int ast_format_get_minimum_bytes(const struct ast_format *format);
384
385 /*!
386  * \brief Get the sample rate of a media format
387  *
388  * \param format The media format
389  *
390  * \return sample rate
391  */
392 unsigned int ast_format_get_sample_rate(const struct ast_format *format);
393
394 /*!
395  * \brief Get the length (in milliseconds) for the format with a given number of samples
396  *
397  * \param format The media format
398  * \param samples The number of samples
399  *
400  * \return length of media (in milliseconds)
401  */
402 unsigned int ast_format_determine_length(const struct ast_format *format, unsigned int samples);
403
404 /*!
405  * \since 12
406  * \brief Get the message type used for signaling a format registration
407  *
408  * \retval Stasis message type for format registration
409  * \retval NULL on error
410  */
411 struct stasis_message_type *ast_format_register_type(void);
412
413 /*!
414  * \since 12
415  * \brief Get the message type used for signaling a format unregistration
416  *
417  * \retval Stasis message type for format unregistration
418  * \retval NULL on error
419  */
420 struct stasis_message_type *ast_format_unregister_type(void);
421
422 #endif /* _AST_FORMAT_H */