Asterisk - The Open Source Telephony Project GIT-master-55f4e6d
format_cap.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 Format Capabilities API
22 *
23 * \author Joshua Colp <jcolp@digium.com>
24 */
25
26#ifndef _AST_FORMAT_CAP_H_
27#define _AST_FORMAT_CAP_H_
28
29#include "asterisk/codec.h"
30
31/*! Capabilities are represented by an opaque structure statically defined in format_cap.c */
32struct ast_format_cap;
33
35 /*!
36 * Default format capabilities settings
37 */
39};
40
41/*!
42 * \brief Allocate a new ast_format_cap structure
43 *
44 * \param flags Modifiers of struct behavior.
45 *
46 * \return ast_format_cap object on success.
47 * \retval NULL on failure.
48 */
49#define ast_format_cap_alloc(flags) \
50 __ast_format_cap_alloc((flags), "ast_format_cap_alloc", \
51 __FILE__, __LINE__, __PRETTY_FUNCTION__)
52#define ast_t_format_cap_alloc(flags, tag) \
53 __ast_format_cap_alloc((flags), (tag), __FILE__, __LINE__, __PRETTY_FUNCTION__)
55 const char *tag, const char *file, int line, const char *func);
56
57/*!
58 * \brief Set the global framing.
59 *
60 * \param cap The capabilities structure.
61 * \param framing The framing value (in milliseconds).
62 *
63 * \note This is used if a format does not provide a framing itself. Note that
64 * adding subsequent formats to the \c ast_format_cap structure may
65 * override this value, if the framing they require is less than the
66 * value set by this function.
67 */
68void ast_format_cap_set_framing(struct ast_format_cap *cap, unsigned int framing);
69
70/*!
71 * \brief Get the global framing.
72 *
73 * \param cap The capabilities structure.
74 *
75 * \retval 0 if no formats are in the structure and no framing has been provided
76 * \return The global framing value (in milliseconds)
77 *
78 * \note This will be the minimum framing allowed across all formats in the
79 * capabilities structure, or an overridden value
80 */
81unsigned int ast_format_cap_get_framing(const struct ast_format_cap *cap);
82
83/*!
84 * \brief Add format capability to capabilities structure.
85 *
86 * \param cap The capabilities structure to add to.
87 * \param format The format to add.
88 * \param framing The framing for the format (in milliseconds).
89 *
90 * \retval 0 success
91 * \retval -1 failure
92 *
93 * \note A reference to the format is taken and used in the capabilities structure.
94 *
95 * \note The order in which add is called determines the format preference order.
96 *
97 * \note If framing is specified here it overrides any global framing that has been set.
98 */
99#define ast_format_cap_append(cap, format, framing) \
100 __ast_format_cap_append((cap), (format), (framing), "ast_format_cap_append", \
101 __FILE__, __LINE__, __PRETTY_FUNCTION__)
102#define ast_t_format_cap_append(cap, format, framing, tag) \
103 __ast_format_cap_append((cap), (format), (framing), (tag), \
104 __FILE__, __LINE__, __PRETTY_FUNCTION__)
105int __ast_format_cap_append(struct ast_format_cap *cap, struct ast_format *format, unsigned int framing,
106 const char *tag, const char *file, int line, const char *func);
107
108/*!
109 * \brief Add all codecs Asterisk knows about for a specific type to
110 * the capabilities structure.
111 *
112 * \param cap The capabilities structure to add to.
113 * \param type The type of formats to add.
114 *
115 * \retval 0 success
116 * \retval -1 failure
117 *
118 * \note A generic format with no attributes is created using the codec.
119 *
120 * \note If AST_MEDIA_TYPE_UNKNOWN is passed as the type all known codecs will be added.
121 */
123
124/*!
125 * \brief Append the formats of provided type in src to dst
126 *
127 * \param dst The destination capabilities structure
128 * \param src The source capabilities structure
129 * \param type The type of formats to append.
130 *
131 * \retval 0 success
132 * \retval -1 failure
133 *
134 * \note If AST_MEDIA_TYPE_UNKNOWN is passed as the type all known codecs will be added.
135 */
136int ast_format_cap_append_from_cap(struct ast_format_cap *dst, const struct ast_format_cap *src, enum ast_media_type type);
137
138/*!
139 * \brief Replace the formats of provided type in dst with equivalent formats from src
140 *
141 * \param dst The destination capabilities structure
142 * \param src The source capabilities structure
143 * \param type The type of formats to replace.
144 *
145 * \note If AST_MEDIA_TYPE_UNKNOWN is passed as the type all known codecs will be replaced.
146 * \note Formats present in src but not dst will not be appended to dst.
147 */
148void ast_format_cap_replace_from_cap(struct ast_format_cap *dst, const struct ast_format_cap *src, enum ast_media_type type);
149
150/*!
151 * \brief Parse an "allow" or "deny" list and modify a format capabilities structure accordingly
152 *
153 * \param cap The capabilities structure to modify
154 * \param list The list containing formats to append or remove
155 * \param allowing If zero, start removing formats specified in the list. If non-zero,
156 * start appending formats specified in the list.
157 *
158 * \retval 0 on success
159 * \retval -1 on failure
160 */
161int ast_format_cap_update_by_allow_disallow(struct ast_format_cap *cap, const char *list, int allowing);
162
163/*!
164 * \brief Get the number of formats present within the capabilities structure
165 *
166 * \param cap The capabilities structure
167 *
168 * \return the number of formats
169 */
170size_t ast_format_cap_count(const struct ast_format_cap *cap);
171
172/*!
173 * \brief Get the format at a specific index
174 *
175 * \param cap The capabilities structure
176 * \param position The position to get
177 *
178 * \retval non-NULL success
179 * \retval NULL failure
180 *
181 * \note This is a zero based index.
182 *
183 * \note Formats are returned in order of preference.
184 *
185 * \note The reference count of the returned format is increased. It must be released using ao2_ref
186 * or ao2_cleanup.
187 */
188struct ast_format *ast_format_cap_get_format(const struct ast_format_cap *cap, int position);
189
190/*!
191 * \brief Get the most preferred format for a particular media type
192 *
193 * \param cap The capabilities structure
194 * \param type The type of media to get
195 *
196 * \retval non-NULL the preferred format
197 * \retval NULL no media of \c type present
198 *
199 * \note The reference count of the returned format is increased. It must be released using ao2_ref
200 * or ao2_cleanup.
201 */
203
204/*!
205 * \brief Get the framing for a format
206 *
207 * \param cap The capabilities structure
208 * \param format The format to retrieve
209 *
210 * \return the framing (in milliseconds)
211 */
212unsigned int ast_format_cap_get_format_framing(const struct ast_format_cap *cap, const struct ast_format *format);
213
214/*!
215 * \brief Remove format capability from capability structure.
216 *
217 * \note format must be an exact pointer match to remove from capabilities structure.
218 *
219 * \retval 0 remove was successful
220 * \retval -1 remove failed. Could not find format to remove
221 */
222int ast_format_cap_remove(struct ast_format_cap *cap, struct ast_format *format);
223
224/*!
225 * \brief Remove all formats matching a specific format type.
226 *
227 * \param cap The capabilities structure
228 * \param type The media type to remove formats of
229 *
230 * \note All formats can be removed by using the AST_MEDIA_TYPE_UNKNOWN type.
231 */
233
234/*!
235 * \brief Find if input ast_format is within the capabilities of the ast_format_cap object
236 * then return the compatible format from the capabilities structure in the result.
237 *
238 * \retval non-NULL if format is compatible
239 * \retval NULL if not compatible
240 *
241 * \note The reference count of the returned format is increased. It must be released using ao2_ref
242 * or ao2_cleanup.
243 */
244struct ast_format *ast_format_cap_get_compatible_format(const struct ast_format_cap *cap, const struct ast_format *format);
245
246/*!
247 * \brief Find if ast_format is within the capabilities of the ast_format_cap object.
248 *
249* \return ast_format_cmp_res representing the result of the compatibility check between cap and format.
250 */
251enum ast_format_cmp_res ast_format_cap_iscompatible_format(const struct ast_format_cap *cap, const struct ast_format *format);
252
253/*!
254 * \brief Find the compatible formats between two capabilities structures
255 *
256 * \param cap1 The first capabilities structure
257 * \param cap2 The second capabilities structure
258 * \param[out] result The capabilities structure to place the results into
259 *
260 * \retval 0 success
261 * \retval -1 failure
262 *
263 * \note The preference order of cap1 is respected.
264 *
265 * \note If failure occurs the result format capabilities structure may contain a partial result.
266 */
267int ast_format_cap_get_compatible(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2,
268 struct ast_format_cap *result);
269
270/*!
271 * \brief Determine if any joint capabilities exist between two capabilities structures
272 *
273 * \param cap1 The first capabilities structure
274 * \param cap2 The second capabilities structure
275 *
276 * \retval 0 no joint capabilities exist
277 * \retval 1 joint capabilities exist
278 */
279int ast_format_cap_iscompatible(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
280
281/*!
282 * \brief Determine if two capabilities structures are identical
283 *
284 * \param cap1 The first capabilities structure
285 * \param cap2 The second capabilities structure
286 *
287 * \retval 0 capabilities are not identical
288 * \retval 1 capabilities are identical
289 */
290int ast_format_cap_identical(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
291
292/*!
293 * \brief Find out if the capabilities structure has any formats
294 * of a specific type.
295 *
296 * \retval 1 true
297 * \retval 0 false, no formats of specific type.
298 */
299int ast_format_cap_has_type(const struct ast_format_cap *cap, enum ast_media_type type);
300
301/*!
302 * \brief Get the names of codecs of a set of formats
303 *
304 * \param cap The capabilities structure containing the formats
305 * \param buf A \c ast_str buffer to populate with the names of the formats
306 *
307 * \return The contents of the buffer in \c buf
308 */
309const char *ast_format_cap_get_names(const struct ast_format_cap *cap, struct ast_str **buf);
310
311/*!
312 * \brief Append the names of codecs of a set of formats to an ast_str buffer
313 * \since 18
314 *
315 * \param cap The capabilities structure containing the formats
316 * \param buf A \c ast_str buffer to append the names of the formats to
317 *
318 * \return The contents of the buffer in \c buf
319 */
320const char *ast_format_cap_append_names(const struct ast_format_cap *cap, struct ast_str **buf);
321
322#ifndef AST_FORMAT_CAP_NAMES_LEN
323/*! Buffer size for callers of ast_format_cap_get_names to allocate. */
324#define AST_FORMAT_CAP_NAMES_LEN 384
325#endif
326
327/*!
328 * \brief Determine if a format cap has no formats in it.
329 *
330 * \param cap The format cap to check for emptiness
331 * \retval 1 The format cap has zero formats or only ast_format_none
332 * \retval 0 The format cap has at least one format
333 */
334int ast_format_cap_empty(const struct ast_format_cap *cap);
335
336#endif /* _AST_FORMAT_CAP_H */
static PGresult * result
Definition: cel_pgsql.c:84
static const char type[]
Definition: chan_ooh323.c:109
Codec API.
ast_media_type
Types of media.
Definition: codec.h:30
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
ast_format_cmp_res
Format comparison results.
Definition: format.h:34
int ast_format_cap_empty(const struct ast_format_cap *cap)
Determine if a format cap has no formats in it.
Definition: format_cap.c:744
int ast_format_cap_append_by_type(struct ast_format_cap *cap, enum ast_media_type type)
Add all codecs Asterisk knows about for a specific type to the capabilities structure.
Definition: format_cap.c:216
struct ast_format * ast_format_cap_get_format(const struct ast_format_cap *cap, int position)
Get the format at a specific index.
Definition: format_cap.c:400
unsigned int ast_format_cap_get_format_framing(const struct ast_format_cap *cap, const struct ast_format *format)
Get the framing for a format.
Definition: format_cap.c:443
int ast_format_cap_update_by_allow_disallow(struct ast_format_cap *cap, const char *list, int allowing)
Parse an "allow" or "deny" list and modify a format capabilities structure accordingly.
Definition: format_cap.c:320
unsigned int ast_format_cap_get_framing(const struct ast_format_cap *cap)
Get the global framing.
Definition: format_cap.c:438
int ast_format_cap_remove(struct ast_format_cap *cap, struct ast_format *format)
Remove format capability from capability structure.
Definition: format_cap.c:495
struct ast_format * ast_format_cap_get_best_by_type(const struct ast_format_cap *cap, enum ast_media_type type)
Get the most preferred format for a particular media type.
Definition: format_cap.c:417
int ast_format_cap_get_compatible(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2, struct ast_format_cap *result)
Find the compatible formats between two capabilities structures.
Definition: format_cap.c:628
const char * ast_format_cap_append_names(const struct ast_format_cap *cap, struct ast_str **buf)
Append the names of codecs of a set of formats to an ast_str buffer.
Definition: format_cap.c:739
void ast_format_cap_remove_by_type(struct ast_format_cap *cap, enum ast_media_type type)
Remove all formats matching a specific format type.
Definition: format_cap.c:523
enum ast_format_cmp_res ast_format_cap_iscompatible_format(const struct ast_format_cap *cap, const struct ast_format *format)
Find if ast_format is within the capabilities of the ast_format_cap object.
Definition: format_cap.c:581
ast_format_cap_flags
Definition: format_cap.h:34
@ AST_FORMAT_CAP_FLAG_DEFAULT
Definition: format_cap.h:38
int ast_format_cap_append_from_cap(struct ast_format_cap *dst, const struct ast_format_cap *src, enum ast_media_type type)
Append the formats of provided type in src to dst.
Definition: format_cap.c:269
const char * ast_format_cap_get_names(const struct ast_format_cap *cap, struct ast_str **buf)
Get the names of codecs of a set of formats.
Definition: format_cap.c:734
void ast_format_cap_replace_from_cap(struct ast_format_cap *dst, const struct ast_format_cap *src, enum ast_media_type type)
Replace the formats of provided type in dst with equivalent formats from src.
Definition: format_cap.c:306
int ast_format_cap_identical(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2)
Determine if two capabilities structures are identical.
Definition: format_cap.c:687
int ast_format_cap_has_type(const struct ast_format_cap *cap, enum ast_media_type type)
Find out if the capabilities structure has any formats of a specific type.
Definition: format_cap.c:613
int ast_format_cap_iscompatible(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2)
Determine if any joint capabilities exist between two capabilities structures.
Definition: format_cap.c:653
int __ast_format_cap_append(struct ast_format_cap *cap, struct ast_format *format, unsigned int framing, const char *tag, const char *file, int line, const char *func)
Definition: format_cap.c:195
void ast_format_cap_set_framing(struct ast_format_cap *cap, unsigned int framing)
Set the global framing.
Definition: format_cap.c:136
struct ast_format_cap * __ast_format_cap_alloc(enum ast_format_cap_flags flags, const char *tag, const char *file, int line, const char *func)
Definition: format_cap.c:117
size_t ast_format_cap_count(const struct ast_format_cap *cap)
Get the number of formats present within the capabilities structure.
Definition: format_cap.c:395
struct ast_format * ast_format_cap_get_compatible_format(const struct ast_format_cap *cap, const struct ast_format *format)
Find if input ast_format is within the capabilities of the ast_format_cap object then return the comp...
Definition: format_cap.c:546
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
unsigned int framing
Global framing size, applies to all formats if no framing present on format.
Definition: format_cap.c:60
Definition of a media format.
Definition: format.c:43
Support for dynamic strings.
Definition: strings.h:623