Asterisk - The Open Source Telephony Project  GIT-master-b91fb3c
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 
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 The module that registered this codec */
82  struct ast_module *mod;
83 };
84 
85 /*!
86  * \brief Initialize codec support within the core.
87  *
88  * \retval 0 success
89  * \retval -1 failure
90  */
91 int ast_codec_init(void);
92 
93 /*!
94  * \brief Initialize built-in codecs within the core.
95  *
96  * \retval 0 success
97  * \retval -1 failure
98  */
99 int ast_codec_builtin_init(void);
100 
101 /*!
102  * \brief This function is used to register a codec with the Asterisk core. Registering
103  * allows it to be passed through in frames and configured in channel drivers.
104  *
105  * \param codec to register
106  * \param mod the module this codec is provided by
107  *
108  * \retval 0 success
109  * \retval -1 failure
110  */
111 int __ast_codec_register(struct ast_codec *codec, struct ast_module *mod);
112 
113 /*!
114  * \brief This function is used to register a codec with the Asterisk core. Registering
115  * allows it to be passed through in frames and configured in channel drivers.
116  *
117  * \param codec to register
118  *
119  * \retval 0 success
120  * \retval -1 failure
121  */
122 #define ast_codec_register(codec) __ast_codec_register(codec, AST_MODULE_SELF)
123 
124 /*!
125  * \brief Retrieve a codec given a name, type, and sample rate
126  *
127  * \param name The name of the codec
128  * \param type The type of the codec
129  * \param sample_rate Optional sample rate, may not be applicable for some types
130  *
131  * \retval non-NULL success
132  * \retval NULL failure
133  *
134  * \note The returned codec is reference counted and ao2_ref or ao2_cleanup
135  * must be used to release the reference.
136  */
137 struct ast_codec *ast_codec_get(const char *name, enum ast_media_type type, unsigned int sample_rate);
138 
139 /*!
140  * \brief Retrieve a codec given the unique identifier
141  *
142  * \param id The unique identifier
143  *
144  * \retval non-NULL success
145  * \retval NULL failure
146  *
147  * \note Identifiers start at 1 so if iterating don't start at 0.
148  *
149  * \note The returned codec is reference counted and ao2_ref or ao2_cleanup
150  * must be used to release the reference.
151  */
152 struct ast_codec *ast_codec_get_by_id(int id);
153 
154 /*!
155  * \brief Retrieve the current maximum identifier for codec iteration
156  *
157  * \return Maximum codec identifier
158  */
159 int ast_codec_get_max(void);
160 
161 /*!
162  * \brief Conversion function to take a media type and turn it into a string
163  *
164  * \param type The media type
165  *
166  * \retval string representation of the media type
167  */
169 
170 /*!
171  * \brief Conversion function to take a media string and convert it to a media type
172  *
173  * \param media_type_str The media type string
174  *
175  * \retval The ast_media_type that corresponds to the string
176  *
177  * \since 15.0.0
178  */
179 enum ast_media_type ast_media_type_from_str(const char *media_type_str);
180 
181 /*!
182  * \brief Get the number of samples contained within a frame
183  *
184  * \param frame The frame itself
185  *
186  * \retval number of samples in the frame
187  */
188 unsigned int ast_codec_samples_count(struct ast_frame *frame);
189 
190 /*!
191  * \brief Get the length of media (in milliseconds) given a number of samples
192  *
193  * \param codec The codec itself
194  * \param samples The number of samples
195  *
196  * \retval length of media (in milliseconds)
197  */
198 unsigned int ast_codec_determine_length(const struct ast_codec *codec, unsigned int samples);
199 
200 #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:337
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:347
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:363
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:326
struct ast_module * mod
The module that registered this codec.
Definition: codec.h:82
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:249
int ast_codec_get_max(void)
Retrieve the current maximum identifier for codec iteration.
Definition: codec.c:342
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:272
unsigned int ast_codec_samples_count(struct ast_frame *frame)
Get the number of samples contained within a frame.
Definition: codec.c:378
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:407