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