Asterisk - The Open Source Telephony Project  GIT-master-09303e8
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  */
52 struct ast_stream;
53 
54 /*!
55  * \brief Forward declaration for a format capability
56  */
57 struct ast_format_cap;
58 
59 /*!
60  * \brief The topology of a set of streams
61  */
62 struct ast_stream_topology;
63 
64 /*!
65  * \brief A mapping of two topologies.
66  */
68 
69 typedef 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  */
106 extern const char *ast_stream_state_map[AST_STREAM_STATE_END];
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  * \returns 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  * \returns 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_prefer_values
251  * \returns 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_operation_values
261  * \returns 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_keep_values
271  * \returns 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_transcode_values
281  * \returns 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  * \returns 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  */
359 int 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  */
377 struct 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  */
386 void 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 Optional name 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  */
402 struct 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  */
414 const 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  */
425 enum 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  */
435 void 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  */
449 const 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  * \retval <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  * <name>:<media_type>:<stream_state> (formats)
469  *
470  * Sample return:
471  * "audio:audio:sendrecv (ulaw,g722)"
472  *
473  */
474 const 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  * \returns 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  */
498 int 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  */
511 void 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  */
522 enum 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  */
534 void 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  */
556 enum ast_stream_state ast_stream_str2state(const char *str);
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  */
569 const 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  * \retval 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  */
585 struct 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  */
599 int 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  */
610 int 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  */
621 struct 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  */
631 void 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  * \retval A new, resolved stream.
654  *
655  */
656 struct 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  */
698 int ast_stream_topology_equal(const struct ast_stream_topology *left,
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  */
710 void 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  * \returns 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  */
736 int 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  *
800  * \return Nothing
801  */
803  unsigned int position);
804 
805 /*!
806  * \brief A helper function that, given a format capabilities structure,
807  * creates a topology and separates the media types in format_cap into
808  * separate streams.
809  *
810  * \param caps The format capabilities structure (NULL creates an empty topology)
811  *
812  * \retval non-NULL success
813  * \retval NULL failure
814  *
815  * \note The format capabilities reference is NOT altered by this function
816  * since a new format capabilities structure is created for each media type.
817  *
818  * \note Each stream will have its name set to the corresponding media type.
819  * For example: "audio".
820  *
821  * \note Each stream will be set to the sendrecv state.
822  *
823  * \since 15
824  */
826  struct ast_format_cap *cap);
827 
828 /*!
829  * \brief Create a format capabilities structure representing the topology.
830  *
831  * \details
832  * A helper function that, given a stream topology, creates a format
833  * capabilities structure containing all formats from all active streams.
834  *
835  * \param topology The topology of streams
836  *
837  * \retval non-NULL success (the resulting format caps must be unreffed by the caller)
838  * \retval NULL failure
839  *
840  * \note The stream topology is NOT altered by this function.
841  *
842  * \since 15
843  */
845  struct ast_stream_topology *topology);
846 
847 /*!
848  * \brief Get a string representing the topology for debugging/display purposes
849  * \since 18
850  *
851  * \param topology A stream topology
852  * \param buf A pointer to an ast_str* used for the output.
853  *
854  * \retval "" (empty string) if either buf or *buf are NULL
855  * \retval "(null topology)" if *topology was NULL
856  * \retval <topology_representation> otherwise
857  *
858  * \warning No attempt should ever be made to free the returned
859  * char * and it should be dup'd if needed after the ast_str is freed.
860  *
861  * Return format:
862  * <final>? <stream> ...
863  *
864  * Sample return:
865  * "final <audio:audio:sendrecv (ulaw,g722)> <video:video:sendonly (h264)>"
866  *
867  */
868 const char *ast_stream_topology_to_str(const struct ast_stream_topology *topology, struct ast_str **buf);
869 
870 /*!
871  * \brief Create a format capabilities structure containing all the formats from all the streams
872  * of a particular type in the topology.
873  * \since 18
874  *
875  * \details
876  * A helper function that, given a stream topology and a media type, creates a format
877  * capabilities structure containing all formats from all active streams with the particular type.
878  *
879  * \param topology The topology of streams
880  * \param type The media type
881  *
882  * \retval non-NULL success (the resulting format caps must be unreffed by the caller)
883  * \retval NULL failure
884  *
885  * \note The stream topology is NOT altered by this function.
886  *
887  */
889  struct ast_stream_topology *topology, enum ast_media_type type);
890 
891 /*!
892  * \brief Gets the first active stream of a specific type from the topology
893  *
894  * \param topology The topology of streams
895  * \param type The media type
896  *
897  * \retval non-NULL success
898  * \retval NULL failure
899  *
900  * \since 15
901  */
903  const struct ast_stream_topology *topology,
904  enum ast_media_type type);
905 
906 /*!
907  * \brief Map a given topology's streams to the given types.
908  *
909  * \note The given vectors in which mapping values are placed are reset by
910  * this function. This means if those vectors already contain mapping
911  * values they will be lost.
912  *
913  * \param topology The topology to map
914  * \param types The media types to be mapped
915  * \param v0 Index mapping of topology to types
916  * \param v1 Index mapping of types to topology
917  *
918  * \since 15
919  */
920 void ast_stream_topology_map(const struct ast_stream_topology *topology,
921  struct ast_vector_int *types, struct ast_vector_int *v0, struct ast_vector_int *v1);
922 
923 /*!
924  * \brief Get the stream group that a stream is part of
925  *
926  * \param stream The stream
927  *
928  * \return the numerical stream group (-1 if not in a group)
929  *
930  * \since 15.2.0
931  */
932 int ast_stream_get_group(const struct ast_stream *stream);
933 
934 /*!
935  * \brief Set the stream group for a stream
936  *
937  * \param stream The stream
938  * \param group The group the stream is part of
939  *
940  * \since 15.2.0
941  */
942 void ast_stream_set_group(struct ast_stream *stream, int group);
943 
944 /*!
945  * \brief Create a resolved stream topology from 2 topologies
946  * \since 18
947  *
948  * \param pending_topology The "live" topology created from an SDP,
949  * passed through the core, or used to create an SDP.
950  * \param configured_topology The static topology used to validate the pending topology.
951  * It MUST have only 1 stream per media type.
952  * \param prefs A pointer to an ast_stream_codec_negotiation_prefs structure.
953  * \param error_message If supplied, error messages will be appended.
954  *
955  * \details
956  * The streams in the resolved topology will contain all of the attributes
957  * of the corresponding stream from the pending topology. It's format_caps
958  * however will contain only the formats that passed the validation
959  * specified by the ast_stream_codec_negotiation_prefs structure. This may
960  * mean that some of the streams format_caps will be empty. If that's the case,
961  * the stream will be in a REMOVED state. With those rules in mind,
962  * a resolved topology will always be returned (unless there's some catastrophic
963  * allocation failure) and the resolved topology is guaranteed to have the same
964  * number of streams, in the same order, as the pending topology.
965  *
966  * \retval NULL if there was some allocation failure.
967  * \retval The joint topology.
968  */
970  struct ast_stream_topology *pending_topology, struct ast_stream_topology *validation_topology,
972  struct ast_str **error_message);
973 
974 /*!
975  * \brief Get a stack allocated string representing the topology for debugging/display purposes
976  *
977  * \param topology A topology
978  *
979  * \returns a stack allocated pointer to a string representing the topology.
980  *
981  * \warning No attempt should ever be made to free the returned
982  * char* as it is allocated from the stack.
983  *
984  */
985 #define ast_stream_topology_to_stra(__topology) ast_str_tmp(256, ast_stream_topology_to_str(__topology, &STR_TMP))
986 
987 #endif /* _AST_STREAM_H */
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
static const char type[]
Definition: chan_ooh323.c:109
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
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
int ast_stream_get_group(const struct ast_stream *stream)
Get the stream group that a stream is part of.
Definition: stream.c:1077
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
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
enum ast_media_type ast_stream_get_type(const struct ast_stream *stream)
Get the media type of a stream.
Definition: stream.c:316
enum ast_stream_codec_negotiation_prefs_operation_values operation
Definition: stream.h:296
Structure for variables, used for configurations and for channel variables.
Set when the stream has been removed/declined.
Definition: stream.h:78
Codec API.
enum ast_stream_codec_negotiation_prefs_prefer_values prefer
Definition: stream.h:294
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
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
Set when the stream is not sending OR receiving media.
Definition: stream.h:94
const char * str
Definition: app_jack.c:147
ast_stream_state
States that a stream may be in.
Definition: stream.h:74
const char * ast_stream_codec_negotiation_keep_map[CODEC_NEGOTIATION_KEEP_END]
"keep" enum to string map
Definition: stream.c:69
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_append_stream(struct ast_stream_topology *topology, struct ast_stream *stream)
Append a stream to the topology.
Definition: stream.c:748
int value
Definition: syslog.c:37
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_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
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_codec_negotiation_transcode_map[CODEC_NEGOTIATION_TRANSCODE_END]
"transcode" state enum to string map
Definition: stream.c:75
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
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
const char * ast_stream_codec_negotiation_operation_map[CODEC_NEGOTIATION_OPERATION_END]
"operation" enum to string map
Definition: stream.c:61
struct ast_variable * ast_stream_get_metadata_list(const struct ast_stream *stream)
Get all stream metadata keys.
Definition: stream.c:439
enum ast_stream_state ast_stream_str2state(const char *str)
Convert a string to a stream state.
Definition: stream.c:406
ast_stream_codec_negotiation_prefs_operation_values
The "operation" values.
Definition: stream.h:159
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
ast_stream_codec_negotiation_prefs_transcode_values
The "transcode" values.
Definition: stream.h:191
ast_stream_codec_negotiation_params
Advanced Codec Negotiation Preferences.
Definition: stream.h:127
enum ast_stream_codec_negotiation_prefs_keep_values keep
Definition: stream.h:298
void ast_stream_set_group(struct ast_stream *stream, int group)
Set the stream group for a stream.
Definition: stream.c:1084
Sentinel.
Definition: stream.h:98
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
Set when the stream is sending and receiving media.
Definition: stream.h:82
const char * ast_stream_codec_negotiation_prefer_map[CODEC_NEGOTIATION_PREFER_END]
"prefer" enum to string map
Definition: stream.c:55
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_state_map[AST_STREAM_STATE_END]
Stream state enum to string map.
Definition: stream.c:223
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
Format capabilities structure, holds formats + preference order + etc.
Definition: format_cap.c:54
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_topology * ast_stream_topology_alloc(void)
Create a stream topology.
Definition: stream.c:650
Set when the stream is sending media only.
Definition: stream.h:86
static const char name[]
Definition: cdr_mysql.c:74
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
void ast_stream_set_state(struct ast_stream *stream, enum ast_stream_state state)
Set the state of a stream.
Definition: stream.c:380
Vector container support.
int ast_stream_topology_get_count(const struct ast_stream_topology *topology)
Get the number of streams in a topology.
Definition: stream.c:765
void(* ast_stream_data_free_fn)(void *)
Definition: stream.h:69
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
void ast_stream_free(struct ast_stream *stream)
Destroy a media stream representation.
Definition: stream.c:292
struct ast_stream * ast_stream_alloc(const char *name, enum ast_media_type type)
Create a new media stream representation.
Definition: stream.c:233
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
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_codec_negotiation_prefs_transcode_values transcode
Definition: stream.h:300
const char * ast_stream_state2str(enum ast_stream_state state)
Convert the state of a stream into a string.
Definition: stream.c:388
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
const char * ast_stream_get_metadata(const struct ast_stream *stream, const char *m_key)
Get a stream metadata value.
Definition: stream.c:423
ast_stream_codec_negotiation_prefs_prefer_values
The "prefer" values.
Definition: stream.h:145
ast_media_type
Types of media.
Definition: codec.h:30
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&#39;s streams to the given types.
Definition: stream.c:985
void ast_stream_topology_free(struct ast_stream_topology *topology)
Unreference and destroy a stream topology.
Definition: stream.c:743
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_get_name(const struct ast_stream *stream)
Get the name of a stream.
Definition: stream.c:309
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
Set when the stream is receiving media only.
Definition: stream.h:90
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
enum ast_stream_state ast_stream_get_state(const struct ast_stream *stream)
Get the current state of a stream.
Definition: stream.c:373
unsigned int position
The position of the stream in the topology.
Definition: stream.c:90
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
const char * ast_stream_codec_negotiation_params_map[CODEC_NEGOTIATION_PARAM_END]
Preference enum to string map.
Definition: stream.c:47
ast_stream_codec_negotiation_prefs_keep_values
The "keep" values.
Definition: stream.h:177