Asterisk - The Open Source Telephony Project GIT-master-d856a3e
codec.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 Codec API
22 *
23 * \author Joshua Colp <jcolp@digium.com>
24 */
25
26#ifndef _AST_CODEC_H_
27#define _AST_CODEC_H_
28
29/*! \brief Types of media */
37};
38
39struct ast_module;
40
41/*! \brief Represents a media codec within Asterisk. */
42struct ast_codec {
43 /*! \brief Internal unique identifier for this codec, set at registration time (starts at 1) */
44 unsigned int id;
45 /*! \brief Name for this codec */
46 const char *name;
47 /*! \brief Brief description */
48 const char *description;
49 /*! \brief Type of media this codec contains */
51 /*! \brief Sample rate (number of samples carried in a second) */
52 unsigned int sample_rate;
53 /*! \brief Minimum length of media that can be carried (in milliseconds) in a frame */
54 unsigned int minimum_ms;
55 /*! \brief Maximum length of media that can be carried (in milliseconds) in a frame */
56 unsigned int maximum_ms;
57 /*! \brief Default length of media carried (in milliseconds) in a frame */
58 unsigned int default_ms;
59 /*! \brief Length in bytes of the data payload of a minimum_ms frame */
60 unsigned int minimum_bytes;
61 /*!
62 * \brief Retrieve the number of samples in a frame
63 *
64 * \param frame The frame to examine
65 *
66 * \return the number of samples
67 */
68 int (*samples_count)(struct ast_frame *frame);
69 /*!
70 * \brief Retrieve the length of media from number of samples
71 *
72 * \param samples The number of samples
73 *
74 * \return The length of media in milliseconds
75 */
76 int (*get_length)(unsigned int samples);
77 /*! \brief Whether the media can be smoothed or not */
78 unsigned int smooth;
79 /*! \brief Flags to be passed to the smoother */
80 unsigned int smoother_flags;
81 /*! \brief Format quality, on scale from 0 to 150 (100 is ulaw, the reference). This allows better format to be used, ceterus paribus. */
82 unsigned int quality;
83 /*! \brief The module that registered this codec */
84 struct ast_module *mod;
85};
86
87/*!
88 * \brief Initialize codec support within the core.
89 *
90 * \retval 0 success
91 * \retval -1 failure
92 */
93int ast_codec_init(void);
94
95/*!
96 * \brief Initialize built-in codecs within the core.
97 *
98 * \retval 0 success
99 * \retval -1 failure
100 */
101int ast_codec_builtin_init(void);
102
103/*!
104 * \brief This function is used to register a codec with the Asterisk core. Registering
105 * allows it to be passed through in frames and configured in channel drivers.
106 *
107 * \param codec to register
108 * \param mod the module this codec is provided by
109 *
110 * \retval 0 success
111 * \retval -1 failure
112 */
113int __ast_codec_register(struct ast_codec *codec, struct ast_module *mod);
114
115/*!
116 * \brief This function is used to register a codec with the Asterisk core. Registering
117 * allows it to be passed through in frames and configured in channel drivers.
118 *
119 * \param codec to register
120 *
121 * \retval 0 success
122 * \retval -1 failure
123 */
124#define ast_codec_register(codec) __ast_codec_register(codec, AST_MODULE_SELF)
125
126/*!
127 * \brief Retrieve a codec given a name, type, and sample rate
128 *
129 * \param name The name of the codec
130 * \param type The type of the codec
131 * \param sample_rate Optional sample rate, may not be applicable for some types
132 *
133 * \retval non-NULL success
134 * \retval NULL failure
135 *
136 * \note The returned codec is reference counted and ao2_ref or ao2_cleanup
137 * must be used to release the reference.
138 */
139struct ast_codec *ast_codec_get(const char *name, enum ast_media_type type, unsigned int sample_rate);
140
141/*!
142 * \brief Retrieve a codec given the unique identifier
143 *
144 * \param id The unique identifier
145 *
146 * \retval non-NULL success
147 * \retval NULL failure
148 *
149 * \note Identifiers start at 1 so if iterating don't start at 0.
150 *
151 * \note The returned codec is reference counted and ao2_ref or ao2_cleanup
152 * must be used to release the reference.
153 */
154struct ast_codec *ast_codec_get_by_id(int id);
155
156/*!
157 * \brief Retrieve the current maximum identifier for codec iteration
158 *
159 * \return Maximum codec identifier
160 */
161int ast_codec_get_max(void);
162
163/*!
164 * \brief Conversion function to take a media type and turn it into a string
165 *
166 * \param type The media type
167 *
168 * \retval string representation of the media type
169 */
171
172/*!
173 * \brief Conversion function to take a media string and convert it to a media type
174 *
175 * \param media_type_str The media type string
176 *
177 * \retval The ast_media_type that corresponds to the string
178 *
179 * \since 15.0.0
180 */
181enum ast_media_type ast_media_type_from_str(const char *media_type_str);
182
183/*!
184 * \brief Get the number of samples contained within a frame
185 *
186 * \param frame The frame itself
187 *
188 * \retval number of samples in the frame
189 */
190unsigned int ast_codec_samples_count(struct ast_frame *frame);
191
192/*!
193 * \brief Get the length of media (in milliseconds) given a number of samples
194 *
195 * \param codec The codec itself
196 * \param samples The number of samples
197 *
198 * \retval length of media (in milliseconds)
199 */
200unsigned int ast_codec_determine_length(const struct ast_codec *codec, unsigned int samples);
201
202#endif /* _AST_CODEC_H */
static const char type[]
Definition: chan_ooh323.c:109
unsigned int ast_codec_determine_length(const struct ast_codec *codec, unsigned int samples)
Get the length of media (in milliseconds) given a number of samples.
Definition: codec.c:408
int __ast_codec_register(struct ast_codec *codec, struct ast_module *mod)
This function is used to register a codec with the Asterisk core. Registering allows it to be passed ...
Definition: codec.c:273
ast_media_type
Types of media.
Definition: codec.h:30
@ AST_MEDIA_TYPE_AUDIO
Definition: codec.h:32
@ AST_MEDIA_TYPE_UNKNOWN
Definition: codec.h:31
@ AST_MEDIA_TYPE_VIDEO
Definition: codec.h:33
@ AST_MEDIA_TYPE_END
Definition: codec.h:36
@ AST_MEDIA_TYPE_IMAGE
Definition: codec.h:34
@ AST_MEDIA_TYPE_TEXT
Definition: codec.h:35
enum ast_media_type ast_media_type_from_str(const char *media_type_str)
Conversion function to take a media string and convert it to a media type.
Definition: codec.c:364
int ast_codec_init(void)
Initialize codec support within the core.
Definition: codec.c:250
struct ast_codec * ast_codec_get(const char *name, enum ast_media_type type, unsigned int sample_rate)
Retrieve a codec given a name, type, and sample rate.
Definition: codec.c:327
unsigned int ast_codec_samples_count(struct ast_frame *frame)
Get the number of samples contained within a frame.
Definition: codec.c:379
struct ast_codec * ast_codec_get_by_id(int id)
Retrieve a codec given the unique identifier.
Definition: codec.c:338
const char * ast_codec_media_type2str(enum ast_media_type type)
Conversion function to take a media type and turn it into a string.
Definition: codec.c:348
int ast_codec_get_max(void)
Retrieve the current maximum identifier for codec iteration.
Definition: codec.c:343
int ast_codec_builtin_init(void)
Initialize built-in codecs within the core.
static const char name[]
Definition: format_mp3.c:68
Represents a media codec within Asterisk.
Definition: codec.h:42
unsigned int sample_rate
Sample rate (number of samples carried in a second)
Definition: codec.h:52
unsigned int maximum_ms
Maximum length of media that can be carried (in milliseconds) in a frame.
Definition: codec.h:56
unsigned int minimum_bytes
Length in bytes of the data payload of a minimum_ms frame.
Definition: codec.h:60
unsigned int smoother_flags
Flags to be passed to the smoother.
Definition: codec.h:80
unsigned int default_ms
Default length of media carried (in milliseconds) in a frame.
Definition: codec.h:58
int(* samples_count)(struct ast_frame *frame)
Retrieve the number of samples in a frame.
Definition: codec.h:68
enum ast_media_type type
Type of media this codec contains.
Definition: codec.h:50
int(* get_length)(unsigned int samples)
Retrieve the length of media from number of samples.
Definition: codec.h:76
unsigned int minimum_ms
Minimum length of media that can be carried (in milliseconds) in a frame.
Definition: codec.h:54
const char * description
Brief description.
Definition: codec.h:48
unsigned int quality
Format quality, on scale from 0 to 150 (100 is ulaw, the reference). This allows better format to be ...
Definition: codec.h:82
unsigned int smooth
Whether the media can be smoothed or not.
Definition: codec.h:78
struct ast_module * mod
The module that registered this codec.
Definition: codec.h:84
const char * name
Name for this codec.
Definition: codec.h:46
unsigned int id
Internal unique identifier for this codec, set at registration time (starts at 1)
Definition: codec.h:44
Data structure associated with a single frame of data.