Clean up doxygen warnings
[asterisk/asterisk.git] / include / asterisk / format_cap.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2010, Digium, Inc.
5  *
6  * David Vossel <dvossel@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 Capability API
22  *
23  * \author David Vossel <dvossel@digium.com>
24  */
25
26 #ifndef _AST_FORMATCAP_H_
27 #define _AST_FORMATCAP_H_
28
29 /*! Capabilities are represented by an opaque structure statically defined in format_capability.c */
30 struct ast_format_cap;
31
32 /*!
33  * \brief Allocate a new ast_format_cap structure.
34  *
35  * \note Allocation of this object assumes locking
36  * is already occuring and that the point of contention
37  * is above this capabilities structure.  For example,
38  * a tech_pvt object referencing a capabilities structure
39  * can use this function as long as it always holds the
40  * tech_pvt lock while accessing its capabilities.
41  *
42  * \retval ast_format_cap object on success.
43  * \retval NULL on failure.
44  */
45 struct ast_format_cap *ast_format_cap_alloc_nolock(void);
46
47 /*!
48  * \brief Allocate a new ast_format_cap structure with locking
49  *
50  * \note If no other form of locking is taking place, use this function.
51  * This function makes most sense for globally accessible capabilities structures
52  * that have no other means of locking.
53  *
54  * \retval ast_format_cap object on success.
55  * \retval NULL on failure.
56  */
57 struct ast_format_cap *ast_format_cap_alloc(void);
58
59 /*!
60  * \brief Destroy an ast_format_cap structure.
61  *
62  * \return NULL
63  */
64 void *ast_format_cap_destroy(struct ast_format_cap *cap);
65
66 /*!
67  * \brief Add format capability to capabilities structure.
68  *
69  * \note A copy of the input format is made and that copy is
70  * what is placed in the ast_format_cap structure.  The actual
71  * input format ptr is not stored.
72  */
73 void ast_format_cap_add(struct ast_format_cap *cap, const struct ast_format *format);
74
75 /*!
76  * \brief Add all formats Asterisk knows about for a specific type to
77  * the capabilities structure.  Formats with attributes are set, but their
78  * attributes are initilized to 0's.  An attribute structure of 0's should
79  * indicate to the format attribute interface that the format has full
80  * capabilities.
81  *
82  * \note A copy of the input format is made and that copy is
83  * what is placed in the ast_format_cap structure.  The actual
84  * input format ptr is not stored.
85  */
86 void ast_format_cap_add_all_by_type(struct ast_format_cap *cap, enum ast_format_type type);
87
88 /*!
89  * \brief Add all known formats to the capabilities structure using default format attribute. */
90 void ast_format_cap_add_all(struct ast_format_cap *cap);
91
92 /*!
93  * \brief Append the formats in src to dst
94  */
95 void ast_format_cap_append(struct ast_format_cap *dst, const struct ast_format_cap *src);
96
97 /*!
98  * \brief Copy all items in src to dst.
99  * \note any items in dst will be removed before copying
100  */
101 void ast_format_cap_copy(struct ast_format_cap *dst, const struct ast_format_cap *src);
102
103 /*!
104  * \brief create a deep copy of an ast_format_cap structure
105  *
106  * \retval cap on success
107  * \retval NULL on failure
108  */
109 struct ast_format_cap *ast_format_cap_dup(const struct ast_format_cap *src);
110
111 /*!
112  * \brief determine if a capabilities structure is empty or not
113  *
114  * \retval 1, true is empty
115  * \retval 0, false, not empty
116  */
117 int ast_format_cap_is_empty(const struct ast_format_cap *cap);
118
119 /*!
120  * \brief Remove format capability from capability structure.
121  *
122  * \note format must match Exactly to format in ast_format_cap object in order
123  * to be removed.
124  *
125  * \retval 0, remove was successful
126  * \retval -1, remove failed. Could not find format to remove
127  */
128 int ast_format_cap_remove(struct ast_format_cap *cap, struct ast_format *format);
129
130 /*!
131  * \brief Remove all format capabilities from capability
132  * structure for a specific format id.
133  *
134  * \note This will remove _ALL_ formats matching the format id from the
135  * capabilities structure.
136  *
137  * \retval 0, remove was successful
138  * \retval -1, remove failed. Could not find formats to remove
139  */
140 int ast_format_cap_remove_byid(struct ast_format_cap *cap, enum ast_format_id id);
141
142 /*!
143  * \brief Remove all formats matching a specific format type.
144  */
145 void ast_format_cap_remove_bytype(struct ast_format_cap *cap, enum ast_format_type type);
146
147 /*!
148  * \brief Remove all format capabilities from capability structure
149  */
150 void ast_format_cap_remove_all(struct ast_format_cap *cap);
151
152 /*!
153  * \brief Remove all previous formats and set a single new format.
154  */
155 void ast_format_cap_set(struct ast_format_cap *cap, struct ast_format *format);
156
157 /*!
158  * \brief Find if input ast_format is within the capabilities of the ast_format_cap object
159  * then return the compatible format from the capabilities structure in the result.
160  *
161  * \retval 1 format is compatible with formats held in ast_format_cap object.
162  * \retval 0 format is not compatible with any formats in ast_format_cap object.
163  */
164 int ast_format_cap_get_compatible_format(const struct ast_format_cap *cap, const struct ast_format *format, struct ast_format *result);
165
166 /*!
167  * \brief Find if ast_format is within the capabilities of the ast_format_cap object.
168  *
169  * retval 1 format is compatible with formats held in ast_format_cap object.
170  * retval 0 format is not compatible with any formats in ast_format_cap object.
171  */
172 int ast_format_cap_iscompatible(const struct ast_format_cap *cap, const struct ast_format *format);
173
174 /*!
175  * \brief Finds the best quality audio format for a given format id and returns it in result.
176  *
177  * \retval 1 format found and set to result structure.
178  * \retval 0 no format found, result structure is cleared.
179  */
180 int ast_format_cap_best_byid(const struct ast_format_cap *cap, enum ast_format_id, struct ast_format *result);
181
182 /*!
183  * \brief is cap1 identical to cap2
184  *
185  * retval 1 true, identical
186  * retval 0 false, not identical
187  */
188 int ast_format_cap_identical(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
189
190 /*!
191  * \brief Get joint capability structure.
192  *
193  * \note returns an ast_format_cap object containing the joint capabilities on success.  This new
194  * capabilities structure is allocated with _NO_ locking enabled.  If a joint structure requires
195  * locking, allocate it and use the ast_format_cap_joint_copy function to fill it with the joint
196  * capabilities.
197  *
198  * \retval !NULL success, joint capabilties structure with _NO_ locking enabled.
199  * \retval NULL failure
200  */
201 struct ast_format_cap *ast_format_cap_joint(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
202
203 /*!
204  * \brief Get joint capability structure, copy into result capabilities structure
205  *
206  * \retval 1, joint capabilities exist
207  * \retval 0, joint capabilities do not exist
208  */
209 int ast_format_cap_joint_copy(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2, struct ast_format_cap *result);
210
211 /*!
212  * \brief Get joint capability structure, append into result capabilities structure
213  *
214  * \retval 1, joint capabilities exist
215  * \retval 0, joint capabilities do not exist
216  */
217 int ast_format_cap_joint_append(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2, struct ast_format_cap *result);
218
219 /*!
220  * \brief Find out if capability structures have any joint capabilities without
221  * returning those capabilities.
222  *
223  * \retval 1 true, has joint capabilities
224  * \retval 0 false, failure
225  */
226 int ast_format_cap_has_joint(const struct ast_format_cap *cap1, const struct ast_format_cap *cap2);
227
228 /*!
229  * \brief Get all capabilities for a specific media type
230  *
231  * \retval !NULL success, new capabilities structure with _NO_ locking enabled on the new structure.
232  * \retval NULL failure
233  */
234 struct ast_format_cap *ast_format_cap_get_type(const struct ast_format_cap *cap, enum ast_format_type ftype);
235
236 /*!
237  * \brief Find out if the capabilities structure has any formats
238  * of a specific type.
239  *
240  * \retval 1 true
241  * \retval 0 false, no formats of specific type.
242  */
243 int ast_format_cap_has_type(const struct ast_format_cap *cap, enum ast_format_type type);
244
245 /*! \brief Start iterating formats */
246 void ast_format_cap_iter_start(struct ast_format_cap *cap);
247
248 /*!
249  * \brief Next format in interation
250  *
251  * \details
252  * Here is how to use the ast_format_cap iterator.
253  *
254  * 1. call ast_format_cap_iter_start
255  * 2. call ast_format_cap_iter_next in a loop until it returns -1
256  * 3. call ast_format_cap_iter_end to terminate the iterator.
257  *
258  * example:
259  *
260  * ast_format_cap_iter_start(cap);
261  * while (!ast_format_cap_iter_next(cap, &format)) {
262  *
263  * }
264  * ast_format_cap_iter_end(Cap);
265  *
266  * \note Unless the container was alloced using no_lock, the container
267  * will be locked during the entire iteration until ast_format_cap_iter_end
268  * is called. XXX Remember this, and do not attempt to lock any containers
269  * within this iteration that will violate locking order.
270  *
271  * \retval 0 on success, new format is copied into input format struct
272  * \retval -1, no more formats are present.
273  */
274 int ast_format_cap_iter_next(struct ast_format_cap *cap, struct ast_format *format);
275
276 /*!
277  * \brief Ends ast_format_cap iteration.
278  * \note this must be call after every ast_format_cap_iter_start
279  */
280 void ast_format_cap_iter_end(struct ast_format_cap *cap);
281
282 /*!
283  * \brief ast_format_cap to old bitfield format represenatation
284  *
285  * \note This is only to be used for IAX2 compatibility 
286  *
287  * \retval old bitfield representation of ast_format_cap
288  * \retval 0, if no old bitfield capabilities are present in ast_format_cap
289  */
290 uint64_t ast_format_cap_to_old_bitfield(const struct ast_format_cap *cap);
291
292 /*!
293  * \brief convert old bitfield format to ast_format_cap represenatation
294  * \note This is only to be used for IAX2 compatibility 
295  */
296 void ast_format_cap_from_old_bitfield(struct ast_format_cap *dst, uint64_t src);
297
298 /*! \brief Get the names of a set of formats
299  * \param buf a buffer for the output string
300  * \param size size of buf (bytes)
301  * \param cap format the format (combined IDs of codecs)
302  * Prints a list of readable codec names corresponding to "format".
303  * ex: for format=AST_FORMAT_GSM|AST_FORMAT_SPEEX|AST_FORMAT_ILBC it will return "0x602 (GSM|SPEEX|ILBC)"
304  * \return The return value is buf.
305  */
306 char* ast_getformatname_multiple(char *buf, size_t size, struct ast_format_cap *cap);
307
308 #endif /* _AST_FORMATCAP_H */