Asterisk - The Open Source Telephony Project GIT-master-d856a3e
stream.h
Go to the documentation of this file.
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 Internal macro to assist converting enums to strings
34 * \internal
35 * \since 18
36 *
37 * This macro checks that _value is in the bounds
38 * of the enum/string map.
39 */
40#define _stream_maps_to_str(_mapname, _value) \
41({ \
42 const char *_rtn = ""; \
43 if (ARRAY_IN_BOUNDS(_value, _mapname)) { \
44 _rtn = _mapname[_value]; \
45 } \
46 _rtn; \
47})
48
49/*!
50 * \brief Forward declaration for a stream, as it is opaque
51 */
52struct ast_stream;
53
54/*!
55 * \brief Forward declaration for a format capability
56 */
57struct ast_format_cap;
58
59/*!
60 * \brief The topology of a set of streams
61 */
63
64/*!
65 * \brief A mapping of two topologies.
66 */
68
69typedef void (*ast_stream_data_free_fn)(void *);
70
71/*!
72 * \brief States that a stream may be in
73 */
75 /*!
76 * \brief Set when the stream has been removed/declined
77 */
79 /*!
80 * \brief Set when the stream is sending and receiving media
81 */
83 /*!
84 * \brief Set when the stream is sending media only
85 */
87 /*!
88 * \brief Set when the stream is receiving media only
89 */
91 /*!
92 * \brief Set when the stream is not sending OR receiving media
93 */
95 /*!
96 * \brief Sentinel
97 */
99};
100
101/*!
102 * \brief Stream state enum to string map
103 * \internal
104 * \since 18
105 */
107
108/*!
109 * \brief Safely get the name of a stream state
110 * \since 18
111 *
112 * \param stream_state One of enum ast_stream_state
113 * \return A constant string with the name of the state or an empty string
114 * if an invalid value was passed in.
115 */
116#define ast_stream_state_to_str(stream_state) _stream_maps_to_str(ast_stream_state_map, stream_state)
117
118/*!
119 * \brief Advanced Codec Negotiation Preferences
120 * \since 18
121 */
122
123/*!
124 * \brief The preference parameters themselves
125 * \since 18
126 */
129 /*! Which of the lists to "prefer" */
131 /*! "operation" to perform */
133 /*! "keep" all or only first */
135 /*! Allow or prevent "transcode" */
137 /*! Sentinel */
139};
140
141/*!
142 * \brief The "prefer" values
143 * \since 18
144 */
147 /*! Prefer the "pending" list */
149 /*! Prefer the "configured" list */
151 /*! Sentinel */
153};
154
155/*!
156 * \brief The "operation" values
157 * \since 18
158 */
161 /*! "intersect": only those codecs that appear in both lists */
163 /*! "union": all codecs in both lists */
165 /*! "only_preferred": only the codecs in the preferred list */
167 /*! "only_nonpreferred": only the codecs in the non-preferred list */
169 /*! Sentinel */
171};
172
173/*!
174 * \brief The "keep" values
175 * \since 18
176 */
179 /*! "keep" all codecs after performing the operation */
181 /*! "keep" only the first codec after performing the operation */
183 /*! Sentinel */
185};
186
187/*!
188 * \brief The "transcode" values
189 * \since 18
190 */
193 /*! "allow" transcoding */
195 /*! "prevent" transcoding */
197 /*! Sentinel */
199};
200
201/*!
202 * \brief Preference enum to string map
203 * \internal
204 * \since 18
205 */
207
208/*!
209 * \brief "prefer" enum to string map
210 * \internal
211 * \since 18
212 */
214
215/*!
216 * \brief "operation" enum to string map
217 * \internal
218 * \since 18
219 */
221
222/*!
223 * \brief "keep" enum to string map
224 * \internal
225 * \since 18
226 */
228
229/*!
230 * \brief "transcode" state enum to string map
231 * \internal
232 * \since 18
233 */
235
236/*!
237 * \brief Safely get the name of a preference parameter
238 * \since 18
239 *
240 * \param value One of enum \ref ast_stream_codec_negotiation_params
241 * \return A constant string with the name of the preference or an empty string
242 * if an invalid value was passed in.
243 */
244#define ast_stream_codec_param_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_params_map, value)
245
246/*!
247 * \brief Safely get the name of a "prefer" parameter value
248 * \since 18
249 *
250 * \param value One of enum \ref ast_stream_codec_negotiation_prefs_prefer_values
251 * \return A constant string with the name of the value or an empty string
252 * if an invalid value was passed in.
253 */
254#define ast_stream_codec_prefer_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_prefer_map, value)
255
256/*!
257 * \brief Safely get the name of an "operation" parameter value
258 * \since 18
259 *
260 * \param value One of enum \ref ast_stream_codec_negotiation_prefs_operation_values
261 * \return A constant string with the name of the value or an empty string
262 * if an invalid value was passed in.
263 */
264#define ast_stream_codec_operation_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_operation_map, value)
265
266/*!
267 * \brief Safely get the name of a "keep" parameter value
268 * \since 18
269 *
270 * \param value One of enum \ref ast_stream_codec_negotiation_prefs_keep_values
271 * \return A constant string with the name of the value or an empty string
272 * if an invalid value was passed in.
273 */
274#define ast_stream_codec_keep_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_keep_map, value)
275
276/*!
277 * \brief Safely get the name of a "transcode" parameter value
278 * \since 18
279 *
280 * \param value One of enum \ref ast_stream_codec_negotiation_prefs_transcode_values
281 * \return A constant string with the name of the value or an empty string
282 * if an invalid value was passed in.
283 */
284#define ast_stream_codec_transcode_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_transcode_map, value)
285
286/*!
287 * \brief
288 * \since 18
289 *
290 * The structure that makes up a codec negotiation preference object
291 */
293 /*! Which codec list to prefer */
295 /*! The operation to perform on the lists */
297 /*! What to keep after the operation is performed */
299 /*! To allow or prevent transcoding */
301};
302
303/*!
304 * \brief Define for allocating buffer space for to_str() functions
305 * \since 18
306 */
307#define AST_STREAM_MAX_CODEC_PREFS_LENGTH (128)
308
309/*!
310 * \brief Return a string representing the codec preferences
311 * \since 18
312 *
313 * This function can be used for debugging purposes but is also
314 * used in pjsip_configuration as a sorcery parameter handler
315 *
316 * \param prefs A pointer to a ast_stream_codec_negotiation_prefs structure
317 * \param buf A pointer to an ast_str* used for the output. See note below.
318 *
319 * \return the contents of the ast_str as a const char *.
320 *
321 * \warning No attempt should ever be made to free the returned
322 * char * and it should be dup'd if needed after the ast_str is freed.
323 *
324 * \note
325 * buf can't be NULL but it CAN contain a NULL value. If so, a new
326 * ast_str will be allocated and the value of buf updated with a pointer
327 * to it. Whether the caller supplies the ast_str or it's allocated by
328 * this function, it's the caller's responsibility to free it.
329 *
330 * Sample output:
331 * "prefer: configured, operation: union, keep:all, transcode:prevent"
332 */
334 struct ast_str **buf);
335
336/*!
337 * \brief Parses a string representing the codec prefs into a ast_stream_codec_negotiation_pref structure
338 * \since 18
339 *
340 * This function is mainly used by pjsip_configuration as a sorcery parameter handler.
341 *
342 * \param pref_string A string in the format described by ast_stream_codec_prefs_to_str().
343 * \param prefs Pointer to a ast_stream_codec_negotiation_prefs structure to receive the parsed values.
344 * \param error_message An optional ast_str** into which parsing errors will be placed.
345 *
346 * \retval 0 if success
347 * \retval -1 if failed
348 *
349 * \details
350 * Whitespace around the ':' and ',' separators is ignored and the parameters
351 * can be specified in any order. Parameters missing in the input string
352 * will have their values set to the appropriate *_UNSPECIFIED value and will not
353 * be considered an error. It's up to the caller to decide whether set a default
354 * value, return an error, etc.
355 *
356 * Sample input:
357 * "prefer : configured , operation: union,keep:all, transcode:prevent"
358 */
359int ast_stream_codec_prefs_parse(const char *pref_string, struct ast_stream_codec_negotiation_prefs *prefs,
360 struct ast_str **error_message);
361
362/*!
363 * \brief Create a new media stream representation
364 *
365 * \param name A name for the stream
366 * \param type The media type the stream is handling
367 *
368 * \retval non-NULL success
369 * \retval NULL failure
370 *
371 * \note This is NOT an AO2 object and has no locking. It is expected that a higher level object provides protection.
372 *
373 * \note The stream will default to an inactive state until changed.
374 *
375 * \since 15
376 */
377struct ast_stream *ast_stream_alloc(const char *name, enum ast_media_type type);
378
379/*!
380 * \brief Destroy a media stream representation
381 *
382 * \param stream The media stream
383 *
384 * \since 15
385 */
386void ast_stream_free(struct ast_stream *stream);
387
388/*!
389 * \brief Create a deep clone of an existing stream
390 *
391 * \param stream The existing stream
392 * \param name Optional for cloned stream. If NULL, then existing stream's name is copied.
393 *
394 * \retval non-NULL success
395 * \retval NULL failure
396 *
397 * \note Opaque data pointers set with ast_stream_set_data() are not part
398 * of the deep clone. We have no way to clone the data.
399 *
400 * \since 15
401 */
402struct ast_stream *ast_stream_clone(const struct ast_stream *stream, const char *name);
403
404/*!
405 * \brief Get the name of a stream
406 *
407 * \param stream The media stream
408 *
409 * \retval non-NULL success
410 * \retval NULL failure
411 *
412 * \since 15
413 */
414const char *ast_stream_get_name(const struct ast_stream *stream);
415
416/*!
417 * \brief Get the media type of a stream
418 *
419 * \param stream The media stream
420 *
421 * \return The media type of the stream (AST_MEDIA_TYPE_UNKNOWN on error)
422 *
423 * \since 15
424 */
425enum ast_media_type ast_stream_get_type(const struct ast_stream *stream);
426
427/*!
428 * \brief Change the media type of a stream
429 *
430 * \param stream The media stream
431 * \param type The new media type
432 *
433 * \since 15
434 */
435void ast_stream_set_type(struct ast_stream *stream, enum ast_media_type type);
436
437/*!
438 * \brief Get the current negotiated formats of a stream
439 *
440 * \param stream The media stream
441 *
442 * \retval non-NULL success
443 * \retval NULL failure
444 *
445 * \note The reference count is not increased
446 *
447 * \since 15
448 */
449const struct ast_format_cap *ast_stream_get_formats(const struct ast_stream *stream);
450
451/*!
452 * \brief Get a string representing the stream for debugging/display purposes
453 * \since 18
454 *
455 * \param stream A stream
456 * \param buf A pointer to an ast_str* used for the output.
457 *
458 * \retval "" (empty string) if either buf or *buf are NULL
459 * \retval "(null stream)" if *stream was NULL
460 * \return <stream_representation> otherwise
461 *
462 * \warning No attempt should ever be made to free the returned
463 * char * and it should be dup'd if needed after the ast_str is freed.
464 *
465 * \details
466 *
467 * Return format:
468 * \verbatim <name>:<media_type>:<stream_state> (formats) \endverbatim
469 *
470 * Sample return:
471 * \verbatim "audio:audio:sendrecv (ulaw,g722)" \endverbatim
472 *
473 */
474const char *ast_stream_to_str(const struct ast_stream *stream, struct ast_str **buf);
475
476/*!
477 * \brief Get a stack allocated string representing the stream for debugging/display purposes
478 *
479 * \param __stream A stream
480 *
481 * \return A stack allocated pointer to a string representing the stream.
482 *
483 * \warning No attempt should ever be made to free the returned
484 * char* as it is allocated from the stack.
485 *
486 */
487#define ast_stream_to_stra(__stream) ast_str_tmp(128, ast_stream_to_str(__stream, &STR_TMP))
488
489/*!
490 * \brief Get the count of the current negotiated formats of a stream
491 *
492 * \param stream The media stream
493 *
494 * \return The count of negotiated formats
495 *
496 * \since 18
497 */
498int ast_stream_get_format_count(const struct ast_stream *stream);
499
500/*!
501 * \brief Set the current negotiated formats of a stream
502 *
503 * \param stream The media stream
504 * \param caps The current negotiated formats
505 *
506 * \note The new format capabilities structure has its refcount bumped and
507 * any existing format capabilities structure has its refcount decremented.
508 *
509 * \since 15
510 */
511void ast_stream_set_formats(struct ast_stream *stream, struct ast_format_cap *caps);
512
513/*!
514 * \brief Get the current state of a stream
515 *
516 * \param stream The media stream
517 *
518 * \return The state of the stream (AST_STREAM_STATE_UNKNOWN on error)
519 *
520 * \since 15
521 */
522enum ast_stream_state ast_stream_get_state(const struct ast_stream *stream);
523
524/*!
525 * \brief Set the state of a stream
526 *
527 * \param stream The media stream
528 * \param state The new state that the stream is in
529 *
530 * \note Used by stream creator to update internal state
531 *
532 * \since 15
533 */
534void ast_stream_set_state(struct ast_stream *stream, enum ast_stream_state state);
535
536/*!
537 * \brief Convert the state of a stream into a string
538 *
539 * \param state The stream state
540 *
541 * \return The state of the stream in string format
542 *
543 * \since 15
544 */
546
547/*!
548 * \brief Convert a string to a stream state
549 *
550 * \param str The string to convert
551 *
552 * \return The stream state
553 *
554 * \since 15.0.0
555 */
557
558/*!
559 * \brief Get a stream metadata value
560 *
561 * \param stream The media stream
562 * \param m_key An arbitrary metadata key
563 *
564 * \retval non-NULL metadata value
565 * \retval NULL failure or not found
566 *
567 * \since 15.5
568 */
569const char *ast_stream_get_metadata(const struct ast_stream *stream,
570 const char *m_key);
571
572/*!
573 * \brief Get all stream metadata keys
574 *
575 * \param stream The media stream
576 *
577 * \return An ast_variable list of the metadata key/value pairs.
578 * \retval NULL if error or no variables are set.
579 *
580 * When you're finished with the list, you must call
581 * ast_variables_destroy(list);
582 *
583 * \since 15.5
584 */
585struct ast_variable *ast_stream_get_metadata_list(const struct ast_stream *stream);
586
587/*!
588 * \brief Set a stream metadata value
589 *
590 * \param stream The media stream
591 * \param m_key An arbitrary metadata key
592 * \param value String metadata value or NULL to remove existing value
593 *
594 * \retval -1 failure
595 * \retval 0 success
596 *
597 * \since 15.5
598 */
599int ast_stream_set_metadata(struct ast_stream *stream, const char *m_key, const char *value);
600
601/*!
602 * \brief Get the position of the stream in the topology
603 *
604 * \param stream The media stream
605 *
606 * \return The position of the stream (-1 on error)
607 *
608 * \since 15
609 */
610int ast_stream_get_position(const struct ast_stream *stream);
611
612/*!
613 * \brief Get rtp_codecs associated with the stream
614 *
615 * \param stream The media stream
616 *
617 * \return The rtp_codecs
618 *
619 * \since 15.5
620 */
621struct ast_rtp_codecs *ast_stream_get_rtp_codecs(const struct ast_stream *stream);
622
623/*!
624 * \brief Set rtp_codecs associated with the stream
625 *
626 * \param stream The media stream
627 * \param rtp_codecs The rtp_codecs
628 *
629 * \since 15.5
630 */
631void ast_stream_set_rtp_codecs(struct ast_stream *stream, struct ast_rtp_codecs *rtp_codecs);
632
633/*!
634 * \brief Create a resolved stream from 2 streams
635 * \since 18
636 *
637 * \param pending_stream The "live" stream created from an SDP,
638 * passed through the core, or used to create an SDP.
639 * \param configured_stream The static stream used to validate the pending stream.
640 * \param prefs A pointer to an ast_stream_codec_negotiation_prefs structure.
641 * \param error_message If supplied, error messages will be appended.
642 *
643 * \details
644 * The resulting stream will contain all of the attributes and metadata of the
645 * pending stream but will contain only the formats that passed the validation
646 * specified by the ast_stream_codec_negotiation_prefs structure. This may mean
647 * that the stream's format_caps will be empty. It's up to the caller to determine
648 * what to do with the stream in that case. I.E. Free it, set it to the
649 * REMOVED state, etc. A stream will always be returned unless there was
650 * some catastrophic allocation failure.
651 *
652 * \retval NULL if there was some allocation failure.
653 * \return A new, resolved stream.
654 *
655 */
656struct ast_stream *ast_stream_create_resolved(struct ast_stream *pending_stream,
657 struct ast_stream *configured_stream, struct ast_stream_codec_negotiation_prefs *prefs,
658 struct ast_str **error_message);
659
660/*!
661 * \brief Create a stream topology
662 *
663 * \retval non-NULL success
664 * \retval NULL failure
665 *
666 * \since 15
667 *
668 * \note This returns an ao2 refcounted object
669 */
671
672/*!
673 * \brief Create a deep clone of an existing stream topology
674 *
675 * \param topology The existing topology of streams
676 *
677 * \retval non-NULL success
678 * \retval NULL failure
679 *
680 * \since 15
681 *
682 * \note This returns an ao2 refcounted object
683 */
685 const struct ast_stream_topology *topology);
686
687/*!
688 * \brief Compare two stream topologies to see if they are equal
689 *
690 * \param left The left topology
691 * \param right The right topology
692 *
693 * \retval 1 topologies are equivalent
694 * \retval 0 topologies differ
695 *
696 * \since 15
697 */
699 const struct ast_stream_topology *right);
700
701/*!
702 * \brief Unreference and destroy a stream topology
703 *
704 * \param topology The topology of streams
705 *
706 * \note All streams contained within the topology will be destroyed
707 *
708 * \since 15
709 */
710void ast_stream_topology_free(struct ast_stream_topology *topology);
711
712/*!
713 * \brief Append a stream to the topology
714 *
715 * \param topology The topology of streams
716 * \param stream The stream to append
717 *
718 * \return The position of the stream in the topology (-1 on error)
719 *
720 * \since 15
721 *
722 * \note If the stream's name is empty, it'll be set to <stream_type>-<position>
723 */
725 struct ast_stream *stream);
726
727/*!
728 * \brief Get the number of streams in a topology
729 *
730 * \param topology The topology of streams
731 *
732 * \return The number of streams (-1 on error)
733 *
734 * \since 15
735 */
736int ast_stream_topology_get_count(const struct ast_stream_topology *topology);
737
738/*!
739 * \brief Get the number of active (non-REMOVED) streams in a topology
740 *
741 * \param topology The topology of streams
742 *
743 * \return the number of active streams
744 *
745 * \since 18
746 */
748
749
750/*!
751 * \brief Get a specific stream from the topology
752 *
753 * \param topology The topology of streams
754 * \param position The topology position to get
755 *
756 * \retval non-NULL success
757 * \retval NULL failure
758 *
759 * \since 15
760 */
762 const struct ast_stream_topology *topology, unsigned int position);
763
764/*!
765 * \brief Set a specific position in a topology
766 *
767 * \param topology The topology of streams
768 * \param position The topology position to set
769 * \param stream The stream to put in its place
770 *
771 * \retval 0 success
772 * \retval -1 failure
773 *
774 * \note If an existing stream exists it will be destroyed
775 *
776 * \note You can overwrite an existing position in the topology or set
777 * the first unused position. You can't set positions beyond that.
778 *
779 * \since 15
780 *
781 * \note If the stream's name is empty, it'll be set to <stream_type>-<position>
782 */
784 unsigned int position, struct ast_stream *stream);
785
786/*!
787 * \brief Delete a specified stream from the given topology.
788 * \since 15.0.0
789 *
790 * \param topology The topology of streams.
791 * \param position The topology position to delete.
792 *
793 * \note Deleting a stream will completely remove it from the topology
794 * as if it never existed in it. i.e., Any following stream positions
795 * will shift down so there is no gap.
796 *
797 * \retval 0 on success.
798 * \retval -1 on failure.
799 */
801 unsigned int position);
802
803/*!
804 * \brief A helper function that, given a format capabilities structure,
805 * creates a topology and separates the media types in format_cap into
806 * separate streams.
807 *
808 * \param cap The format capabilities structure (NULL creates an empty topology)
809 *
810 * \retval non-NULL success
811 * \retval NULL failure
812 *
813 * \note The format capabilities reference is NOT altered by this function
814 * since a new format capabilities structure is created for each media type.
815 *
816 * \note Each stream will have its name set to the corresponding media type.
817 * For example: "audio".
818 *
819 * \note Each stream will be set to the sendrecv state.
820 *
821 * \since 15
822 */
824 struct ast_format_cap *cap);
825
826/*!
827 * \brief Create a format capabilities structure representing the topology.
828 *
829 * \details
830 * A helper function that, given a stream topology, creates a format
831 * capabilities structure containing all formats from all active streams.
832 *
833 * \param topology The topology of streams
834 *
835 * \retval non-NULL success (the resulting format caps must be unreffed by the caller)
836 * \retval NULL failure
837 *
838 * \note The stream topology is NOT altered by this function.
839 *
840 * \since 15
841 */
843 struct ast_stream_topology *topology);
844
845/*!
846 * \brief Get a string representing the topology for debugging/display purposes
847 * \since 18
848 *
849 * \param topology A stream topology
850 * \param buf A pointer to an ast_str* used for the output.
851 *
852 * \retval "" (empty string) if either buf or *buf are NULL
853 * \retval "(null topology)" if *topology was NULL
854 * \return <topology_representation> otherwise
855 *
856 * \warning No attempt should ever be made to free the returned
857 * char * and it should be dup'd if needed after the ast_str is freed.
858 *
859 * Return format:
860 * \verbatim <final>? <stream> ... \endverbatim
861 *
862 * Sample return:
863 * \verbatim "final <audio:audio:sendrecv (ulaw,g722)> <video:video:sendonly (h264)>" \endverbatim
864 *
865 */
866const char *ast_stream_topology_to_str(const struct ast_stream_topology *topology, struct ast_str **buf);
867
868/*!
869 * \brief Create a format capabilities structure containing all the formats from all the streams
870 * of a particular type in the topology.
871 * \since 18
872 *
873 * \details
874 * A helper function that, given a stream topology and a media type, creates a format
875 * capabilities structure containing all formats from all active streams with the particular type.
876 *
877 * \param topology The topology of streams
878 * \param type The media type
879 *
880 * \retval non-NULL success (the resulting format caps must be unreffed by the caller)
881 * \retval NULL failure
882 *
883 * \note The stream topology is NOT altered by this function.
884 *
885 */
887 struct ast_stream_topology *topology, enum ast_media_type type);
888
889/*!
890 * \brief Gets the first active stream of a specific type from the topology
891 *
892 * \param topology The topology of streams
893 * \param type The media type
894 *
895 * \retval non-NULL success
896 * \retval NULL failure
897 *
898 * \since 15
899 */
901 const struct ast_stream_topology *topology,
902 enum ast_media_type type);
903
904/*!
905 * \brief Map a given topology's streams to the given types.
906 *
907 * \note The given vectors in which mapping values are placed are reset by
908 * this function. This means if those vectors already contain mapping
909 * values they will be lost.
910 *
911 * \param topology The topology to map
912 * \param types The media types to be mapped
913 * \param v0 Index mapping of topology to types
914 * \param v1 Index mapping of types to topology
915 *
916 * \since 15
917 */
918void ast_stream_topology_map(const struct ast_stream_topology *topology,
919 struct ast_vector_int *types, struct ast_vector_int *v0, struct ast_vector_int *v1);
920
921/*!
922 * \brief Get the stream group that a stream is part of
923 *
924 * \param stream The stream
925 *
926 * \return the numerical stream group (-1 if not in a group)
927 *
928 * \since 15.2.0
929 */
930int ast_stream_get_group(const struct ast_stream *stream);
931
932/*!
933 * \brief Set the stream group for a stream
934 *
935 * \param stream The stream
936 * \param group The group the stream is part of
937 *
938 * \since 15.2.0
939 */
940void ast_stream_set_group(struct ast_stream *stream, int group);
941
942/*!
943 * \brief Create a resolved stream topology from 2 topologies
944 * \since 18
945 *
946 * \param pending_topology The "live" topology created from an SDP,
947 * passed through the core, or used to create an SDP.
948 * \param validation_topology The static topology used to validate the pending topology.
949 * It MUST have only 1 stream per media type.
950 * \param prefs A pointer to an ast_stream_codec_negotiation_prefs structure.
951 * \param error_message If supplied, error messages will be appended.
952 *
953 * \details
954 * The streams in the resolved topology will contain all of the attributes
955 * of the corresponding stream from the pending topology. It's format_caps
956 * however will contain only the formats that passed the validation
957 * specified by the ast_stream_codec_negotiation_prefs structure. This may
958 * mean that some of the streams format_caps will be empty. If that's the case,
959 * the stream will be in a REMOVED state. With those rules in mind,
960 * a resolved topology will always be returned (unless there's some catastrophic
961 * allocation failure) and the resolved topology is guaranteed to have the same
962 * number of streams, in the same order, as the pending topology.
963 *
964 * \retval NULL if there was some allocation failure.
965 * \return The joint topology.
966 */
968 struct ast_stream_topology *pending_topology, struct ast_stream_topology *validation_topology,
970 struct ast_str **error_message);
971
972/*!
973 * \brief Get a stack allocated string representing the topology for debugging/display purposes
974 *
975 * \param __topology A topology
976 *
977 * \return A stack allocated pointer to a string representing the topology.
978 *
979 * \warning No attempt should ever be made to free the returned
980 * char* as it is allocated from the stack.
981 *
982 */
983#define ast_stream_topology_to_stra(__topology) ast_str_tmp(256, ast_stream_topology_to_str(__topology, &STR_TMP))
984
985#endif /* _AST_STREAM_H */
const char * str
Definition: app_jack.c:147
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
static const char name[]
Definition: format_mp3.c:68
struct ast_stream_topology * ast_stream_topology_alloc(void)
Create a stream topology.
Definition: stream.c:650
struct ast_rtp_codecs * ast_stream_get_rtp_codecs(const struct ast_stream *stream)
Get rtp_codecs associated with the stream.
Definition: stream.c:507
void ast_stream_set_rtp_codecs(struct ast_stream *stream, struct ast_rtp_codecs *rtp_codecs)
Set rtp_codecs associated with the stream.
Definition: stream.c:514
const char * ast_stream_codec_negotiation_operation_map[CODEC_NEGOTIATION_OPERATION_END]
"operation" enum to string map
Definition: stream.c:61
const char * ast_stream_codec_negotiation_prefer_map[CODEC_NEGOTIATION_PREFER_END]
"prefer" enum to string map
Definition: stream.c:55
const char * ast_stream_to_str(const struct ast_stream *stream, struct ast_str **buf)
Get a string representing the stream for debugging/display purposes.
Definition: stream.c:337
struct ast_stream * ast_stream_alloc(const char *name, enum ast_media_type type)
Create a new media stream representation.
Definition: stream.c:233
int ast_stream_topology_set_stream(struct ast_stream_topology *topology, unsigned int position, struct ast_stream *stream)
Set a specific position in a topology.
Definition: stream.c:796
const char * ast_stream_get_metadata(const struct ast_stream *stream, const char *m_key)
Get a stream metadata value.
Definition: stream.c:423
struct ast_format_cap * ast_stream_topology_get_formats_by_type(struct ast_stream_topology *topology, enum ast_media_type type)
Create a format capabilities structure containing all the formats from all the streams of a particula...
Definition: stream.c:902
struct ast_stream_topology * ast_stream_topology_create_resolved(struct ast_stream_topology *pending_topology, struct ast_stream_topology *validation_topology, struct ast_stream_codec_negotiation_prefs *prefs, struct ast_str **error_message)
Create a resolved stream topology from 2 topologies.
Definition: stream.c:1030
const char * ast_stream_get_name(const struct ast_stream *stream)
Get the name of a stream.
Definition: stream.c:309
ast_stream_codec_negotiation_prefs_operation_values
The "operation" values.
Definition: stream.h:159
@ CODEC_NEGOTIATION_OPERATION_ONLY_PREFERRED
Definition: stream.h:166
@ CODEC_NEGOTIATION_OPERATION_UNSPECIFIED
Definition: stream.h:160
@ CODEC_NEGOTIATION_OPERATION_ONLY_NONPREFERRED
Definition: stream.h:168
@ CODEC_NEGOTIATION_OPERATION_UNION
Definition: stream.h:164
@ CODEC_NEGOTIATION_OPERATION_END
Definition: stream.h:170
@ CODEC_NEGOTIATION_OPERATION_INTERSECT
Definition: stream.h:162
int ast_stream_set_metadata(struct ast_stream *stream, const char *m_key, const char *value)
Set a stream metadata value.
Definition: stream.c:460
ast_stream_state
States that a stream may be in.
Definition: stream.h:74
@ AST_STREAM_STATE_RECVONLY
Set when the stream is receiving media only.
Definition: stream.h:90
@ AST_STREAM_STATE_END
Sentinel.
Definition: stream.h:98
@ AST_STREAM_STATE_INACTIVE
Set when the stream is not sending OR receiving media.
Definition: stream.h:94
@ AST_STREAM_STATE_REMOVED
Set when the stream has been removed/declined.
Definition: stream.h:78
@ AST_STREAM_STATE_SENDRECV
Set when the stream is sending and receiving media.
Definition: stream.h:82
@ AST_STREAM_STATE_SENDONLY
Set when the stream is sending media only.
Definition: stream.h:86
int ast_stream_get_position(const struct ast_stream *stream)
Get the position of the stream in the topology.
Definition: stream.c:500
const char * ast_stream_state2str(enum ast_stream_state state)
Convert the state of a stream into a string.
Definition: stream.c:388
void(* ast_stream_data_free_fn)(void *)
Definition: stream.h:69
void ast_stream_set_state(struct ast_stream *stream, enum ast_stream_state state)
Set the state of a stream.
Definition: stream.c:380
int ast_stream_topology_append_stream(struct ast_stream_topology *topology, struct ast_stream *stream)
Append a stream to the topology.
Definition: stream.c:748
const char * ast_stream_topology_to_str(const struct ast_stream_topology *topology, struct ast_str **buf)
Get a string representing the topology for debugging/display purposes.
Definition: stream.c:936
ast_stream_codec_negotiation_prefs_keep_values
The "keep" values.
Definition: stream.h:177
@ CODEC_NEGOTIATION_KEEP_FIRST
Definition: stream.h:182
@ CODEC_NEGOTIATION_KEEP_UNSPECIFIED
Definition: stream.h:178
@ CODEC_NEGOTIATION_KEEP_END
Definition: stream.h:184
@ CODEC_NEGOTIATION_KEEP_ALL
Definition: stream.h:180
struct ast_stream * ast_stream_clone(const struct ast_stream *stream, const char *name)
Create a deep clone of an existing stream.
Definition: stream.c:257
enum ast_stream_state ast_stream_str2state(const char *str)
Convert a string to a stream state.
Definition: stream.c:406
int ast_stream_codec_prefs_parse(const char *pref_string, struct ast_stream_codec_negotiation_prefs *prefs, struct ast_str **error_message)
Parses a string representing the codec prefs into a ast_stream_codec_negotiation_pref structure.
Definition: stream.c:181
struct ast_stream * ast_stream_topology_get_stream(const struct ast_stream_topology *topology, unsigned int position)
Get a specific stream from the topology.
Definition: stream.c:788
int ast_stream_topology_get_count(const struct ast_stream_topology *topology)
Get the number of streams in a topology.
Definition: stream.c:765
int ast_stream_get_format_count(const struct ast_stream *stream)
Get the count of the current negotiated formats of a stream.
Definition: stream.c:358
enum ast_stream_state ast_stream_get_state(const struct ast_stream *stream)
Get the current state of a stream.
Definition: stream.c:373
int ast_stream_topology_del_stream(struct ast_stream_topology *topology, unsigned int position)
Delete a specified stream from the given topology.
Definition: stream.c:825
int ast_stream_get_group(const struct ast_stream *stream)
Get the stream group that a stream is part of.
Definition: stream.c:1077
const char * ast_stream_codec_negotiation_transcode_map[CODEC_NEGOTIATION_TRANSCODE_END]
"transcode" state enum to string map
Definition: stream.c:75
enum ast_media_type ast_stream_get_type(const struct ast_stream *stream)
Get the media type of a stream.
Definition: stream.c:316
void ast_stream_topology_free(struct ast_stream_topology *topology)
Unreference and destroy a stream topology.
Definition: stream.c:743
const char * ast_stream_codec_negotiation_keep_map[CODEC_NEGOTIATION_KEEP_END]
"keep" enum to string map
Definition: stream.c:69
void ast_stream_set_formats(struct ast_stream *stream, struct ast_format_cap *caps)
Set the current negotiated formats of a stream.
Definition: stream.c:365
int ast_stream_topology_get_active_count(const struct ast_stream_topology *topology)
Get the number of active (non-REMOVED) streams in a topology.
Definition: stream.c:772
void ast_stream_set_type(struct ast_stream *stream, enum ast_media_type type)
Change the media type of a stream.
Definition: stream.c:323
const char * ast_stream_codec_prefs_to_str(const struct ast_stream_codec_negotiation_prefs *prefs, struct ast_str **buf)
Return a string representing the codec preferences.
Definition: stream.c:132
ast_stream_codec_negotiation_prefs_transcode_values
The "transcode" values.
Definition: stream.h:191
@ CODEC_NEGOTIATION_TRANSCODE_UNSPECIFIED
Definition: stream.h:192
@ CODEC_NEGOTIATION_TRANSCODE_END
Definition: stream.h:198
@ CODEC_NEGOTIATION_TRANSCODE_PREVENT
Definition: stream.h:196
@ CODEC_NEGOTIATION_TRANSCODE_ALLOW
Definition: stream.h:194
struct ast_stream_topology * ast_stream_topology_create_from_format_cap(struct ast_format_cap *cap)
A helper function that, given a format capabilities structure, creates a topology and separates the m...
Definition: stream.c:848
struct ast_variable * ast_stream_get_metadata_list(const struct ast_stream *stream)
Get all stream metadata keys.
Definition: stream.c:439
ast_stream_codec_negotiation_params
Advanced Codec Negotiation Preferences.
Definition: stream.h:127
@ CODEC_NEGOTIATION_PARAM_PREFER
Definition: stream.h:130
@ CODEC_NEGOTIATION_PARAM_TRANSCODE
Definition: stream.h:136
@ CODEC_NEGOTIATION_PARAM_KEEP
Definition: stream.h:134
@ CODEC_NEGOTIATION_PARAM_END
Definition: stream.h:138
@ CODEC_NEGOTIATION_PARAM_OPERATION
Definition: stream.h:132
@ CODEC_NEGOTIATION_PARAM_UNSPECIFIED
Definition: stream.h:128
const char * ast_stream_state_map[AST_STREAM_STATE_END]
Stream state enum to string map.
Definition: stream.c:223
struct ast_format_cap * ast_stream_topology_get_formats(struct ast_stream_topology *topology)
Create a format capabilities structure representing the topology.
Definition: stream.c:930
void ast_stream_free(struct ast_stream *stream)
Destroy a media stream representation.
Definition: stream.c:292
void ast_stream_set_group(struct ast_stream *stream, int group)
Set the stream group for a stream.
Definition: stream.c:1084
void ast_stream_topology_map(const struct ast_stream_topology *topology, struct ast_vector_int *types, struct ast_vector_int *v0, struct ast_vector_int *v1)
Map a given topology's streams to the given types.
Definition: stream.c:985
const struct ast_format_cap * ast_stream_get_formats(const struct ast_stream *stream)
Get the current negotiated formats of a stream.
Definition: stream.c:330
const char * ast_stream_codec_negotiation_params_map[CODEC_NEGOTIATION_PARAM_END]
Preference enum to string map.
Definition: stream.c:47
int ast_stream_topology_equal(const struct ast_stream_topology *left, const struct ast_stream_topology *right)
Compare two stream topologies to see if they are equal.
Definition: stream.c:696
struct ast_stream * ast_stream_create_resolved(struct ast_stream *pending_stream, struct ast_stream *configured_stream, struct ast_stream_codec_negotiation_prefs *prefs, struct ast_str **error_message)
Create a resolved stream from 2 streams.
Definition: stream.c:525
struct ast_stream_topology * ast_stream_topology_clone(const struct ast_stream_topology *topology)
Create a deep clone of an existing stream topology.
Definition: stream.c:667
ast_stream_codec_negotiation_prefs_prefer_values
The "prefer" values.
Definition: stream.h:145
@ CODEC_NEGOTIATION_PREFER_CONFIGURED
Definition: stream.h:150
@ CODEC_NEGOTIATION_PREFER_UNSPECIFIED
Definition: stream.h:146
@ CODEC_NEGOTIATION_PREFER_PENDING
Definition: stream.h:148
@ CODEC_NEGOTIATION_PREFER_END
Definition: stream.h:152
struct ast_stream * ast_stream_topology_get_first_stream_by_type(const struct ast_stream_topology *topology, enum ast_media_type type)
Gets the first active stream of a specific type from the topology.
Definition: stream.c:964
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
Support for dynamic strings.
Definition: strings.h:623
enum ast_stream_codec_negotiation_prefs_transcode_values transcode
Definition: stream.h:300
enum ast_stream_codec_negotiation_prefs_operation_values operation
Definition: stream.h:296
enum ast_stream_codec_negotiation_prefs_keep_values keep
Definition: stream.h:298
enum ast_stream_codec_negotiation_prefs_prefer_values prefer
Definition: stream.h:294
unsigned int position
The position of the stream in the topology.
Definition: stream.c:90
Structure for variables, used for configurations and for channel variables.
Integer vector definition.
Definition: vector.h:52
int value
Definition: syslog.c:37
Vector container support.