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