Asterisk - The Open Source Telephony Project
GIT-master-3dae2cf
include
asterisk
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 */
34
enum
ast_format_cmp_res
{
35
/*! Both formats are equivalent to each other */
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
* \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
*/
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
* \return \ref 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 format 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
* \return Stasis message type for format registration
438
* \retval NULL on error
439
*/
440
struct
stasis_message_type
*
ast_format_register_type
(
void
);
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
*/
449
struct
stasis_message_type
*
ast_format_unregister_type
(
void
);
450
451
#endif
/* _AST_FORMAT_H */
str
const char * str
Definition:
app_jack.c:147
codec.h
Codec API.
ast_media_type
ast_media_type
Types of media.
Definition:
codec.h:30
ast_format_get_smoother_flags
int ast_format_get_smoother_flags(const struct ast_format *format)
Get smoother flags for this format.
Definition:
format.c:349
__ast_format_interface_register
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
ast_format_get_type
enum ast_media_type ast_format_get_type(const struct ast_format *format)
Get the media type of a format.
Definition:
format.c:354
ast_format_unregister_type
struct stasis_message_type * ast_format_unregister_type(void)
Get the message type used for signaling a format unregistration.
ast_format_get_codec_id
unsigned int ast_format_get_codec_id(const struct ast_format *format)
Get the codec identifier associated with a format.
Definition:
format.c:329
ast_format_get_codec
struct ast_codec * ast_format_get_codec(const struct ast_format *format)
Get the codec associated with a format.
Definition:
format.c:324
ast_format_attribute_set
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
ast_format_can_be_smoothed
int ast_format_can_be_smoothed(const struct ast_format *format)
Get whether or not the format can be smoothed.
Definition:
format.c:344
ast_format_set_channel_count
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
ast_format_get_attribute_data
void * ast_format_get_attribute_data(const struct ast_format *format)
Get the attribute data on a format.
Definition:
format.c:125
ast_format_get_minimum_bytes
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
ast_format_get_sample_rate
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_format_create_named
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
ast_format_get_minimum_ms
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
ast_format_joint
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
ast_format_cmp
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
ast_format_set_attribute_data
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
ast_format_cmp_res
Format comparison results.
Definition:
format.h:34
AST_FORMAT_CMP_SUBSET
@ AST_FORMAT_CMP_SUBSET
Definition:
format.h:40
AST_FORMAT_CMP_EQUAL
@ AST_FORMAT_CMP_EQUAL
Definition:
format.h:36
AST_FORMAT_CMP_NOT_EQUAL
@ AST_FORMAT_CMP_NOT_EQUAL
Definition:
format.h:38
ast_format_get_name
const char * ast_format_get_name(const struct ast_format *format)
Get the name associated with a format.
Definition:
format.c:334
ast_format_clone
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
ast_format_get_codec_name
const char * ast_format_get_codec_name(const struct ast_format *format)
Get the codec name associated with a format.
Definition:
format.c:339
ast_format_attribute_get
const void * ast_format_attribute_get(const struct ast_format *format, const char *name)
Definition:
format.c:267
ast_format_determine_length
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
ast_format_generate_sdp_fmtp
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
ast_format_get_default_ms
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
ast_format_parse_sdp_fmtp
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
ast_format_register_type
struct stasis_message_type * ast_format_register_type(void)
Get the message type used for signaling a format registration.
ast_format_create
struct ast_format * ast_format_create(struct ast_codec *codec)
Create a new media format.
Definition:
format.c:196
ast_format_get_channel_count
unsigned int ast_format_get_channel_count(const struct ast_format *format)
Get the channel count on a format.
Definition:
format.c:135
ast_format_get_maximum_ms
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
ast_format_init
int ast_format_init(void)
Initialize media format support.
Definition:
format.c:77
name
static const char name[]
Definition:
format_mp3.c:68
ast_codec
Represents a media codec within Asterisk.
Definition:
codec.h:42
ast_format_interface
Optional format interface to extend format operations.
Definition:
format.h:44
ast_format_interface::format_attribute_set
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
ast_format_interface::format_destroy
void(*const format_destroy)(struct ast_format *format)
Callback for when the format is destroyed, used to release attribute resources.
Definition:
format.h:50
ast_format_interface::format_generate_sdp_fmtp
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
ast_format_interface::format_clone
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
ast_format_interface::format_parse_sdp_fmtp
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
ast_format_interface::format_attribute_get
const void *(*const format_attribute_get)(const struct ast_format *format, const char *name)
Retrieve a particular format attribute setting.
Definition:
format.h:134
ast_format_interface::format_get_joint
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
ast_format_interface::format_cmp
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
ast_format
Definition of a media format.
Definition:
format.c:43
ast_format::codec
struct ast_codec * codec
Pointer to the codec in use for this format.
Definition:
format.c:47
ast_format::attribute_data
void * attribute_data
Attribute specific data, implementation specific.
Definition:
format.c:49
ast_format::channel_count
unsigned int channel_count
The number if audio channels used, if more than one an interleaved format is required.
Definition:
format.c:53
ast_format::interface
const struct ast_format_interface * interface
Pointer to the optional format interface.
Definition:
format.c:51
ast_module
Definition:
loader.c:293
ast_str
Support for dynamic strings.
Definition:
strings.h:623
stasis_message_type
Definition:
stasis_message.c:38
value
int value
Definition:
syslog.c:37
Generated on Wed Nov 27 2024 20:04:16 for Asterisk - The Open Source Telephony Project by
1.9.4