Asterisk - The Open Source Telephony Project  GIT-master-a24979a
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 */
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  * \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  */
68 void 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  */
81 unsigned 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__)
105 int __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  */
136 int 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  */
148 void 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  */
161 int 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  */
170 size_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  */
188 struct 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  */
212 unsigned 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  */
222 int 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  */
244 struct 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  */
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  */
267 int 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  */
279 int 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  */
290 int 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  */
299 int 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  */
309 const 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  */
320 const 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  */
334 int 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 snd_pcm_format_t format
Definition: chan_alsa.c:106
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
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
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
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
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
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
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
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_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
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
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
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
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
void ast_format_cap_set_framing(struct ast_format_cap *cap, unsigned int framing)
Set the global framing.
Definition: format_cap.c:136
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
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:604