Asterisk - The Open Source Telephony Project GIT-master-3dae2cf
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
31struct 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 * \return \ref 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 */
143int 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 */
174struct 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 */
186struct ast_format *ast_format_clone(const struct ast_format *format);
187
188/*!
189 * \brief Compare two formats
190 *
191 * \return \ref ast_format_cmp_res representing the result of comparing format1 and format2.
192 */
193enum 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 */
203struct 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 */
215struct 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 */
227const 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 */
240struct 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 */
250void 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 */
262int __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 */
282void *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 */
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 */
299const char *ast_format_get_name(const struct ast_format *format);
300
301/*!
302 * \brief Get the channel count on a format
303 *
304 * \param format The media format
305 *
306 * \return Currently set channel count
307 */
308unsigned 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 */
317void 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 */
328struct 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 */
337unsigned 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 */
346const 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 */
356int 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 */
367int 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 */
376enum 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 */
385unsigned 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 */
394unsigned 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 */
403unsigned 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 */
412unsigned 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 */
421unsigned 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 */
431unsigned 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 * \return 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 * \return Stasis message type for format unregistration
447 * \retval NULL on error
448 */
450
451#endif /* _AST_FORMAT_H */
const char * str
Definition: app_jack.c:147
Codec API.
ast_media_type
Types of media.
Definition: codec.h:30
int ast_format_get_smoother_flags(const struct ast_format *format)
Get smoother flags for this format.
Definition: format.c:349
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
enum ast_media_type ast_format_get_type(const struct ast_format *format)
Get the media type of a format.
Definition: format.c:354
struct stasis_message_type * ast_format_unregister_type(void)
Get the message type used for signaling a format unregistration.
unsigned int ast_format_get_codec_id(const struct ast_format *format)
Get the codec identifier associated with a format.
Definition: format.c:329
struct ast_codec * ast_format_get_codec(const struct ast_format *format)
Get the codec associated with a format.
Definition: format.c:324
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
int ast_format_can_be_smoothed(const struct ast_format *format)
Get whether or not the format can be smoothed.
Definition: format.c:344
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
void * ast_format_get_attribute_data(const struct ast_format *format)
Get the attribute data on a format.
Definition: format.c:125
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
unsigned int ast_format_get_sample_rate(const struct ast_format *format)
Get the sample rate of a media format.
Definition: format.c:379
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_minimum_ms(const struct ast_format *format)
Get the minimum amount of media carried in this format.
Definition: format.c:364
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
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 ast_format_set_attribute_data(struct ast_format *format, void *attribute_data)
Set the attribute data on a format.
Definition: format.c:130
ast_format_cmp_res
Format comparison results.
Definition: format.h:34
@ AST_FORMAT_CMP_SUBSET
Definition: format.h:40
@ AST_FORMAT_CMP_EQUAL
Definition: format.h:36
@ AST_FORMAT_CMP_NOT_EQUAL
Definition: format.h:38
const char * ast_format_get_name(const struct ast_format *format)
Get the name associated with a format.
Definition: format.c:334
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
const char * ast_format_get_codec_name(const struct ast_format *format)
Get the codec name associated with a format.
Definition: format.c:339
const void * ast_format_attribute_get(const struct ast_format *format, const char *name)
Definition: format.c:267
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
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
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 * 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
struct stasis_message_type * ast_format_register_type(void)
Get the message type used for signaling a format registration.
struct ast_format * ast_format_create(struct ast_codec *codec)
Create a new media format.
Definition: format.c:196
unsigned int ast_format_get_channel_count(const struct ast_format *format)
Get the channel count on a format.
Definition: format.c:135
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
int ast_format_init(void)
Initialize media format support.
Definition: format.c:77
static const char name[]
Definition: format_mp3.c:68
Represents a media codec within Asterisk.
Definition: codec.h:42
Optional format interface to extend format operations.
Definition: format.h:44
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
void(*const format_destroy)(struct ast_format *format)
Callback for when the format is destroyed, used to release attribute resources.
Definition: format.h:50
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
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_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 void *(*const format_attribute_get)(const struct ast_format *format, const char *name)
Retrieve a particular format attribute setting.
Definition: format.h:134
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
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
Definition of a media format.
Definition: format.c:43
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition: format.c:47
void * attribute_data
Attribute specific data, implementation specific.
Definition: format.c:49
unsigned int channel_count
The number if audio channels used, if more than one an interleaved format is required.
Definition: format.c:53
const struct ast_format_interface * interface
Pointer to the optional format interface.
Definition: format.c:51
Support for dynamic strings.
Definition: strings.h:623
int value
Definition: syslog.c:37