Asterisk - The Open Source Telephony Project  GIT-master-44aef04
format.h
Go to the documentation of this file.
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 */
35  /*! Both formats are equivalent to each other */
37  /*! Both formats are completely different and not the same in any way */
39  /*! Both formats are similar but not equivalent */
41 };
42 
43 /*! \brief Optional format interface to extend format operations */
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 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  */
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 channel count on a format
303  *
304  * \param The media format
305  *
306  * \return Currently set channel count
307  */
308 unsigned int ast_format_get_channel_count(const struct ast_format *format);
309 
310 /*!
311  * \brief Set the channel count on a format
312  *
313  * \param format The media format
314  * \param channel_count The number of audio channels used
315  *
316  */
317 void ast_format_set_channel_count(struct ast_format *format, unsigned int channel_count);
318 
319 /*!
320  * \brief Get the codec associated with a format
321  *
322  * \param format The media format
323  *
324  * \return The codec
325  *
326  * \note The reference count of the returned codec is increased by 1 and must be decremented
327  */
328 struct ast_codec *ast_format_get_codec(const struct ast_format *format);
329 
330 /*!
331  * \brief Get the codec identifier associated with a format
332  *
333  * \param format The media format
334  *
335  * \return codec identifier
336  */
337 unsigned int ast_format_get_codec_id(const struct ast_format *format);
338 
339 /*!
340  * \brief Get the codec name associated with a format
341  *
342  * \param format The media format
343  *
344  * \return The codec name
345  */
346 const char *ast_format_get_codec_name(const struct ast_format *format);
347 
348 /*!
349  * \brief Get whether or not the format can be smoothed
350  *
351  * \param format The media format
352  *
353  * \retval 0 the format cannot be smoothed
354  * \retval 1 the format can be smoothed
355  */
356 int ast_format_can_be_smoothed(const struct ast_format *format);
357 
358 /*!
359  * \since 13.17.0
360  *
361  * \brief Get smoother flags for this format
362  *
363  * \param format The media format
364  *
365  * \return smoother flags for the provided format
366  */
367 int ast_format_get_smoother_flags(const struct ast_format *format);
368 
369 /*!
370  * \brief Get the media type of a format
371  *
372  * \param format The media format
373  *
374  * \return the media type
375  */
376 enum ast_media_type ast_format_get_type(const struct ast_format *format);
377 
378 /*!
379  * \brief Get the default framing size (in milliseconds) for a format
380  *
381  * \param format The media format
382  *
383  * \return default framing size in milliseconds
384  */
385 unsigned int ast_format_get_default_ms(const struct ast_format *format);
386 
387 /*!
388  * \brief Get the minimum amount of media carried in this format
389  *
390  * \param format The media format
391  *
392  * \return minimum framing size in milliseconds
393  */
394 unsigned int ast_format_get_minimum_ms(const struct ast_format *format);
395 
396 /*!
397  * \brief Get the maximum amount of media carried in this format
398  *
399  * \param format The media format
400  *
401  * \return maximum framing size in milliseconds
402  */
403 unsigned int ast_format_get_maximum_ms(const struct ast_format *format);
404 
405 /*!
406  * \brief Get the minimum number of bytes expected in a frame for this format
407  *
408  * \param format The media format
409  *
410  * \return minimum expected bytes in a frame for this format
411  */
412 unsigned int ast_format_get_minimum_bytes(const struct ast_format *format);
413 
414 /*!
415  * \brief Get the sample rate of a media format
416  *
417  * \param format The media format
418  *
419  * \return sample rate
420  */
421 unsigned int ast_format_get_sample_rate(const struct ast_format *format);
422 
423 /*!
424  * \brief Get the length (in milliseconds) for the format with a given number of samples
425  *
426  * \param format The media format
427  * \param samples The number of samples
428  *
429  * \return length of media (in milliseconds)
430  */
431 unsigned int ast_format_determine_length(const struct ast_format *format, unsigned int samples);
432 
433 /*!
434  * \since 12
435  * \brief Get the message type used for signaling a format registration
436  *
437  * \retval Stasis message type for format registration
438  * \retval NULL on error
439  */
441 
442 /*!
443  * \since 12
444  * \brief Get the message type used for signaling a format unregistration
445  *
446  * \retval Stasis message type for format unregistration
447  * \retval NULL on error
448  */
450 
451 #endif /* _AST_FORMAT_H */
enum ast_media_type ast_format_get_type(const struct ast_format *format)
Get the media type of a format.
Definition: format.c:354
unsigned int ast_format_get_channel_count(const struct ast_format *format)
Get the channel count on a format.
Definition: format.c:135
struct ast_codec * ast_format_get_codec(const struct ast_format *format)
Get the codec associated with a format.
Definition: format.c:324
Optional format interface to extend format operations.
Definition: format.h:44
int ast_format_init(void)
Initialize media format support.
Definition: format.c:77
struct ast_format *(*const format_get_joint)(const struct ast_format *format1, const struct ast_format *format2)
Get a format with the joint compatible attributes of both provided formats.
Definition: format.h:86
const char * ast_format_get_codec_name(const struct ast_format *format)
Get the codec name associated with a format.
Definition: format.c:339
struct ast_format * ast_format_create(struct ast_codec *codec)
Create a new media format.
Definition: format.c:196
void ast_format_set_channel_count(struct ast_format *format, unsigned int channel_count)
Set the channel count on a format.
Definition: format.c:140
int(*const format_clone)(const struct ast_format *src, struct ast_format *dst)
Callback for when the format is cloned, used to clone attributes.
Definition: format.h:61
struct ast_format *(*const format_attribute_set)(const struct ast_format *format, const char *name, const char *value)
Set an attribute on a format.
Definition: format.h:98
Codec API.
Definition of a media format.
Definition: format.c:43
void * ast_format_get_attribute_data(const struct ast_format *format)
Get the attribute data on a format.
Definition: format.c:125
const char * ast_format_get_name(const struct ast_format *format)
Get the name associated with a format.
Definition: format.c:334
const char * str
Definition: app_jack.c:147
enum ast_format_cmp_res(*const format_cmp)(const struct ast_format *format1, const struct ast_format *format2)
Determine if format 1 is a subset of format 2.
Definition: format.h:71
int value
Definition: syslog.c:37
int ast_format_get_smoother_flags(const struct ast_format *format)
Get smoother flags for this format.
Definition: format.c:349
struct ast_format * ast_format_clone(const struct ast_format *format)
Clone an existing media format so it can be modified.
Definition: format.c:180
struct ast_format * ast_format_joint(const struct ast_format *format1, const struct ast_format *format2)
Get a common joint capability between two formats.
Definition: format.c:226
void(*const format_generate_sdp_fmtp)(const struct ast_format *format, unsigned int payload, struct ast_str **str)
Generate SDP attribute information from an ast_format structure.
Definition: format.h:121
enum ast_format_cmp_res ast_format_cmp(const struct ast_format *format1, const struct ast_format *format2)
Compare two formats.
Definition: format.c:201
void(*const format_destroy)(struct ast_format *format)
Callback for when the format is destroyed, used to release attribute resources.
Definition: format.h:50
struct stasis_message_type * ast_format_unregister_type(void)
Get the message type used for signaling a format unregistration.
ast_format_cmp_res
Format comparison results.
Definition: format.h:34
unsigned int ast_format_get_minimum_bytes(const struct ast_format *format)
Get the minimum number of bytes expected in a frame for this format.
Definition: format.c:374
struct ast_format * ast_format_attribute_set(const struct ast_format *format, const char *name, const char *value)
Set an attribute on a format to a specific value.
Definition: format.c:248
void * attribute_data
Attribute specific data, implementation specific.
Definition: format.c:49
int ast_format_can_be_smoothed(const struct ast_format *format)
Get whether or not the format can be smoothed.
Definition: format.c:344
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
unsigned int ast_format_determine_length(const struct ast_format *format, unsigned int samples)
Get the length (in milliseconds) for the format with a given number of samples.
Definition: format.c:384
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
struct stasis_message_type * ast_format_register_type(void)
Get the message type used for signaling a format registration.
const void *(*const format_attribute_get)(const struct ast_format *format, const char *name)
Retrieve a particular format attribute setting.
Definition: format.h:134
static const char name[]
Definition: cdr_mysql.c:74
unsigned int ast_format_get_default_ms(const struct ast_format *format)
Get the default framing size (in milliseconds) for a format.
Definition: format.c:359
struct ast_format *(*const format_parse_sdp_fmtp)(const struct ast_format *format, const char *attributes)
Parse SDP attribute information, interpret it, and store it in the format structure.
Definition: format.h:110
const struct ast_format_interface * interface
Pointer to the optional format interface.
Definition: format.c:51
unsigned int channel_count
The number if audio channels used, if more than one an interleaved format is required.
Definition: format.c:53
void ast_format_set_attribute_data(struct ast_format *format, void *attribute_data)
Set the attribute data on a format.
Definition: format.c:130
unsigned int ast_format_get_maximum_ms(const struct ast_format *format)
Get the maximum amount of media carried in this format.
Definition: format.c:369
struct ast_format * ast_format_create_named(const char *format_name, struct ast_codec *codec)
Create a new media format with a specific name.
Definition: format.c:157
unsigned int ast_format_get_sample_rate(const struct ast_format *format)
Get the sample rate of a media format.
Definition: format.c:379
ast_media_type
Types of media.
Definition: codec.h:30
struct ast_format * ast_format_parse_sdp_fmtp(const struct ast_format *format, const char *attributes)
This function is used to have a media format aware module parse and interpret SDP attribute informati...
Definition: format.c:286
int __ast_format_interface_register(const char *codec, const struct ast_format_interface *interface, struct ast_module *mod)
Register a format interface for use with the provided codec.
Definition: format.c:90
unsigned int ast_format_get_minimum_ms(const struct ast_format *format)
Get the minimum amount of media carried in this format.
Definition: format.c:364
void ast_format_generate_sdp_fmtp(const struct ast_format *format, unsigned int payload, struct ast_str **str)
This function is used to produce an fmtp SDP line for an Asterisk format. The attributes present on t...
Definition: format.c:305
const void * ast_format_attribute_get(const struct ast_format *format, const char *name)
Definition: format.c:267
static snd_pcm_format_t format
Definition: chan_alsa.c:102
unsigned int ast_format_get_codec_id(const struct ast_format *format)
Get the codec identifier associated with a format.
Definition: format.c:329
Represents a media codec within Asterisk.
Definition: codec.h:42