1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
/*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 2014, Digium, Inc.
*
* Joshua Colp <jcolp@digium.com>
*
* See http://www.asterisk.org for more information about
* the Asterisk project. Please do not directly contact
* any of the maintainers of this project for assistance;
* the project provides a web site, mailing lists and IRC
* channels for your use.
*
* This program is free software, distributed under the terms of
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree.
*/
/*!
* \file
* \brief Codec API
*
* \author Joshua Colp <jcolp@digium.com>
*/
#ifndef _AST_CODEC_H_
#define _AST_CODEC_H_
/*! \brief Types of media */
enum ast_media_type {
AST_MEDIA_TYPE_UNKNOWN = 0,
AST_MEDIA_TYPE_AUDIO,
AST_MEDIA_TYPE_VIDEO,
AST_MEDIA_TYPE_IMAGE,
AST_MEDIA_TYPE_TEXT,
AST_MEDIA_TYPE_END,
};
struct ast_module;
/*! \brief Represents a media codec within Asterisk. */
struct ast_codec {
/*! \brief Internal unique identifier for this codec, set at registration time (starts at 1) */
unsigned int id;
/*! \brief Name for this codec */
const char *name;
/*! \brief Brief description */
const char *description;
/*! \brief Type of media this codec contains */
enum ast_media_type type;
/*! \brief Sample rate (number of samples carried in a second) */
unsigned int sample_rate;
/*! \brief Minimum length of media that can be carried (in milliseconds) in a frame */
unsigned int minimum_ms;
/*! \brief Maximum length of media that can be carried (in milliseconds) in a frame */
unsigned int maximum_ms;
/*! \brief Default length of media carried (in milliseconds) in a frame */
unsigned int default_ms;
/*! \brief Length in bytes of the data payload of a minimum_ms frame */
unsigned int minimum_bytes;
/*!
* \brief Retrieve the number of samples in a frame
*
* \param frame The frame to examine
*
* \return the number of samples
*/
int (*samples_count)(struct ast_frame *frame);
/*!
* \brief Retrieve the length of media from number of samples
*
* \param samples The number of samples
*
* \return The length of media in milliseconds
*/
int (*get_length)(unsigned int samples);
/*! \brief Whether the media can be smoothed or not */
unsigned int smooth;
/*! \brief Flags to be passed to the smoother */
unsigned int smoother_flags;
/*! \brief The module that registered this codec */
struct ast_module *mod;
};
/*!
* \brief Initialize codec support within the core.
*
* \retval 0 success
* \retval -1 failure
*/
int ast_codec_init(void);
/*!
* \brief Initialize built-in codecs within the core.
*
* \retval 0 success
* \retval -1 failure
*/
int ast_codec_builtin_init(void);
/*!
* \brief This function is used to register a codec with the Asterisk core. Registering
* allows it to be passed through in frames and configured in channel drivers.
*
* \param codec to register
* \param mod the module this codec is provided by
*
* \retval 0 success
* \retval -1 failure
*/
int __ast_codec_register(struct ast_codec *codec, struct ast_module *mod);
/*!
* \brief This function is used to register a codec with the Asterisk core. Registering
* allows it to be passed through in frames and configured in channel drivers.
*
* \param codec to register
*
* \retval 0 success
* \retval -1 failure
*/
#define ast_codec_register(codec) __ast_codec_register(codec, AST_MODULE_SELF)
/*!
* \brief Retrieve a codec given a name, type, and sample rate
*
* \param name The name of the codec
* \param type The type of the codec
* \param sample_rate Optional sample rate, may not be applicable for some types
*
* \retval non-NULL success
* \retval NULL failure
*
* \note The returned codec is reference counted and ao2_ref or ao2_cleanup
* must be used to release the reference.
*/
struct ast_codec *ast_codec_get(const char *name, enum ast_media_type type, unsigned int sample_rate);
/*!
* \brief Retrieve a codec given the unique identifier
*
* \param id The unique identifier
*
* \retval non-NULL success
* \retval NULL failure
*
* \note Identifiers start at 1 so if iterating don't start at 0.
*
* \note The returned codec is reference counted and ao2_ref or ao2_cleanup
* must be used to release the reference.
*/
struct ast_codec *ast_codec_get_by_id(int id);
/*!
* \brief Retrieve the current maximum identifier for codec iteration
*
* \return Maximum codec identifier
*/
int ast_codec_get_max(void);
/*!
* \brief Conversion function to take a media type and turn it into a string
*
* \param type The media type
*
* \retval string representation of the media type
*/
const char *ast_codec_media_type2str(enum ast_media_type type);
/*!
* \brief Conversion function to take a media string and convert it to a media type
*
* \param media_type_str The media type string
*
* \retval The ast_media_type that corresponds to the string
*
* \since 15.0.0
*/
enum ast_media_type ast_media_type_from_str(const char *media_type_str);
/*!
* \brief Get the number of samples contained within a frame
*
* \param frame The frame itself
*
* \retval number of samples in the frame
*/
unsigned int ast_codec_samples_count(struct ast_frame *frame);
/*!
* \brief Get the length of media (in milliseconds) given a number of samples
*
* \param codec The codec itself
* \param samples The number of samples
*
* \retval length of media (in milliseconds)
*/
unsigned int ast_codec_determine_length(const struct ast_codec *codec, unsigned int samples);
#endif /* _AST_CODEC_H */
|
