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