stream: Make ast_stream_topology_create_from_format_cap() allow NULL cap.
[asterisk/asterisk.git] / include / asterisk / stream.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2017, 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 Media Stream API
22  *
23  * \author Joshua Colp <jcolp@digium.com>
24  */
25
26 #ifndef _AST_STREAM_H_
27 #define _AST_STREAM_H_
28
29 #include "asterisk/codec.h"
30
31 /*!
32  * \brief Forward declaration for a stream, as it is opaque
33  */
34 struct ast_stream;
35
36 /*!
37  * \brief Forward declaration for a format capability
38  */
39 struct ast_format_cap;
40
41 /*!
42  * \brief The topology of a set of streams
43  */
44 struct ast_stream_topology;
45
46 typedef void (*ast_stream_data_free_fn)(void *);
47
48 /*!
49  * \brief States that a stream may be in
50  */
51 enum ast_stream_state {
52     /*!
53      * \brief Set when the stream has been removed
54      */
55     AST_STREAM_STATE_REMOVED = 0,
56     /*!
57      * \brief Set when the stream is sending and receiving media
58      */
59     AST_STREAM_STATE_SENDRECV,
60     /*!
61      * \brief Set when the stream is sending media only
62      */
63     AST_STREAM_STATE_SENDONLY,
64     /*!
65      * \brief Set when the stream is receiving media only
66      */
67     AST_STREAM_STATE_RECVONLY,
68     /*!
69      * \brief Set when the stream is not sending OR receiving media
70      */
71     AST_STREAM_STATE_INACTIVE,
72 };
73
74 /*!
75  * \brief Stream data slots
76  */
77 enum ast_stream_data_slot {
78     /*!
79      * \brief Data slot for RTP instance
80      */
81         AST_STREAM_DATA_RTP_INSTANCE = 0,
82     /*!
83      * \brief Controls the size of the data pointer array
84      */
85         AST_STREAM_DATA_SLOT_MAX
86 };
87
88 /*!
89  * \brief Create a new media stream representation
90  *
91  * \param name A name for the stream
92  * \param type The media type the stream is handling
93  *
94  * \retval non-NULL success
95  * \retval NULL failure
96  *
97  * \note This is NOT an AO2 object and has no locking. It is expected that a higher level object provides protection.
98  *
99  * \note The stream will default to an inactive state until changed.
100  *
101  * \since 15
102  */
103 struct ast_stream *ast_stream_alloc(const char *name, enum ast_media_type type);
104
105 /*!
106  * \brief Destroy a media stream representation
107  *
108  * \param stream The media stream
109  *
110  * \since 15
111  */
112 void ast_stream_free(struct ast_stream *stream);
113
114 /*!
115  * \brief Create a deep clone of an existing stream
116  *
117  * \param stream The existing stream
118  *
119  * \retval non-NULL success
120  * \retval NULL failure
121  *
122  * \note Opaque data pointers set with ast_stream_set_data() are not part
123  * of the deep clone.  The pointers are simply copied.
124  *
125  * \since 15
126  */
127 struct ast_stream *ast_stream_clone(const struct ast_stream *stream);
128
129 /*!
130  * \brief Get the name of a stream
131  *
132  * \param stream The media stream
133  *
134  * \retval non-NULL success
135  * \retval NULL failure
136  *
137  * \since 15
138  */
139 const char *ast_stream_get_name(const struct ast_stream *stream);
140
141 /*!
142  * \brief Get the media type of a stream
143  *
144  * \param stream The media stream
145  *
146  * \return The media type of the stream (AST_MEDIA_TYPE_UNKNOWN on error)
147  *
148  * \since 15
149  */
150 enum ast_media_type ast_stream_get_type(const struct ast_stream *stream);
151
152 /*!
153  * \brief Change the media type of a stream
154  *
155  * \param stream The media stream
156  * \param type The new media type
157  *
158  * \since 15
159  */
160 void ast_stream_set_type(struct ast_stream *stream, enum ast_media_type type);
161
162 /*!
163  * \brief Get the current negotiated formats of a stream
164  *
165  * \param stream The media stream
166  *
167  * \retval non-NULL success
168  * \retval NULL failure
169  *
170  * \note The reference count is not increased
171  *
172  * \since 15
173  */
174 struct ast_format_cap *ast_stream_get_formats(const struct ast_stream *stream);
175
176 /*!
177  * \brief Set the current negotiated formats of a stream
178  *
179  * \param stream The media stream
180  * \param caps The current negotiated formats
181  *
182  * \note The new format capabilities structure has its refcount bumped and
183  * any existing format capabilities structure has its refcount decremented.
184  *
185  * \since 15
186  */
187 void ast_stream_set_formats(struct ast_stream *stream, struct ast_format_cap *caps);
188
189 /*!
190  * \brief Get the current state of a stream
191  *
192  * \param stream The media stream
193  *
194  * \return The state of the stream (AST_STREAM_STATE_UNKNOWN on error)
195  *
196  * \since 15
197  */
198 enum ast_stream_state ast_stream_get_state(const struct ast_stream *stream);
199
200 /*!
201  * \brief Set the state of a stream
202  *
203  * \param stream The media stream
204  * \param state The new state that the stream is in
205  *
206  * \note Used by stream creator to update internal state
207  *
208  * \since 15
209  */
210 void ast_stream_set_state(struct ast_stream *stream, enum ast_stream_state state);
211
212 /*!
213  * \brief Convert the state of a stream into a string
214  *
215  * \param state The stream state
216  *
217  * \return The state of the stream in string format
218  *
219  * \since 15
220  */
221 const char *ast_stream_state2str(enum ast_stream_state state);
222
223 /*!
224  * \brief Get the opaque stream data
225  *
226  * \param stream The media stream
227  * \param slot The data slot to retrieve
228  *
229  * \retval non-NULL success
230  * \retval NULL failure
231  *
232  * \since 15
233  */
234 void *ast_stream_get_data(struct ast_stream *stream, enum ast_stream_data_slot slot);
235
236 /*!
237  * \brief Set the opaque stream data
238  *
239  * \param stream The media stream
240  * \param slot The data slot to set
241  * \param data Opaque data
242  * \param data_free_fn Callback to free data when stream is freed. May be NULL for no action.
243  *
244  * \return data
245  *
246  * \since 15
247  */
248 void *ast_stream_set_data(struct ast_stream *stream, enum ast_stream_data_slot slot,
249         void *data, ast_stream_data_free_fn data_free_fn);
250
251 /*!
252  * \brief Get the position of the stream in the topology
253  *
254  * \param stream The media stream
255  *
256  * \return The position of the stream (-1 on error)
257  *
258  * \since 15
259  */
260 int ast_stream_get_position(const struct ast_stream *stream);
261
262 /*!
263  * \brief Create a stream topology
264  *
265  * \retval non-NULL success
266  * \retval NULL failure
267  *
268  * \since 15
269  */
270 struct ast_stream_topology *ast_stream_topology_alloc(void);
271
272 /*!
273  * \brief Create a deep clone of an existing stream topology
274  *
275  * \param topology The existing topology of streams
276  *
277  * \retval non-NULL success
278  * \retval NULL failure
279  *
280  * \since 15
281  */
282 struct ast_stream_topology *ast_stream_topology_clone(
283         const struct ast_stream_topology *topology);
284
285 /*!
286  * \brief Destroy a stream topology
287  *
288  * \param topology The topology of streams
289  *
290  * \note All streams contained within the topology will be destroyed
291  *
292  * \since 15
293  */
294 void ast_stream_topology_free(struct ast_stream_topology *topology);
295
296 /*!
297  * \brief Append a stream to the topology
298  *
299  * \param topology The topology of streams
300  * \param stream The stream to append
301  *
302  * \returns the position of the stream in the topology (-1 on error)
303  *
304  * \since 15
305  */
306 int ast_stream_topology_append_stream(struct ast_stream_topology *topology,
307         struct ast_stream *stream);
308
309 /*!
310  * \brief Get the number of streams in a topology
311  *
312  * \param topology The topology of streams
313  *
314  * \return the number of streams (-1 on error)
315  *
316  * \since 15
317  */
318 int ast_stream_topology_get_count(const struct ast_stream_topology *topology);
319
320 /*!
321  * \brief Get a specific stream from the topology
322  *
323  * \param topology The topology of streams
324  * \param position The topology position to get
325  *
326  * \retval non-NULL success
327  * \retval NULL failure
328  *
329  * \since 15
330  */
331 struct ast_stream *ast_stream_topology_get_stream(
332         const struct ast_stream_topology *topology, unsigned int position);
333
334 /*!
335  * \brief Set a specific position in a topology
336  *
337  * \param topology The topology of streams
338  * \param position The topology position to set
339  * \param stream The stream to put in its place
340  *
341  * \retval 0 success
342  * \retval -1 failure
343  *
344  * \note If an existing stream exists it will be destroyed
345  *
346  * \note You can overwrite an existing position in the topology or set
347  * the first unused position.  You can't set positions beyond that.
348  *
349  * \since 15
350  */
351 int ast_stream_topology_set_stream(struct ast_stream_topology *topology,
352         unsigned int position, struct ast_stream *stream);
353
354 /*!
355  * \brief A helper function that, given a format capabilities structure,
356  * creates a topology and separates the media types in format_cap into
357  * separate streams.
358  *
359  * \param caps The format capabilities structure (NULL creates an empty topology)
360  *
361  * \retval non-NULL success
362  * \retval NULL failure
363  *
364  * \note The format capabilities reference is NOT altered by this function
365  * since a new format capabilities structure is created for each media type.
366  *
367  * \note Each stream will have its name set to the corresponding media type.
368  * For example: "AST_MEDIA_TYPE_AUDIO".
369  *
370  * \note Each stream will be set to the sendrecv state.
371  *
372  * \since 15
373  */
374 struct ast_stream_topology *ast_stream_topology_create_from_format_cap(
375         struct ast_format_cap *cap);
376
377 /*!
378  * \brief A helper function that, given a stream topology, creates a format
379  * capabilities structure containing all formats from all streams.
380  *
381  * \param topology The topology of streams
382  *
383   * \retval non-NULL success
384   * \retval NULL failure
385   *
386   * \note The stream topology is NOT altered by this function.
387   *
388   * \since 15
389   */
390 struct ast_format_cap *ast_format_cap_from_stream_topology(
391     struct ast_stream_topology *topology);
392
393 /*!
394  * \brief Gets the first stream of a specific type from the topology
395  *
396  * \param topology The topology of streams
397  * \param type The media type
398  *
399  * \retval non-NULL success
400  * \retval NULL failure
401  *
402  * \since 15
403  */
404 struct ast_stream *ast_stream_topology_get_first_stream_by_type(
405         const struct ast_stream_topology *topology,
406         enum ast_media_type type);
407
408 #endif /* _AST_STREAM_H */