Asterisk - The Open Source Telephony Project  21.4.1
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 */
31  AST_MEDIA_TYPE_UNKNOWN = 0,
32  AST_MEDIA_TYPE_AUDIO,
33  AST_MEDIA_TYPE_VIDEO,
34  AST_MEDIA_TYPE_IMAGE,
35  AST_MEDIA_TYPE_TEXT,
36  AST_MEDIA_TYPE_END,
37 };
38 
39 struct ast_module;
40 
41 /*! \brief Represents a media codec within Asterisk. */
42 struct 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  */
93 int 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  */
101 int 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  */
113 int __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  */
139 struct 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  */
154 struct 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  */
161 int 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  */
181 enum 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  */
190 unsigned 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  */
200 unsigned int ast_codec_determine_length(const struct ast_codec *codec, unsigned int samples);
201 
202 #endif /* _AST_CODEC_H */
int ast_codec_builtin_init(void)
Initialize built-in codecs within the core.
unsigned int smoother_flags
Flags to be passed to the smoother.
Definition: codec.h:80
unsigned int minimum_bytes
Length in bytes of the data payload of a minimum_ms frame.
Definition: codec.h:60
const char * name
Name for this codec.
Definition: codec.h:46
struct ast_codec * ast_codec_get_by_id(int id)
Retrieve a codec given the unique identifier.
Definition: codec.c:338
unsigned int id
Internal unique identifier for this codec, set at registration time (starts at 1) ...
Definition: codec.h:44
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
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
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
struct ast_module * mod
The module that registered this codec.
Definition: codec.h:84
unsigned int default_ms
Default length of media carried (in milliseconds) in a frame.
Definition: codec.h:58
int ast_codec_init(void)
Initialize codec support within the core.
Definition: codec.c:250
int ast_codec_get_max(void)
Retrieve the current maximum identifier for codec iteration.
Definition: codec.c:343
unsigned int maximum_ms
Maximum length of media that can be carried (in milliseconds) in a frame.
Definition: codec.h:56
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
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 ast_codec_samples_count(struct ast_frame *frame)
Get the number of samples contained within a frame.
Definition: codec.c:379
const char * description
Brief description.
Definition: codec.h:48
int(* get_length)(unsigned int samples)
Retrieve the length of media from number of samples.
Definition: codec.h:76
unsigned int sample_rate
Sample rate (number of samples carried in a second)
Definition: codec.h:52
int(* samples_count)(struct ast_frame *frame)
Retrieve the number of samples in a frame.
Definition: codec.h:68
Data structure associated with a single frame of data.
enum ast_media_type type
Type of media this codec contains.
Definition: codec.h:50
unsigned int smooth
Whether the media can be smoothed or not.
Definition: codec.h:78
ast_media_type
Types of media.
Definition: codec.h:30
unsigned int minimum_ms
Minimum length of media that can be carried (in milliseconds) in a frame.
Definition: codec.h:54
Represents a media codec within Asterisk.
Definition: codec.h:42
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