stream.h File Reference

Media Stream API. More...

#include "asterisk/codec.h"
#include "asterisk/vector.h"

Include dependency graph for stream.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_stream_codec_negotiation_prefs

Macros
#define	_stream_maps_to_str(_mapname, _value)
	Internal macro to assist converting enums to strings. More...
#define	ast_stream_codec_keep_to_str(value)   _stream_maps_to_str(ast_stream_codec_negotiation_keep_map, value)
	Safely get the name of a "keep" parameter value. More...
#define	ast_stream_codec_operation_to_str(value)   _stream_maps_to_str(ast_stream_codec_negotiation_operation_map, value)
	Safely get the name of an "operation" parameter value. More...
#define	ast_stream_codec_param_to_str(value)   _stream_maps_to_str(ast_stream_codec_negotiation_params_map, value)
	Safely get the name of a preference parameter. More...
#define	ast_stream_codec_prefer_to_str(value)   _stream_maps_to_str(ast_stream_codec_negotiation_prefer_map, value)
	Safely get the name of a "prefer" parameter value. More...
#define	ast_stream_codec_transcode_to_str(value)   _stream_maps_to_str(ast_stream_codec_negotiation_transcode_map, value)
	Safely get the name of a "transcode" parameter value. More...
#define	AST_STREAM_MAX_CODEC_PREFS_LENGTH   (128)
	Define for allocating buffer space for to_str() functions. More...
#define	ast_stream_state_to_str(stream_state)   _stream_maps_to_str(ast_stream_state_map, stream_state)
	Safely get the name of a stream state. More...
#define	ast_stream_to_stra(__stream)   ast_str_tmp(128, ast_stream_to_str(__stream, &STR_TMP))
	Get a stack allocated string representing the stream for debugging/display purposes. More...
#define	ast_stream_topology_to_stra(__topology)   ast_str_tmp(256, ast_stream_topology_to_str(__topology, &STR_TMP))
	Get a stack allocated string representing the topology for debugging/display purposes. More...

Typedefs
typedef void(*	ast_stream_data_free_fn) (void *)

Enumerations
enum	ast_stream_codec_negotiation_params {   CODEC_NEGOTIATION_PARAM_UNSPECIFIED = 0, CODEC_NEGOTIATION_PARAM_PREFER, CODEC_NEGOTIATION_PARAM_OPERATION, CODEC_NEGOTIATION_PARAM_KEEP,   CODEC_NEGOTIATION_PARAM_TRANSCODE, CODEC_NEGOTIATION_PARAM_END }
	Advanced Codec Negotiation Preferences. More...
enum	ast_stream_codec_negotiation_prefs_keep_values { CODEC_NEGOTIATION_KEEP_UNSPECIFIED = 0, CODEC_NEGOTIATION_KEEP_ALL, CODEC_NEGOTIATION_KEEP_FIRST, CODEC_NEGOTIATION_KEEP_END }
	The "keep" values. More...
enum	ast_stream_codec_negotiation_prefs_operation_values {   CODEC_NEGOTIATION_OPERATION_UNSPECIFIED = 0, CODEC_NEGOTIATION_OPERATION_INTERSECT, CODEC_NEGOTIATION_OPERATION_UNION, CODEC_NEGOTIATION_OPERATION_ONLY_PREFERRED,   CODEC_NEGOTIATION_OPERATION_ONLY_NONPREFERRED, CODEC_NEGOTIATION_OPERATION_END }
	The "operation" values. More...
enum	ast_stream_codec_negotiation_prefs_prefer_values { CODEC_NEGOTIATION_PREFER_UNSPECIFIED = 0, CODEC_NEGOTIATION_PREFER_PENDING, CODEC_NEGOTIATION_PREFER_CONFIGURED, CODEC_NEGOTIATION_PREFER_END }
	The "prefer" values. More...
enum	ast_stream_codec_negotiation_prefs_transcode_values { CODEC_NEGOTIATION_TRANSCODE_UNSPECIFIED = 0, CODEC_NEGOTIATION_TRANSCODE_ALLOW, CODEC_NEGOTIATION_TRANSCODE_PREVENT, CODEC_NEGOTIATION_TRANSCODE_END }
	The "transcode" values. More...
enum	ast_stream_state {   AST_STREAM_STATE_REMOVED = 0, AST_STREAM_STATE_SENDRECV, AST_STREAM_STATE_SENDONLY, AST_STREAM_STATE_RECVONLY,   AST_STREAM_STATE_INACTIVE, AST_STREAM_STATE_END }
	States that a stream may be in. More...

Functions
struct ast_stream *	ast_stream_alloc (const char *name, enum ast_media_type type)
	Create a new media stream representation. More...
struct ast_stream *	ast_stream_clone (const struct ast_stream *stream, const char *name)
	Create a deep clone of an existing stream. More...
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. More...
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. More...
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. More...
void	ast_stream_free (struct ast_stream *stream)
	Destroy a media stream representation. More...
int	ast_stream_get_format_count (const struct ast_stream *stream)
	Get the count of the current negotiated formats of a stream. More...
const struct ast_format_cap *	ast_stream_get_formats (const struct ast_stream *stream)
	Get the current negotiated formats of a stream. More...
int	ast_stream_get_group (const struct ast_stream *stream)
	Get the stream group that a stream is part of. More...
const char *	ast_stream_get_metadata (const struct ast_stream *stream, const char *m_key)
	Get a stream metadata value. More...
struct ast_variable *	ast_stream_get_metadata_list (const struct ast_stream *stream)
	Get all stream metadata keys. More...
const char *	ast_stream_get_name (const struct ast_stream *stream)
	Get the name of a stream. More...
int	ast_stream_get_position (const struct ast_stream *stream)
	Get the position of the stream in the topology. More...
struct ast_rtp_codecs *	ast_stream_get_rtp_codecs (const struct ast_stream *stream)
	Get rtp_codecs associated with the stream. More...
enum ast_stream_state	ast_stream_get_state (const struct ast_stream *stream)
	Get the current state of a stream. More...
enum ast_media_type	ast_stream_get_type (const struct ast_stream *stream)
	Get the media type of a stream. More...
void	ast_stream_set_formats (struct ast_stream *stream, struct ast_format_cap *caps)
	Set the current negotiated formats of a stream. More...
void	ast_stream_set_group (struct ast_stream *stream, int group)
	Set the stream group for a stream. More...
int	ast_stream_set_metadata (struct ast_stream *stream, const char *m_key, const char *value)
	Set a stream metadata value. More...
void	ast_stream_set_rtp_codecs (struct ast_stream *stream, struct ast_rtp_codecs *rtp_codecs)
	Set rtp_codecs associated with the stream. More...
void	ast_stream_set_state (struct ast_stream *stream, enum ast_stream_state state)
	Set the state of a stream. More...
void	ast_stream_set_type (struct ast_stream *stream, enum ast_media_type type)
	Change the media type of a stream. More...
const char *	ast_stream_state2str (enum ast_stream_state state)
	Convert the state of a stream into a string. More...
enum ast_stream_state	ast_stream_str2state (const char *str)
	Convert a string to a stream state. More...
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. More...
struct ast_stream_topology *	ast_stream_topology_alloc (void)
	Create a stream topology. More...
int	ast_stream_topology_append_stream (struct ast_stream_topology *topology, struct ast_stream *stream)
	Append a stream to the topology. More...
struct ast_stream_topology *	ast_stream_topology_clone (const struct ast_stream_topology *topology)
	Create a deep clone of an existing stream topology. More...
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 media types in format_cap into separate streams. More...
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. More...
int	ast_stream_topology_del_stream (struct ast_stream_topology *topology, unsigned int position)
	Delete a specified stream from the given topology. More...
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. More...
void	ast_stream_topology_free (struct ast_stream_topology *topology)
	Unreference and destroy a stream topology. More...
int	ast_stream_topology_get_active_count (const struct ast_stream_topology *topology)
	Get the number of active (non-REMOVED) streams in a topology. More...
int	ast_stream_topology_get_count (const struct ast_stream_topology *topology)
	Get the number of streams in a topology. More...
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. More...
struct ast_format_cap *	ast_stream_topology_get_formats (struct ast_stream_topology *topology)
	Create a format capabilities structure representing the topology. More...
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 particular type in the topology. More...
struct ast_stream *	ast_stream_topology_get_stream (const struct ast_stream_topology *topology, unsigned int position)
	Get a specific stream from the topology. More...
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. More...
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. More...
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. More...

Variables
const char *	ast_stream_codec_negotiation_keep_map [CODEC_NEGOTIATION_KEEP_END]
	"keep" enum to string map More...
const char *	ast_stream_codec_negotiation_operation_map [CODEC_NEGOTIATION_OPERATION_END]
	"operation" enum to string map More...
const char *	ast_stream_codec_negotiation_params_map [CODEC_NEGOTIATION_PARAM_END]
	Preference enum to string map. More...
const char *	ast_stream_codec_negotiation_prefer_map [CODEC_NEGOTIATION_PREFER_END]
	"prefer" enum to string map More...
const char *	ast_stream_codec_negotiation_transcode_map [CODEC_NEGOTIATION_TRANSCODE_END]
	"transcode" state enum to string map More...
const char *	ast_stream_state_map [AST_STREAM_STATE_END]
	Stream state enum to string map. More...

Detailed Description

Media Stream API.

Author

Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file stream.h.

Macro Definition Documentation

_stream_maps_to_str

#define _stream_maps_to_str	(		_mapname,
			_value
	)

Internal macro to assist converting enums to strings.

Definition at line 40 of file stream.h.

ast_stream_codec_keep_to_str

#define ast_stream_codec_keep_to_str

(

value

)

_stream_maps_to_str(ast_stream_codec_negotiation_keep_map, value)

Safely get the name of a "keep" parameter value.

Since

18

Parameters

value

One of enum ast_stream_codec_negotiation_keep_values

Returns

A constant string with the name of the value or an empty string if an invalid value was passed in.

Definition at line 274 of file stream.h.

Referenced by ast_stream_codec_prefs_to_str().

ast_stream_codec_operation_to_str

#define ast_stream_codec_operation_to_str

(

value

)

_stream_maps_to_str(ast_stream_codec_negotiation_operation_map, value)

Safely get the name of an "operation" parameter value.

Since

18

Parameters

value

One of enum ast_stream_codec_negotiation_operation_values

Returns

A constant string with the name of the value or an empty string if an invalid value was passed in.

Definition at line 264 of file stream.h.

Referenced by ast_stream_codec_prefs_to_str(), and codec_prefs_handler().

ast_stream_codec_param_to_str

#define ast_stream_codec_param_to_str

(

value

)

_stream_maps_to_str(ast_stream_codec_negotiation_params_map, value)

Safely get the name of a preference parameter.

Since

18

Parameters

value

One of enum ast_stream_codec_negotiation_params

Returns

A constant string with the name of the preference or an empty string if an invalid value was passed in.

Definition at line 244 of file stream.h.

Referenced by ast_stream_codec_prefs_to_str(), and codec_prefs_handler().

ast_stream_codec_prefer_to_str

#define ast_stream_codec_prefer_to_str

(

value

)

_stream_maps_to_str(ast_stream_codec_negotiation_prefer_map, value)

Safely get the name of a "prefer" parameter value.

Since

18

Parameters

value

One of enum ast_stream_codec_negotiation_prefer_values

Returns

A constant string with the name of the value or an empty string if an invalid value was passed in.

Definition at line 254 of file stream.h.

Referenced by ast_stream_codec_prefs_to_str().

ast_stream_codec_transcode_to_str

#define ast_stream_codec_transcode_to_str

(

value

)

_stream_maps_to_str(ast_stream_codec_negotiation_transcode_map, value)

Safely get the name of a "transcode" parameter value.

Since

18

Parameters

value

One of enum ast_stream_codec_negotiation_transcode_values

Returns

A constant string with the name of the value or an empty string if an invalid value was passed in.

Definition at line 284 of file stream.h.

Referenced by ast_stream_codec_prefs_to_str().

AST_STREAM_MAX_CODEC_PREFS_LENGTH

#define AST_STREAM_MAX_CODEC_PREFS_LENGTH   (128)

Define for allocating buffer space for to_str() functions.

Since

18

Definition at line 307 of file stream.h.

Referenced by ast_stream_create_resolved(), and codec_prefs_to_str().

ast_stream_state_to_str

#define ast_stream_state_to_str

(

stream_state

)

_stream_maps_to_str(ast_stream_state_map, stream_state)

Safely get the name of a stream state.

Since

18

Parameters

stream_state

One of enum ast_stream_state

Returns

A constant string with the name of the state or an empty string if an invalid value was passed in.

Definition at line 116 of file stream.h.

ast_stream_to_stra

#define ast_stream_to_stra

(

__stream

)

ast_str_tmp(128, ast_stream_to_str(__stream, &STR_TMP))

Get a stack allocated string representing the stream for debugging/display purposes.

Parameters

stream

A stream

Returns

a stack allocated pointer to a string representing the stream.

Warning

No attempt should ever be made to free the returned char* as it is allocated from the stack.

Definition at line 487 of file stream.h.

ast_stream_topology_to_stra

#define ast_stream_topology_to_stra

(

__topology

)

ast_str_tmp(256, ast_stream_topology_to_str(__topology, &STR_TMP))

Get a stack allocated string representing the topology for debugging/display purposes.

Parameters

topology

A topology

Returns

a stack allocated pointer to a string representing the topology.

Warning

No attempt should ever be made to free the returned char* as it is allocated from the stack.

Definition at line 985 of file stream.h.

Typedef Documentation

ast_stream_data_free_fn

typedef void(* ast_stream_data_free_fn) (void *)

Definition at line 69 of file stream.h.

Enumeration Type Documentation

ast_stream_codec_negotiation_params

enum ast_stream_codec_negotiation_params

Advanced Codec Negotiation Preferences.

Since

18

The preference parameters themselves

Since

18

Enumerator
CODEC_NEGOTIATION_PARAM_UNSPECIFIED
CODEC_NEGOTIATION_PARAM_PREFER	Which of the lists to "prefer"
CODEC_NEGOTIATION_PARAM_OPERATION	"operation" to perform
CODEC_NEGOTIATION_PARAM_KEEP	"keep" all or only first
CODEC_NEGOTIATION_PARAM_TRANSCODE	Allow or prevent "transcode"
CODEC_NEGOTIATION_PARAM_END	Sentinel

Definition at line 127 of file stream.h.

                                         {
   CODEC_NEGOTIATION_PARAM_UNSPECIFIED = 0,
   /*! Which of the lists to "prefer" */
   CODEC_NEGOTIATION_PARAM_PREFER,
   /*! "operation" to perform */
   CODEC_NEGOTIATION_PARAM_OPERATION,
   /*! "keep" all or only first */
   CODEC_NEGOTIATION_PARAM_KEEP,
   /*! Allow or prevent "transcode" */
   CODEC_NEGOTIATION_PARAM_TRANSCODE,
   /*! Sentinel */
   CODEC_NEGOTIATION_PARAM_END,
};

ast_stream_codec_negotiation_prefs_keep_values

enum ast_stream_codec_negotiation_prefs_keep_values

The "keep" values.

Since

18

Enumerator
CODEC_NEGOTIATION_KEEP_UNSPECIFIED
CODEC_NEGOTIATION_KEEP_ALL	"keep" all codecs after performing the operation
CODEC_NEGOTIATION_KEEP_FIRST	"keep" only the first codec after performing the operation
CODEC_NEGOTIATION_KEEP_END	Sentinel

Definition at line 177 of file stream.h.

                                                    {
   CODEC_NEGOTIATION_KEEP_UNSPECIFIED = 0,
   /*! "keep" all codecs after performing the operation */
   CODEC_NEGOTIATION_KEEP_ALL,
   /*! "keep" only the first codec after performing the operation */
   CODEC_NEGOTIATION_KEEP_FIRST,
   /*! Sentinel */
   CODEC_NEGOTIATION_KEEP_END,
};

ast_stream_codec_negotiation_prefs_operation_values

enum ast_stream_codec_negotiation_prefs_operation_values

The "operation" values.

Since

18

Enumerator
CODEC_NEGOTIATION_OPERATION_UNSPECIFIED
CODEC_NEGOTIATION_OPERATION_INTERSECT	"intersect": only those codecs that appear in both lists
CODEC_NEGOTIATION_OPERATION_UNION	"union": all codecs in both lists
CODEC_NEGOTIATION_OPERATION_ONLY_PREFERRED	"only_preferred": only the codecs in the preferred list
CODEC_NEGOTIATION_OPERATION_ONLY_NONPREFERRED	"only_nonpreferred": only the codecs in the non-preferred list
CODEC_NEGOTIATION_OPERATION_END	Sentinel

Definition at line 159 of file stream.h.

                                                         {
   CODEC_NEGOTIATION_OPERATION_UNSPECIFIED = 0,
   /*! "intersect": only those codecs that appear in both lists */
   CODEC_NEGOTIATION_OPERATION_INTERSECT,
   /*! "union": all codecs in both lists */
   CODEC_NEGOTIATION_OPERATION_UNION,
   /*! "only_preferred": only the codecs in the preferred list */
   CODEC_NEGOTIATION_OPERATION_ONLY_PREFERRED,
   /*! "only_nonpreferred": only the codecs in the non-preferred list */
   CODEC_NEGOTIATION_OPERATION_ONLY_NONPREFERRED,
   /*! Sentinel */
   CODEC_NEGOTIATION_OPERATION_END,
};

ast_stream_codec_negotiation_prefs_prefer_values

enum ast_stream_codec_negotiation_prefs_prefer_values

The "prefer" values.

Since

18

Enumerator
CODEC_NEGOTIATION_PREFER_UNSPECIFIED
CODEC_NEGOTIATION_PREFER_PENDING	Prefer the "pending" list
CODEC_NEGOTIATION_PREFER_CONFIGURED	Prefer the "configured" list
CODEC_NEGOTIATION_PREFER_END	Sentinel

Definition at line 145 of file stream.h.

                                                      {
   CODEC_NEGOTIATION_PREFER_UNSPECIFIED = 0,
   /*! Prefer the "pending" list */
   CODEC_NEGOTIATION_PREFER_PENDING,
   /*! Prefer the "configured" list */
   CODEC_NEGOTIATION_PREFER_CONFIGURED,
   /*! Sentinel */
   CODEC_NEGOTIATION_PREFER_END,
};

ast_stream_codec_negotiation_prefs_transcode_values

enum ast_stream_codec_negotiation_prefs_transcode_values

The "transcode" values.

Since

18

Enumerator
CODEC_NEGOTIATION_TRANSCODE_UNSPECIFIED
CODEC_NEGOTIATION_TRANSCODE_ALLOW	"allow" transcoding
CODEC_NEGOTIATION_TRANSCODE_PREVENT	"prevent" transcoding
CODEC_NEGOTIATION_TRANSCODE_END	Sentinel

Definition at line 191 of file stream.h.

                                                         {
   CODEC_NEGOTIATION_TRANSCODE_UNSPECIFIED = 0,
   /*! "allow" transcoding */
   CODEC_NEGOTIATION_TRANSCODE_ALLOW,
   /*! "prevent" transcoding */
   CODEC_NEGOTIATION_TRANSCODE_PREVENT,
   /*! Sentinel */
   CODEC_NEGOTIATION_TRANSCODE_END,
};

ast_stream_state

enum ast_stream_state

States that a stream may be in.

Enumerator
AST_STREAM_STATE_REMOVED	Set when the stream has been removed/declined.
AST_STREAM_STATE_SENDRECV	Set when the stream is sending and receiving media.
AST_STREAM_STATE_SENDONLY	Set when the stream is sending media only.
AST_STREAM_STATE_RECVONLY	Set when the stream is receiving media only.
AST_STREAM_STATE_INACTIVE	Set when the stream is not sending OR receiving media.
AST_STREAM_STATE_END	Sentinel.

Definition at line 74 of file stream.h.

                      {
   /*!
    * \brief Set when the stream has been removed/declined
    */
   AST_STREAM_STATE_REMOVED = 0,
   /*!
    * \brief Set when the stream is sending and receiving media
    */
   AST_STREAM_STATE_SENDRECV,
   /*!
    * \brief Set when the stream is sending media only
    */
   AST_STREAM_STATE_SENDONLY,
   /*!
    * \brief Set when the stream is receiving media only
    */
   AST_STREAM_STATE_RECVONLY,
   /*!
    * \brief Set when the stream is not sending OR receiving media
    */
   AST_STREAM_STATE_INACTIVE,
   /*!
    * \brief Sentinel
    */
   AST_STREAM_STATE_END
};

Function Documentation

ast_stream_alloc()

struct ast_stream* ast_stream_alloc	(	const char *	name,
		enum ast_media_type	type
	)

Create a new media stream representation.

Parameters

name	A name for the stream
type	The media type the stream is handling

Return values

non-NULL	success
NULL	failure

Note

This is NOT an AO2 object and has no locking. It is expected that a higher level object provides protection.

The stream will default to an inactive state until changed.

Since

15

Definition at line 233 of file stream.c.

References ast_calloc, ast_format_cap_alloc, AST_FORMAT_CAP_FLAG_DEFAULT, ast_free, AST_STREAM_STATE_INACTIVE, ast_stream::formats, ast_stream::group, MAX, MIN_STREAM_NAME_LEN, ast_stream::name, NULL, S_OR, ast_stream::state, ast_stream::type, and type.

Referenced by ast_stream_topology_create_from_format_cap(), AST_TEST_DEFINE(), ast_unreal_indicate(), build_topology(), handle_incoming_sdp(), make_channel(), sdp_requires_deferral(), t38_create_media_state(), and test_stream_alloc().

{
   struct ast_stream *stream;
   size_t name_len = MAX(strlen(S_OR(name, "")), MIN_STREAM_NAME_LEN); /* Ensure there is enough room for 'removed' or a type-position */

   stream = ast_calloc(1, sizeof(*stream) + name_len + 1);
   if (!stream) {
      return NULL;
   }

   stream->type = type;
   stream->state = AST_STREAM_STATE_INACTIVE;
   stream->group = -1;
   strcpy(stream->name, S_OR(name, "")); /* Safe */

   stream->formats = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
   if (!stream->formats) {
      ast_free(stream);
      return NULL;
   }

   return stream;
}

ast_stream_clone()

struct ast_stream* ast_stream_clone	(	const struct ast_stream *	stream,
		const char *	name
	)

Create a deep clone of an existing stream.

Parameters

stream	The existing stream
Optional	name for cloned stream. If NULL, then existing stream's name is copied.

Return values

non-NULL	success
NULL	failure

Note

Opaque data pointers set with ast_stream_set_data() are not part of the deep clone. We have no way to clone the data.

Since

15

Definition at line 257 of file stream.c.

References ast_calloc, ast_format_cap_alloc, ast_format_cap_append_from_cap(), AST_FORMAT_CAP_FLAG_DEFAULT, ast_free, AST_MEDIA_TYPE_UNKNOWN, ast_stream_get_metadata_list(), ast_stream::formats, ast_stream::group, MAX, ast_stream::metadata, MIN_STREAM_NAME_LEN, ast_stream::name, NULL, and S_OR.

Referenced by append_all_streams(), append_source_stream(), ast_sip_session_create_joint_call_stream(), ast_stream_create_resolved(), ast_stream_topology_clone(), ast_stream_topology_create_resolved(), remove_all_original_streams(), resolve_refresh_media_states(), sip_session_refresh(), and stream_echo_topology_alloc().

{
   struct ast_stream *new_stream;
   const char *stream_name;
   size_t name_len;

   if (!stream) {
      return NULL;
   }

   stream_name = name ?: stream->name;
   name_len = MAX(strlen(S_OR(stream_name, "")), MIN_STREAM_NAME_LEN); /* Ensure there is enough room for 'removed' or a type-position */
   new_stream = ast_calloc(1, sizeof(*stream) + name_len + 1);
   if (!new_stream) {
      return NULL;
   }

   memcpy(new_stream, stream, sizeof(*new_stream));
   strcpy(new_stream->name, stream_name); /* Safe */
   new_stream->group = -1;

   new_stream->formats = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
   if (!new_stream->formats) {
      ast_free(new_stream);
      return NULL;
   }
   ast_format_cap_append_from_cap(new_stream->formats, stream->formats, AST_MEDIA_TYPE_UNKNOWN);

   new_stream->metadata = ast_stream_get_metadata_list(stream);

   /* rtp_codecs aren't cloned */

   return new_stream;
}

ast_stream_codec_prefs_parse()

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.

Since

18

This function is mainly used by pjsip_configuration as a sorcery parameter handler.

Parameters

pref_string	A string in the format described by ast_stream_codec_prefs_to_str().
prefs	Pointer to a ast_stream_codec_negotiation_prefs structure to receive the parsed values.
error_message	An optional ast_str** into which parsing errors will be placed.

Return values

0	if success
-1	if failed

Whitespace around the ':' and ',' separators is ignored and the parameters can be specified in any order. Parameters missing in the input string will have their values set to the appropriate *_UNSPECIFIED value and will not be considered an error. It's up to the caller to decide whether set a default value, return an error, etc.

Sample input: "prefer : configured , operation: union,keep:all, transcode:prevent"

Definition at line 181 of file stream.c.

References ast_str_append(), ast_strdupa, CODEC_NEGOTIATION_KEEP_UNSPECIFIED, CODEC_NEGOTIATION_OPERATION_UNSPECIFIED, CODEC_NEGOTIATION_PREFER_UNSPECIFIED, CODEC_NEGOTIATION_TRANSCODE_UNSPECIFIED, ast_stream_codec_negotiation_prefs::keep, name, NULL, ast_stream_codec_negotiation_prefs::operation, ast_stream_codec_negotiation_prefs::prefer, set_pref_value, ast_stream_codec_negotiation_prefs::transcode, and value.

Referenced by codec_prefs_handler().

{
   char *initial_value = ast_strdupa(pref_string);
   char *current_value;
   char *pref;
   char *saveptr1;
   char *saveptr2;
   char *name;
   char *value;

   if (!prefs) {
      return -1;
   }

   prefs->prefer = CODEC_NEGOTIATION_PREFER_UNSPECIFIED;
   prefs->operation = CODEC_NEGOTIATION_OPERATION_UNSPECIFIED;
   prefs->keep = CODEC_NEGOTIATION_KEEP_UNSPECIFIED;
   prefs->transcode = CODEC_NEGOTIATION_TRANSCODE_UNSPECIFIED;

   for (current_value = initial_value; (pref = strtok_r(current_value, ",", &saveptr1)) != NULL; ) {
      name = strtok_r(pref, ": ", &saveptr2);
      value = strtok_r(NULL, ": ", &saveptr2);

      if (!name || !value) {
         if (error_message) {
            ast_str_append(error_message, 0, "Codec preference '%s' is invalid", pref);
         }
         return -1;
      }

      set_pref_value(name, value, prefs, OPERATION, operation, error_message);
      set_pref_value(name, value, prefs, PREFER, prefer, error_message);
      set_pref_value(name, value, prefs, KEEP, keep, error_message);
      set_pref_value(name, value, prefs, TRANSCODE, transcode, error_message);

      current_value = NULL;
   }

   return 0;
}

ast_stream_codec_prefs_to_str()

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.

Since

18

This function can be used for debugging purposes but is also used in pjsip_configuration as a sorcery parameter handler

Parameters

prefs	A pointer to a ast_stream_codec_negotiation_prefs structure
buf	A pointer to an ast_str* used for the output. See note below.

Returns

the contents of the ast_str as a const char *.

Warning

No attempt should ever be made to free the returned char * and it should be dup'd if needed after the ast_str is freed.

Note

buf can't be NULL but it CAN contain a NULL value. If so, a new ast_str will be allocated and the value of buf updated with a pointer to it. Whether the caller supplies the ast_str or it's allocated by this function, it's the caller's responsibility to free it.

Sample output: "prefer: configured, operation: union, keep:all, transcode:prevent"

Definition at line 132 of file stream.c.

References ast_str_append(), ast_str_buffer(), ast_stream_codec_keep_to_str, ast_stream_codec_operation_to_str, ast_stream_codec_param_to_str, ast_stream_codec_prefer_to_str, ast_stream_codec_transcode_to_str, CODEC_NEGOTIATION_PARAM_KEEP, CODEC_NEGOTIATION_PARAM_OPERATION, CODEC_NEGOTIATION_PARAM_PREFER, CODEC_NEGOTIATION_PARAM_TRANSCODE, ast_stream_codec_negotiation_prefs::keep, ast_stream_codec_negotiation_prefs::operation, ast_stream_codec_negotiation_prefs::prefer, and ast_stream_codec_negotiation_prefs::transcode.

Referenced by ast_stream_create_resolved(), and codec_prefs_to_str().

{
   if (!prefs || !buf || !*buf) {
      return "";
   }

   ast_str_append(buf, 0, "%s:%s, %s:%s, %s:%s, %s:%s",
      ast_stream_codec_param_to_str(CODEC_NEGOTIATION_PARAM_PREFER),
      ast_stream_codec_prefer_to_str(prefs->prefer),
      ast_stream_codec_param_to_str(CODEC_NEGOTIATION_PARAM_OPERATION),
      ast_stream_codec_operation_to_str(prefs->operation),
      ast_stream_codec_param_to_str(CODEC_NEGOTIATION_PARAM_KEEP),
      ast_stream_codec_keep_to_str(prefs->keep),
      ast_stream_codec_param_to_str(CODEC_NEGOTIATION_PARAM_TRANSCODE),
      ast_stream_codec_transcode_to_str(prefs->transcode)
      );

   return ast_str_buffer(*buf);
}

ast_stream_create_resolved()

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.

Since

18

Parameters

pending_stream	The "live" stream created from an SDP, passed through the core, or used to create an SDP.
configured_stream	The static stream used to validate the pending stream.
prefs	A pointer to an ast_stream_codec_negotiation_prefs structure.
error_message	If supplied, error messages will be appended.

The resulting stream will contain all of the attributes and metadata of the pending stream but will contain only the formats that passed the validation specified by the ast_stream_codec_negotiation_prefs structure. This may mean that the stream's format_caps will be empty. It's up to the caller to determine what to do with the stream in that case. I.E. Free it, set it to the REMOVED state, etc. A stream will always be returned unless there was some catastrophic allocation failure.

Return values

NULL	if there was some allocation failure.
A	new, resolved stream.

Definition at line 525 of file stream.c.

References ao2_cleanup, ao2_ref, ast_codec_media_type2str(), ast_format_cap_alloc, ast_format_cap_append, ast_format_cap_append_from_cap(), ast_format_cap_append_names(), ast_format_cap_empty(), AST_FORMAT_CAP_FLAG_DEFAULT, ast_format_cap_get_compatible(), ast_format_cap_get_format(), ast_format_cap_get_framing(), AST_FORMAT_CAP_NAMES_LEN, ast_format_cap_remove_by_type(), ast_format_cap_set_framing(), ast_free, AST_MEDIA_TYPE_UNKNOWN, ast_str_append(), ast_str_buffer(), ast_str_create, ast_str_set(), ast_str_tmp, ast_stream_clone(), ast_stream_codec_prefs_to_str(), AST_STREAM_MAX_CODEC_PREFS_LENGTH, ast_stream_set_formats(), ast_stream_to_str(), ast_trace, buf, CODEC_NEGOTIATION_KEEP_FIRST, CODEC_NEGOTIATION_OPERATION_INTERSECT, CODEC_NEGOTIATION_OPERATION_ONLY_NONPREFERRED, CODEC_NEGOTIATION_OPERATION_ONLY_PREFERRED, CODEC_NEGOTIATION_OPERATION_UNION, CODEC_NEGOTIATION_PREFER_PENDING, ast_stream::formats, ast_stream_codec_negotiation_prefs::keep, NULL, ast_stream_codec_negotiation_prefs::operation, ast_stream_codec_negotiation_prefs::prefer, SCOPE_ENTER, SCOPE_EXIT_RTN_VALUE, TRACE_ATLEAST, and ast_stream::type.

Referenced by ast_stream_topology_create_resolved().

{
   struct ast_format_cap *preferred_caps = NULL;
   struct ast_format_cap *nonpreferred_caps = NULL;
   struct ast_format_cap *joint_caps = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
   struct ast_stream *joint_stream;
   enum ast_media_type media_type = pending_stream ? pending_stream->type : AST_MEDIA_TYPE_UNKNOWN;
   int res = 0;
   SCOPE_ENTER(4, "Pending: %s  Validation: %s  Prefs: %s\n",
      ast_str_tmp(128, ast_stream_to_str(pending_stream, &STR_TMP)),
      ast_str_tmp(128, ast_stream_to_str(validation_stream, &STR_TMP)),
      ast_str_tmp(128, ast_stream_codec_prefs_to_str(prefs, &STR_TMP)));

   if (!pending_stream || !validation_stream || !prefs || !joint_caps
      || media_type == AST_MEDIA_TYPE_UNKNOWN) {
      if (error_message) {
         ast_str_append(error_message, 0, "Invalid arguments");
      }
      ao2_cleanup(joint_caps);
      SCOPE_EXIT_RTN_VALUE(NULL, "Invalid arguments\n");
   }

   if (prefs->prefer == CODEC_NEGOTIATION_PREFER_PENDING) {
      preferred_caps = pending_stream->formats;
      nonpreferred_caps = validation_stream->formats;
   } else {
      preferred_caps = validation_stream->formats;
      nonpreferred_caps = pending_stream->formats;
   }
   ast_format_cap_set_framing(joint_caps, ast_format_cap_get_framing(pending_stream->formats));

   switch(prefs->operation) {
   case CODEC_NEGOTIATION_OPERATION_ONLY_PREFERRED:
      res = ast_format_cap_append_from_cap(joint_caps, preferred_caps, media_type);
      break;
   case CODEC_NEGOTIATION_OPERATION_ONLY_NONPREFERRED:
      res = ast_format_cap_append_from_cap(joint_caps, nonpreferred_caps, media_type);
      break;
   case CODEC_NEGOTIATION_OPERATION_INTERSECT:
      res = ast_format_cap_get_compatible(preferred_caps, nonpreferred_caps, joint_caps);
      break;
   case CODEC_NEGOTIATION_OPERATION_UNION:
      res = ast_format_cap_append_from_cap(joint_caps, preferred_caps, media_type);
      if (res == 0) {
         res = ast_format_cap_append_from_cap(joint_caps, nonpreferred_caps, media_type);
      }
      break;
   default:
      break;
   }

   if (res) {
      if (error_message) {
         ast_str_append(error_message, 0, "No common formats available for media type '%s' ",
            ast_codec_media_type2str(pending_stream->type));
         ast_format_cap_append_names(preferred_caps, error_message);
         ast_str_append(error_message, 0, "<>");
         ast_format_cap_append_names(nonpreferred_caps, error_message);
         ast_str_append(error_message, 0, " with prefs: ");
         ast_stream_codec_prefs_to_str(prefs, error_message);
      }

      ao2_cleanup(joint_caps);
      SCOPE_EXIT_RTN_VALUE(NULL, "No common formats available\n");
   }

   if (!ast_format_cap_empty(joint_caps)) {
      if (prefs->keep == CODEC_NEGOTIATION_KEEP_FIRST) {
         struct ast_format *single = ast_format_cap_get_format(joint_caps, 0);
         ast_format_cap_remove_by_type(joint_caps, AST_MEDIA_TYPE_UNKNOWN);
         ast_format_cap_append(joint_caps, single, 0);
         ao2_ref(single, -1);
      }
   } else {
      if (error_message) {
         ast_str_append(error_message, 0, "No common formats available for media type '%s' ",
            ast_codec_media_type2str(pending_stream->type));
         ast_format_cap_append_names(preferred_caps, error_message);
         ast_str_append(error_message, 0, "<>");
         ast_format_cap_append_names(nonpreferred_caps, error_message);
         ast_str_append(error_message, 0, " with prefs: ");
         ast_stream_codec_prefs_to_str(prefs, error_message);
      }
   }

   joint_stream = ast_stream_clone(pending_stream, NULL);
   if (!joint_stream) {
      ao2_cleanup(joint_caps);
      return NULL;
   }

   /* ref to joint_caps will be transferred to the stream */
   ast_stream_set_formats(joint_stream, joint_caps);

   if (TRACE_ATLEAST(3)) {
      struct ast_str *buf = ast_str_create((AST_FORMAT_CAP_NAMES_LEN * 3) + AST_STREAM_MAX_CODEC_PREFS_LENGTH);
      if (buf) {
         ast_str_set(&buf, 0, "Resolved '%s' stream ", ast_codec_media_type2str(pending_stream->type));
         ast_format_cap_append_names(preferred_caps, &buf);
         ast_str_append(&buf, 0, "<>");
         ast_format_cap_append_names(nonpreferred_caps, &buf);
         ast_str_append(&buf, 0, " to ");
         ast_format_cap_append_names(joint_caps, &buf);
         ast_str_append(&buf, 0, " with prefs: ");
         ast_stream_codec_prefs_to_str(prefs, &buf);
         ast_trace(1, "%s\n", ast_str_buffer(buf));
         ast_free(buf);
      }
   }

   ao2_cleanup(joint_caps);
   SCOPE_EXIT_RTN_VALUE(joint_stream, "Joint stream: %s\n", ast_str_tmp(128, ast_stream_to_str(joint_stream, &STR_TMP)));
}

ast_stream_free()

void ast_stream_free

(

struct ast_stream *

stream

)

Destroy a media stream representation.

Parameters

stream

The media stream

Since

15

Definition at line 292 of file stream.c.

References ao2_cleanup, ast_free, ast_rtp_codecs_payloads_destroy(), ast_variables_destroy(), ast_stream::formats, ast_stream::metadata, and ast_stream::rtp_codecs.

Referenced by append_all_streams(), append_source_stream(), ast_sip_session_create_outgoing(), ast_stream_topology_clone(), ast_stream_topology_create_from_format_cap(), ast_stream_topology_create_resolved(), ast_stream_topology_del_stream(), ast_stream_topology_set_stream(), AST_TEST_DEFINE(), build_topology(), handle_incoming_sdp(), remove_all_original_streams(), sdp_requires_deferral(), sip_session_refresh(), stream_echo_topology_alloc(), stream_topology_destroy(), and t38_create_media_state().

{
   if (!stream) {
      return;
   }

   ast_variables_destroy(stream->metadata);

   if (stream->rtp_codecs) {
      ast_rtp_codecs_payloads_destroy(stream->rtp_codecs);
   }

   ao2_cleanup(stream->formats);

   ast_free(stream);
}

ast_stream_get_format_count()

int ast_stream_get_format_count

(

const struct ast_stream *

stream

)

Get the count of the current negotiated formats of a stream.

Parameters

stream

The media stream

Returns

The count of negotiated formats

Since

18

Definition at line 358 of file stream.c.

References ast_assert, ast_format_cap_count(), ast_stream::formats, and NULL.

Referenced by ast_sip_session_create_outgoing(), and ast_stream_topology_create_resolved().

{
   ast_assert(stream != NULL);

   return stream->formats ? ast_format_cap_count(stream->formats) : 0;
}

ast_stream_get_formats()

const struct ast_format_cap* ast_stream_get_formats

(

const struct ast_stream *

stream

)

Get the current negotiated formats of a stream.

Parameters

stream

The media stream

Return values

non-NULL	success
NULL	failure

Note

The reference count is not increased

Since

15

Definition at line 330 of file stream.c.

References ast_assert, ast_stream::formats, and NULL.

Referenced by ast_sip_session_create_joint_call_stream(), ast_stream_topology_equal(), AST_TEST_DEFINE(), create_outgoing_sdp_stream(), handle_showchan(), is_compatible_format(), local_request_with_stream_topology(), media_offer_read_av(), media_offer_write_av(), native_rtp_request_stream_topology_update(), simple_bridge_request_stream_topology_update(), sip_session_refresh(), and validate_stream().

{
   ast_assert(stream != NULL);

   return stream->formats;
}

ast_stream_get_group()

int ast_stream_get_group

(

const struct ast_stream *

stream

)

Get the stream group that a stream is part of.

Parameters

stream

The stream

Returns

the numerical stream group (-1 if not in a group)

Since

15.2.0

Definition at line 1077 of file stream.c.

References ast_assert, ast_stream::group, and NULL.

Referenced by add_msid_to_stream(), ast_stream_topology_clone(), and handle_showchan().

{
   ast_assert(stream != NULL);

   return stream->group;
}

ast_stream_get_metadata()

const char* ast_stream_get_metadata	(	const struct ast_stream *	stream,
		const char *	m_key
	)

Get a stream metadata value.

Parameters

stream	The media stream
m_key	An arbitrary metadata key

Return values

non-NULL	metadata value
NULL	failure or not found

Since

15.5

Definition at line 423 of file stream.c.

References ast_assert_return, ast_stream::metadata, ast_variable::name, ast_variable::next, NULL, and ast_variable::value.

Referenced by add_msid_to_stream(), AST_TEST_DEFINE(), handle_incoming_sdp(), sdp_requires_deferral(), and sip_session_refresh().

{
   struct ast_variable *v;

   ast_assert_return(stream != NULL, NULL);
   ast_assert_return(m_key != NULL, NULL);

   for (v = stream->metadata; v; v = v->next) {
      if (strcmp(v->name, m_key) == 0) {
         return v->value;
      }
   }

   return NULL;
}

ast_stream_get_metadata_list()

struct ast_variable* ast_stream_get_metadata_list

(

const struct ast_stream *

stream

)

Get all stream metadata keys.

Parameters

stream

The media stream

Return values

An	ast_variable list of the metadata key/value pairs.
NULL	if error or no variables are set.

When you're finished with the list, you must call ast_variables_destroy(list);

Since

15.5

Definition at line 439 of file stream.c.

References ast_assert_return, ast_variable_list_append, ast_variable_new, ast_variables_destroy(), ast_stream::metadata, ast_variable::name, ast_variable::next, NULL, and ast_variable::value.

Referenced by ast_stream_clone(), and handle_showchan().

{
   struct ast_variable *v;
   struct ast_variable *vout = NULL;

   ast_assert_return(stream != NULL, NULL);

   for (v = stream->metadata; v; v = v->next) {
      struct ast_variable *vt = ast_variable_new(v->name, v->value, "");

      if (!vt) {
         ast_variables_destroy(vout);
         return NULL;
      }

      ast_variable_list_append(&vout, vt);
   }

   return vout;
}

ast_stream_get_name()

const char* ast_stream_get_name

(

const struct ast_stream *

stream

)

Get the name of a stream.

Parameters

stream

The media stream

Return values

non-NULL	success
NULL	failure

Since

15

Definition at line 309 of file stream.c.

References ast_assert, ast_stream::name, and NULL.

Referenced by ast_sip_session_media_state_add(), ast_stream_topology_equal(), AST_TEST_DEFINE(), handle_incoming_sdp(), handle_showchan(), is_media_state_valid(), is_video_dest(), is_video_source(), remove_all_original_streams(), resolve_refresh_media_states(), sdp_requires_deferral(), sip_session_refresh(), softmix_bridge_stream_sources_update(), and validate_stream().

{
   ast_assert(stream != NULL);

   return stream->name;
}

ast_stream_get_position()

int ast_stream_get_position

(

const struct ast_stream *

stream

)

Get the position of the stream in the topology.

Parameters

stream

The media stream

Returns

The position of the stream (-1 on error)

Since

15

Definition at line 500 of file stream.c.

References ast_assert, NULL, and ast_stream::position.

Referenced by __ast_read(), apply_negotiated_sdp_stream(), AST_TEST_DEFINE(), ast_write_stream(), check_stream_positions(), create_outgoing_sdp_stream(), stream_echo_write_error(), and tech_write().

{
   ast_assert(stream != NULL);

   return stream->position;
}

ast_stream_get_rtp_codecs()

struct ast_rtp_codecs* ast_stream_get_rtp_codecs

(

const struct ast_stream *

stream

)

Get rtp_codecs associated with the stream.

Parameters

stream

The media stream

Returns

The rtp_codecs

Since

15.5

Definition at line 507 of file stream.c.

References ast_assert, NULL, and ast_stream::rtp_codecs.

{
   ast_assert(stream != NULL);

   return stream->rtp_codecs;
}

ast_stream_get_state()

enum ast_stream_state ast_stream_get_state

(

const struct ast_stream *

stream

)

Get the current state of a stream.

Parameters

stream

The media stream

Returns

The state of the stream (AST_STREAM_STATE_UNKNOWN on error)

Since

15

Definition at line 373 of file stream.c.

References ast_assert, NULL, and ast_stream::state.

Referenced by append_all_streams(), ast_sip_session_create_outgoing(), ast_sip_session_is_pending_stream_default(), ast_sip_session_media_state_add(), ast_sip_session_media_state_clone(), ast_stream_topology_equal(), AST_TEST_DEFINE(), create_outgoing_sdp_stream(), handle_incoming_sdp(), handle_negotiated_sdp(), handle_showchan(), is_video_dest(), is_video_source(), local_request_with_stream_topology(), media_offer_read_av(), native_rtp_request_stream_topology_update(), resolve_refresh_media_states(), simple_bridge_request_stream_topology_update(), sip_session_refresh(), softmix_bridge_stream_sources_update(), softmix_bridge_stream_topology_changed(), stream_echo_topology_alloc(), test_media_add(), and unreal_colp_stream_topology_request_change().

{
   ast_assert(stream != NULL);

   return stream->state;
}

ast_stream_get_type()

enum ast_media_type ast_stream_get_type

(

const struct ast_stream *

stream

)

Get the media type of a stream.

Parameters

stream

The media stream

Returns

The media type of the stream (AST_MEDIA_TYPE_UNKNOWN on error)

Since

15

Definition at line 316 of file stream.c.

References ast_assert, NULL, and ast_stream::type.

Referenced by add_msid_to_stream(), ast_sip_session_create_joint_call_stream(), ast_sip_session_is_pending_stream_default(), ast_sip_session_media_state_clone(), ast_stream_topology_equal(), ast_stream_topology_map(), AST_TEST_DEFINE(), ast_write_stream(), check_stream_positions(), create_local_sdp(), handle_showchan(), is_media_state_valid(), is_video_dest(), is_video_source(), local_request_with_stream_topology(), media_offer_read_av(), native_rtp_request_stream_topology_update(), simple_bridge_request_stream_topology_update(), sip_session_refresh(), softmix_bridge_stream_sources_update(), softmix_bridge_stream_topology_changed(), stream_echo_topology_alloc(), stream_echo_write(), stream_echo_write_error(), and validate_stream().

{
   ast_assert(stream != NULL);

   return stream->type;
}

ast_stream_set_formats()

void ast_stream_set_formats	(	struct ast_stream *	stream,
		struct ast_format_cap *	caps
	)

Set the current negotiated formats of a stream.

Parameters

stream	The media stream
caps	The current negotiated formats

Note

The new format capabilities structure has its refcount bumped and any existing format capabilities structure has its refcount decremented.

Since

15

Definition at line 365 of file stream.c.

References ao2_bump, ao2_cleanup, ast_assert, ast_stream::formats, and NULL.

Referenced by apply_cap_to_bundled(), ast_sip_session_create_joint_call_stream(), ast_stream_create_resolved(), ast_stream_topology_create_from_format_cap(), AST_TEST_DEFINE(), build_topology(), local_request_with_stream_topology(), media_offer_write_av(), native_rtp_request_stream_topology_update(), simple_bridge_request_stream_topology_update(), sip_session_refresh(), and t38_create_media_state().

{
   ast_assert(stream != NULL);

   ao2_cleanup(stream->formats);
   stream->formats = ao2_bump(caps);
}

ast_stream_set_group()

void ast_stream_set_group	(	struct ast_stream *	stream,
		int	group
	)

Set the stream group for a stream.

Parameters

stream	The stream
group	The group the stream is part of

Since

15.2.0

Definition at line 1084 of file stream.c.

References ast_assert, ast_stream::group, and NULL.

Referenced by ast_stream_topology_clone(), and set_remote_mslabel_and_stream_group().

{
   ast_assert(stream != NULL);

   stream->group = group;
}

ast_stream_set_metadata()

int ast_stream_set_metadata	(	struct ast_stream *	stream,
		const char *	m_key,
		const char *	value
	)

Set a stream metadata value.

Parameters

stream	The media stream
m_key	An arbitrary metadata key
value	String metadata value or NULL to remove existing value

Return values

-1	failure
0	success

Since

15.5

Definition at line 460 of file stream.c.

References ast_assert_return, ast_free, ast_variable_list_append, ast_variable_new, ast_stream::metadata, ast_variable::name, ast_variable::next, and NULL.

Referenced by add_msid_to_stream(), append_source_stream(), AST_TEST_DEFINE(), handle_incoming_sdp(), media_offer_write_av(), and sdp_requires_deferral().

{
   struct ast_variable *v;
   struct ast_variable *prev;

   ast_assert_return(stream != NULL, -1);
   ast_assert_return(m_key != NULL, -1);

   prev = NULL;
   v = stream->metadata;
   while(v) {
      struct ast_variable *next = v->next;
      if (strcmp(v->name, m_key) == 0) {
         if (prev) {
            prev->next = next;
         } else {
            stream->metadata = next;
         }
         ast_free(v);
         break;
      } else {
         prev = v;
      }
      v = next;
   }

   if (!value) {
      return 0;
   }

   v = ast_variable_new(m_key, value, "");
   if (!v) {
      return -1;
   }

   ast_variable_list_append(&stream->metadata, v);

   return 0;
}

ast_stream_set_rtp_codecs()

void ast_stream_set_rtp_codecs	(	struct ast_stream *	stream,
		struct ast_rtp_codecs *	rtp_codecs
	)

Set rtp_codecs associated with the stream.

Parameters

stream	The media stream
rtp_codecs	The rtp_codecs

Since

15.5

Definition at line 514 of file stream.c.

References ast_assert, ast_rtp_codecs_payloads_destroy(), NULL, and ast_stream::rtp_codecs.

{
   ast_assert(stream != NULL);

   if (stream->rtp_codecs) {
      ast_rtp_codecs_payloads_destroy(rtp_codecs);
   }

   stream->rtp_codecs = rtp_codecs;
}

ast_stream_set_state()

void ast_stream_set_state	(	struct ast_stream *	stream,
		enum ast_stream_state	state
	)

Set the state of a stream.

Parameters

stream	The media stream
state	The new state that the stream is in

Note

Used by stream creator to update internal state

Since

15

Definition at line 380 of file stream.c.

References ast_assert, NULL, ast_stream::state, and state.

Referenced by append_source_stream(), ast_stream_topology_create_resolved(), AST_TEST_DEFINE(), create_outgoing_sdp_stream(), handle_incoming_sdp(), handle_negotiated_sdp(), handle_negotiated_sdp_session_media(), native_rtp_request_stream_topology_update(), remove_all_original_streams(), remove_destination_streams(), remove_stream_from_bundle(), resolve_refresh_media_states(), sdp_requires_deferral(), simple_bridge_request_stream_topology_update(), sip_session_refresh(), softmix_bridge_stream_sources_update(), stream_echo_topology_alloc(), t38_create_media_state(), test_stream_alloc(), and unreal_colp_stream_topology_request_change().

{
   ast_assert(stream != NULL);

   stream->state = state;

}

ast_stream_set_type()

void ast_stream_set_type	(	struct ast_stream *	stream,
		enum ast_media_type	type
	)

Change the media type of a stream.

Parameters

stream	The media stream
type	The new media type

Since

15

Definition at line 323 of file stream.c.

References ast_assert, NULL, ast_stream::type, and type.

Referenced by AST_TEST_DEFINE().

{
   ast_assert(stream != NULL);

   stream->type = type;
}

ast_stream_state2str()

const char* ast_stream_state2str

(

enum ast_stream_state

state

)

Convert the state of a stream into a string.

Parameters

state

The stream state

Returns

The state of the stream in string format

Since

15

Definition at line 388 of file stream.c.

References AST_STREAM_STATE_INACTIVE, AST_STREAM_STATE_RECVONLY, AST_STREAM_STATE_REMOVED, AST_STREAM_STATE_SENDONLY, and AST_STREAM_STATE_SENDRECV.

Referenced by handle_showchan(), resolve_refresh_media_states(), and softmix_bridge_stream_sources_update().

{
   switch (state) {
   case AST_STREAM_STATE_REMOVED:
      return "removed";
   case AST_STREAM_STATE_SENDRECV:
      return "sendrecv";
   case AST_STREAM_STATE_SENDONLY:
      return "sendonly";
   case AST_STREAM_STATE_RECVONLY:
      return "recvonly";
   case AST_STREAM_STATE_INACTIVE:
      return "inactive";
   default:
      return "<unknown>";
   }
}

ast_stream_str2state()

enum ast_stream_state ast_stream_str2state

(

const char *

str

)

Convert a string to a stream state.

Parameters

str	The string to convert

Returns

The stream state

Since

15.0.0

Definition at line 406 of file stream.c.

References AST_STREAM_STATE_INACTIVE, AST_STREAM_STATE_RECVONLY, AST_STREAM_STATE_REMOVED, AST_STREAM_STATE_SENDONLY, and AST_STREAM_STATE_SENDRECV.

{
   if (!strcmp("sendrecv", str)) {
      return AST_STREAM_STATE_SENDRECV;
   }
   if (!strcmp("sendonly", str)) {
      return AST_STREAM_STATE_SENDONLY;
   }
   if (!strcmp("recvonly", str)) {
      return AST_STREAM_STATE_RECVONLY;
   }
   if (!strcmp("inactive", str)) {
      return AST_STREAM_STATE_INACTIVE;
   }
   return AST_STREAM_STATE_REMOVED;
}

ast_stream_to_str()

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.

Since

18

Parameters

stream	A stream
buf	A pointer to an ast_str* used for the output.

Return values

""	(empty string) if either buf or *buf are NULL
(null stream)	if *stream was NULL
<stream_representation>	otherwise

Warning

No attempt should ever be made to free the returned char * and it should be dup'd if needed after the ast_str is freed.

Return format: <name>:<media_type>:<stream_state> (formats)

Sample return: "audio:audio:sendrecv (ulaw,g722)"

Definition at line 337 of file stream.c.

References ast_codec_media_type2str(), ast_format_cap_append_names(), ast_str_append(), ast_str_buffer(), ast_stream_state_map, ast_stream::formats, ast_stream::name, ast_stream::position, S_OR, ast_stream::state, and ast_stream::type.

Referenced by add_sdp_streams(), apply_negotiated_sdp_stream(), ast_stream_create_resolved(), ast_stream_topology_to_str(), create_local_sdp(), create_outgoing_sdp_stream(), handle_incoming_sdp(), is_media_state_valid(), resolve_refresh_media_states(), and softmix_bridge_stream_sources_update().

{
   if (!buf || !*buf) {
      return "";
   }

   if (!stream) {
      ast_str_append(buf, 0, "(null stream)");
      return ast_str_buffer(*buf);
   }

   ast_str_append(buf, 0, "%d:%s:%s:%s ",
      stream->position,
      S_OR(stream->name, "noname"),
      ast_codec_media_type2str(stream->type),
      ast_stream_state_map[stream->state]);
   ast_format_cap_append_names(stream->formats, buf);

   return ast_str_buffer(*buf);
}

ast_stream_topology_alloc()

struct ast_stream_topology* ast_stream_topology_alloc

(

void

)

Create a stream topology.

Return values

non-NULL	success
NULL	failure

Since

15

Note

This returns an ao2 refcounted object

Definition at line 650 of file stream.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_ref, AST_VECTOR_INIT, NULL, stream_topology_destroy(), and TOPOLOGY_INITIAL_STREAM_COUNT.

Referenced by __ast_channel_alloc_ap(), ast_channel_set_stream_topology(), ast_sip_session_create_outgoing(), ast_stream_topology_clone(), ast_stream_topology_create_from_format_cap(), ast_stream_topology_create_resolved(), AST_TEST_DEFINE(), ast_unreal_indicate(), build_topology(), handle_incoming_sdp(), make_channel(), sdp_requires_deferral(), sfu_topologies_on_join(), sfu_topologies_on_source_change(), softmix_bridge_stream_sources_update(), stream_echo_topology_alloc(), and t38_create_media_state().

{
   struct ast_stream_topology *topology;

   topology = ao2_alloc_options(sizeof(*topology), stream_topology_destroy, AO2_ALLOC_OPT_LOCK_NOLOCK);
   if (!topology) {
      return NULL;
   }

   if (AST_VECTOR_INIT(&topology->streams, TOPOLOGY_INITIAL_STREAM_COUNT)) {
      ao2_ref(topology, -1);
      topology = NULL;
   }

   return topology;
}

ast_stream_topology_append_stream()

int ast_stream_topology_append_stream	(	struct ast_stream_topology *	topology,
		struct ast_stream *	stream
	)

Append a stream to the topology.

Parameters

topology	The topology of streams
stream	The stream to append

Returns

the position of the stream in the topology (-1 on error)

Since

15

Note

If the stream's name is empty, it'll be set to <stream_type>-<position>

Definition at line 748 of file stream.c.

References ast_assert, ast_codec_media_type2str(), ast_strlen_zero, AST_VECTOR_APPEND, AST_VECTOR_SIZE, MIN_STREAM_NAME_LEN, ast_stream::name, ast_stream::position, and ast_stream::type.

Referenced by append_all_streams(), append_source_stream(), ast_sip_session_create_outgoing(), ast_stream_topology_create_from_format_cap(), ast_stream_topology_create_resolved(), AST_TEST_DEFINE(), ast_unreal_indicate(), build_topology(), make_channel(), resolve_refresh_media_states(), sip_session_refresh(), stream_echo_topology_alloc(), and test_media_add().

{
   ast_assert(topology && stream);

   if (AST_VECTOR_APPEND(&topology->streams, stream)) {
      return -1;
   }

   stream->position = AST_VECTOR_SIZE(&topology->streams) - 1;

   if (ast_strlen_zero(stream->name)) {
      snprintf(stream->name, MIN_STREAM_NAME_LEN, "%s-%d", ast_codec_media_type2str(stream->type), stream->position);
   }

   return AST_VECTOR_SIZE(&topology->streams) - 1;
}

ast_stream_topology_clone()

struct ast_stream_topology* ast_stream_topology_clone

(

const struct ast_stream_topology *

topology

)

Create a deep clone of an existing stream topology.

Parameters

topology

The existing topology of streams

Return values

non-NULL	success
NULL	failure

Since

15

Note

This returns an ao2 refcounted object

Definition at line 667 of file stream.c.

References ast_assert, ast_stream_clone(), ast_stream_free(), ast_stream_get_group(), ast_stream_set_group(), ast_stream_topology_alloc(), ast_stream_topology_free(), AST_VECTOR_APPEND, AST_VECTOR_GET, AST_VECTOR_SIZE, and NULL.

Referenced by ast_sip_session_create_outgoing(), ast_sip_session_media_state_clone(), AST_TEST_DEFINE(), ast_unreal_alloc_stream_topology(), ast_unreal_new_channels(), chan_pjsip_new(), create_local_sdp(), dial_exec_full(), do_forward(), handle_negotiated_sdp(), local_request_with_stream_topology(), media_offer_read_av(), media_offer_write_av(), native_rtp_request_stream_topology_update(), session_refresh_state_get_or_alloc(), sfu_topologies_on_join(), sfu_topologies_on_source_change(), simple_bridge_request_stream_topology_update(), softmix_bridge_stream_sources_update(), topology_change_refresh_data_alloc(), and unreal_colp_stream_topology_request_change().

{
   struct ast_stream_topology *new_topology;
   int i;

   ast_assert(topology != NULL);

   new_topology = ast_stream_topology_alloc();
   if (!new_topology) {
      return NULL;
   }

   for (i = 0; i < AST_VECTOR_SIZE(&topology->streams); i++) {
      struct ast_stream *existing = AST_VECTOR_GET(&topology->streams, i);
      struct ast_stream *stream = ast_stream_clone(existing, NULL);

      if (!stream || AST_VECTOR_APPEND(&new_topology->streams, stream)) {
         ast_stream_free(stream);
         ast_stream_topology_free(new_topology);
         return NULL;
      }

      ast_stream_set_group(stream, ast_stream_get_group(existing));
   }

   return new_topology;
}

ast_stream_topology_create_from_format_cap()

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 media types in format_cap into separate streams.

Parameters

caps	The format capabilities structure (NULL creates an empty topology)

Return values

non-NULL	success
NULL	failure

Note

The format capabilities reference is NOT altered by this function since a new format capabilities structure is created for each media type.

Each stream will have its name set to the corresponding media type. For example: "audio".

Each stream will be set to the sendrecv state.

Since

15

Definition at line 848 of file stream.c.

References ao2_cleanup, ao2_ref, ast_codec_media_type2str(), ast_format_cap_alloc, ast_format_cap_append_from_cap(), ast_format_cap_count(), AST_FORMAT_CAP_FLAG_DEFAULT, ast_format_cap_get_framing(), ast_format_cap_has_type(), ast_format_cap_set_framing(), AST_MEDIA_TYPE_END, AST_MEDIA_TYPE_UNKNOWN, ast_stream_alloc(), ast_stream_free(), ast_stream_set_formats(), AST_STREAM_STATE_SENDRECV, ast_stream_topology_alloc(), ast_stream_topology_append_stream(), ast_stream_topology_free(), MIN_STREAM_NAME_LEN, ast_stream::name, NULL, ast_stream::position, ast_stream::state, ast_stream::type, and type.

Referenced by ast_channel_nativeformats_set(), AST_TEST_DEFINE(), ast_unreal_alloc(), chan_pjsip_request(), local_request(), request_channel(), and sip_endpoint_apply_handler().

{
   struct ast_stream_topology *topology;
   enum ast_media_type type;

   topology = ast_stream_topology_alloc();
   if (!topology || !cap || !ast_format_cap_count(cap)) {
      return topology;
   }

   for (type = AST_MEDIA_TYPE_UNKNOWN + 1; type < AST_MEDIA_TYPE_END; type++) {
      struct ast_format_cap *new_cap;
      struct ast_stream *stream;

      if (!ast_format_cap_has_type(cap, type)) {
         continue;
      }

      new_cap = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
      if (!new_cap) {
         ast_stream_topology_free(topology);
         return NULL;
      }

      ast_format_cap_set_framing(new_cap, ast_format_cap_get_framing(cap));
      if (ast_format_cap_append_from_cap(new_cap, cap, type)) {
         ao2_cleanup(new_cap);
         ast_stream_topology_free(topology);
         return NULL;
      }

      stream = ast_stream_alloc(NULL, type);
      if (!stream) {
         ao2_cleanup(new_cap);
         ast_stream_topology_free(topology);
         return NULL;
      }

      ast_stream_set_formats(stream, new_cap);
      ao2_ref(new_cap, -1);
      stream->state = AST_STREAM_STATE_SENDRECV;
      if (ast_stream_topology_append_stream(topology, stream) == -1) {
         ast_stream_free(stream);
         ast_stream_topology_free(topology);
         return NULL;
      }

      snprintf(stream->name, MIN_STREAM_NAME_LEN, "%s-%d", ast_codec_media_type2str(stream->type), stream->position);
   }

   return topology;
}

ast_stream_topology_create_resolved()

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.

Since

18

Parameters

pending_topology	The "live" topology created from an SDP, passed through the core, or used to create an SDP.
configured_topology	The static topology used to validate the pending topology. It MUST have only 1 stream per media type.
prefs	A pointer to an ast_stream_codec_negotiation_prefs structure.
error_message	If supplied, error messages will be appended.

The streams in the resolved topology will contain all of the attributes of the corresponding stream from the pending topology. It's format_caps however will contain only the formats that passed the validation specified by the ast_stream_codec_negotiation_prefs structure. This may mean that some of the streams format_caps will be empty. If that's the case, the stream will be in a REMOVED state. With those rules in mind, a resolved topology will always be returned (unless there's some catastrophic allocation failure) and the resolved topology is guaranteed to have the same number of streams, in the same order, as the pending topology.

Return values

NULL	if there was some allocation failure.
The	joint topology.

Definition at line 1030 of file stream.c.

References ao2_cleanup, ast_stream_clone(), ast_stream_create_resolved(), ast_stream_free(), ast_stream_get_format_count(), ast_stream_set_state(), AST_STREAM_STATE_REMOVED, ast_stream_topology_alloc(), ast_stream_topology_append_stream(), ast_stream_topology_get_first_stream_by_type(), AST_VECTOR_GET, AST_VECTOR_SIZE, NULL, and ast_stream::type.

{
   struct ast_stream_topology *joint_topology = ast_stream_topology_alloc();
   int res = 0;
   int i;

   if (!pending_topology || !configured_topology || !joint_topology) {
      ao2_cleanup(joint_topology);
      return NULL;
   }

   for (i = 0; i < AST_VECTOR_SIZE(&pending_topology->streams); i++) {
      struct ast_stream *pending_stream = AST_VECTOR_GET(&pending_topology->streams, i);
      struct ast_stream *configured_stream =
         ast_stream_topology_get_first_stream_by_type(configured_topology, pending_stream->type);
      struct ast_stream *joint_stream;

      if (!configured_stream) {
         joint_stream = ast_stream_clone(pending_stream, NULL);
         if (!joint_stream) {
            ao2_cleanup(joint_topology);
            return NULL;
         }
         ast_stream_set_state(joint_stream, AST_STREAM_STATE_REMOVED);
      } else {
         joint_stream = ast_stream_create_resolved(pending_stream, configured_stream, prefs, error_message);
         if (!joint_stream) {
            ao2_cleanup(joint_topology);
            return NULL;
         } else if (ast_stream_get_format_count(joint_stream) == 0) {
            ast_stream_set_state(joint_stream, AST_STREAM_STATE_REMOVED);
         }
      }

      res = ast_stream_topology_append_stream(joint_topology, joint_stream);
      if (res < 0) {
         ast_stream_free(joint_stream);
         ao2_cleanup(joint_topology);
         return NULL;
      }
   }

   return joint_topology;
}

ast_stream_topology_del_stream()

int ast_stream_topology_del_stream	(	struct ast_stream_topology *	topology,
		unsigned int	position
	)

Delete a specified stream from the given topology.

Since

15.0.0

Parameters

topology	The topology of streams.
position	The topology position to delete.

Note

Deleting a stream will completely remove it from the topology as if it never existed in it. i.e., Any following stream positions will shift down so there is no gap.

Return values

0	on success.
-1	on failure.

Returns

Nothing

Definition at line 825 of file stream.c.

References ast_assert, ast_stream_free(), AST_VECTOR_GET, AST_VECTOR_REMOVE_ORDERED, AST_VECTOR_SIZE, NULL, and ast_stream::position.

Referenced by AST_TEST_DEFINE(), and sip_session_refresh().

{
   struct ast_stream *stream;

   ast_assert(topology != NULL);

   if (AST_VECTOR_SIZE(&topology->streams) <= position) {
      return -1;
   }

   stream = AST_VECTOR_REMOVE_ORDERED(&topology->streams, position);
   ast_stream_free(stream);

   /* Fix up higher stream position indices */
   for (; position < AST_VECTOR_SIZE(&topology->streams); ++position) {
      stream = AST_VECTOR_GET(&topology->streams, position);
      stream->position = position;
   }

   return 0;
}

ast_stream_topology_equal()

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.

Parameters

left	The left topology
right	The right topology

Return values

1	topologies are equivalent
0	topologies differ

Since

15

Definition at line 696 of file stream.c.

References ast_assert, ast_format_cap_count(), ast_format_cap_identical(), ast_stream_get_formats(), ast_stream_get_name(), ast_stream_get_state(), ast_stream_get_type(), ast_stream_topology_get_count(), ast_stream_topology_get_stream(), and NULL.

Referenced by ast_channel_request_stream_topology_change(), handle_negotiated_sdp(), reschedule_reinvite(), sip_session_refresh(), and test_is_media_state_equal().

{
   int index;

   ast_assert(left != NULL);
   ast_assert(right != NULL);

   if (ast_stream_topology_get_count(left) != ast_stream_topology_get_count(right)) {
      return 0;
   }

   for (index = 0; index < ast_stream_topology_get_count(left); ++index) {
      const struct ast_stream *left_stream = ast_stream_topology_get_stream(left, index);
      const struct ast_stream *right_stream = ast_stream_topology_get_stream(right, index);

      if (ast_stream_get_type(left_stream) != ast_stream_get_type(right_stream)) {
         return 0;
      }

      if (ast_stream_get_state(left_stream) != ast_stream_get_state(right_stream)) {
         return 0;
      }

      if (!ast_stream_get_formats(left_stream) && ast_stream_get_formats(right_stream) &&
         ast_format_cap_count(ast_stream_get_formats(right_stream))) {
         /* A NULL format capabilities and an empty format capabilities are the same, as they have
          * no formats inside. If one does though... they are not equal.
          */
         return 0;
      } else if (!ast_stream_get_formats(right_stream) && ast_stream_get_formats(left_stream) &&
         ast_format_cap_count(ast_stream_get_formats(left_stream))) {
         return 0;
      } else if (ast_stream_get_formats(left_stream) && ast_stream_get_formats(right_stream) &&
         !ast_format_cap_identical(ast_stream_get_formats(left_stream), ast_stream_get_formats(right_stream))) {
         /* But if both are actually present we need to do an actual identical check. */
         return 0;
      }

      if (strcmp(ast_stream_get_name(left_stream), ast_stream_get_name(right_stream))) {
         return 0;
      }
   }

   return 1;
}

ast_stream_topology_free()

void ast_stream_topology_free

(

struct ast_stream_topology *

topology

)

Unreference and destroy a stream topology.

Parameters

topology

The topology of streams

Note

All streams contained within the topology will be destroyed

Since

15

Definition at line 743 of file stream.c.

References ao2_cleanup.

Referenced by ast_channel_internal_set_stream_topology(), ast_sip_session_media_state_reset(), ast_stream_topology_clone(), ast_stream_topology_create_from_format_cap(), AST_TEST_DEFINE(), ast_unreal_alloc(), ast_unreal_destructor(), ast_unreal_new_channels(), build_topology(), chan_pjsip_new(), chan_pjsip_request(), create_local_sdp(), dial_exec_full(), do_forward(), endpoint_destructor(), local_request(), make_channel(), native_rtp_bridge_join(), native_rtp_stream_topology_changed(), request_channel(), sfu_topologies_on_join(), sfu_topologies_on_source_change(), simple_bridge_join(), simple_bridge_stream_topology_changed(), softmix_bridge_leave(), softmix_bridge_stream_sources_update(), softmix_bridge_stream_topology_changed(), stream_echo_exec(), stream_echo_topology_alloc(), and unreal_colp_stream_topology_request_change().

{
   ao2_cleanup(topology);
}

ast_stream_topology_get_active_count()

int ast_stream_topology_get_active_count

(

const struct ast_stream_topology *

topology

)

Get the number of active (non-REMOVED) streams in a topology.

Parameters

topology

The topology of streams

Returns

the number of active streams

Since

18

Definition at line 772 of file stream.c.

References ast_assert, AST_STREAM_STATE_REMOVED, AST_VECTOR_GET, AST_VECTOR_SIZE, NULL, and ast_stream::state.

{
   int i;
   int count = 0;
   ast_assert(topology != NULL);

   for (i = 0; i < AST_VECTOR_SIZE(&topology->streams); i++) {
      struct ast_stream *stream = AST_VECTOR_GET(&topology->streams, i);
      if (stream->state != AST_STREAM_STATE_REMOVED) {
         count++;
      }
   }

   return count;
}

ast_stream_topology_get_count()

int ast_stream_topology_get_count

(

const struct ast_stream_topology *

topology

)

Get the number of streams in a topology.

Parameters

topology

The topology of streams

Returns

the number of streams (-1 on error)

Since

15

Definition at line 765 of file stream.c.

References ast_assert, AST_VECTOR_SIZE, and NULL.

Referenced by append_all_streams(), append_source_streams(), ast_sip_session_create_outgoing(), ast_sip_session_is_pending_stream_default(), ast_stream_topology_equal(), ast_stream_topology_map(), AST_TEST_DEFINE(), ast_write_stream(), chan_pjsip_new(), check_stream_positions(), create_local_sdp(), handle_incoming_sdp(), handle_negotiated_sdp(), handle_showchan(), is_media_state_valid(), local_request_with_stream_topology(), make_channel(), map_source_to_destinations(), media_offer_read_av(), native_rtp_bridge_join(), native_rtp_request_stream_topology_update(), remove_all_original_streams(), remove_destination_streams(), resolve_refresh_media_states(), sdp_requires_deferral(), simple_bridge_join(), simple_bridge_request_stream_topology_update(), sip_session_refresh(), softmix_bridge_stream_sources_update(), softmix_bridge_stream_topology_changed(), stream_echo_topology_alloc(), stream_echo_write(), test_media_add(), unreal_colp_stream_topology_request_change(), and validate_original_streams().

{
   ast_assert(topology != NULL);

   return AST_VECTOR_SIZE(&topology->streams);
}

ast_stream_topology_get_first_stream_by_type()

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.

Parameters

topology	The topology of streams
type	The media type

Return values

non-NULL	success
NULL	failure

Since

15

Definition at line 964 of file stream.c.

References ast_assert, AST_STREAM_STATE_REMOVED, AST_VECTOR_GET, AST_VECTOR_SIZE, NULL, ast_stream::state, and ast_stream::type.

Referenced by ast_stream_topology_create_resolved(), AST_TEST_DEFINE(), channel_set_default_streams(), and media_offer_write_av().

{
   int i;

   ast_assert(topology != NULL);

   for (i = 0; i < AST_VECTOR_SIZE(&topology->streams); i++) {
      struct ast_stream *stream;

      stream = AST_VECTOR_GET(&topology->streams, i);
      if (stream->type == type
         && stream->state != AST_STREAM_STATE_REMOVED) {
         return stream;
      }
   }

   return NULL;
}

ast_stream_topology_get_formats()

struct ast_format_cap* ast_stream_topology_get_formats

(

struct ast_stream_topology *

topology

)

Create a format capabilities structure representing the topology.

A helper function that, given a stream topology, creates a format capabilities structure containing all formats from all active streams.

Parameters

topology

The topology of streams

Return values

non-NULL	success (the resulting format caps must be unreffed by the caller)
NULL	failure

Note

The stream topology is NOT altered by this function.

Since

15

Definition at line 930 of file stream.c.

References AST_MEDIA_TYPE_UNKNOWN, and ast_stream_topology_get_formats_by_type().

Referenced by AST_TEST_DEFINE(), ast_unreal_alloc_stream_topology(), chan_pjsip_new(), compatible_formats_exist(), and request_channel().

{
   return ast_stream_topology_get_formats_by_type(topology, AST_MEDIA_TYPE_UNKNOWN);
}

ast_stream_topology_get_formats_by_type()

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 particular type in the topology.

Since

18

A helper function that, given a stream topology and a media type, creates a format capabilities structure containing all formats from all active streams with the particular type.

Parameters

topology	The topology of streams
type	The media type

Return values

non-NULL	success (the resulting format caps must be unreffed by the caller)
NULL	failure

Note

The stream topology is NOT altered by this function.

Definition at line 902 of file stream.c.

References ast_assert, ast_format_cap_alloc, ast_format_cap_append_from_cap(), AST_FORMAT_CAP_FLAG_DEFAULT, AST_MEDIA_TYPE_UNKNOWN, AST_STREAM_STATE_REMOVED, AST_VECTOR_GET, AST_VECTOR_SIZE, ast_stream::formats, NULL, ast_stream::state, and ast_stream::type.

Referenced by ast_stream_topology_get_formats().

{
   struct ast_format_cap *caps;
   int i;

   ast_assert(topology != NULL);

   caps = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
   if (!caps) {
      return NULL;
   }

   for (i = 0; i < AST_VECTOR_SIZE(&topology->streams); i++) {
      struct ast_stream *stream;

      stream = AST_VECTOR_GET(&topology->streams, i);
      if (!stream->formats || stream->state == AST_STREAM_STATE_REMOVED) {
         continue;
      }
      if (type == AST_MEDIA_TYPE_UNKNOWN || type == stream->type) {
         ast_format_cap_append_from_cap(caps, stream->formats, AST_MEDIA_TYPE_UNKNOWN);
      }
   }

   return caps;
}

ast_stream_topology_get_stream()

struct ast_stream* ast_stream_topology_get_stream	(	const struct ast_stream_topology *	topology,
		unsigned int	position
	)

Get a specific stream from the topology.

Parameters

topology	The topology of streams
position	The topology position to get

Return values

non-NULL	success
NULL	failure

Since

15

Definition at line 788 of file stream.c.

References ast_assert, AST_VECTOR_GET, and NULL.

Referenced by __ast_read(), append_all_streams(), append_source_streams(), ast_sip_session_create_outgoing(), ast_sip_session_is_pending_stream_default(), ast_sip_session_media_state_add(), ast_sip_session_media_state_clone(), ast_stream_topology_equal(), ast_stream_topology_map(), AST_TEST_DEFINE(), ast_write_stream(), check_stream_positions(), create_local_sdp(), handle_incoming_sdp(), handle_negotiated_sdp(), handle_showchan(), is_compatible_format(), is_media_state_valid(), local_request_with_stream_topology(), map_source_to_destinations(), media_offer_read_av(), native_rtp_request_stream_topology_update(), remove_all_original_streams(), remove_destination_streams(), resolve_refresh_media_states(), sdp_requires_deferral(), simple_bridge_request_stream_topology_update(), sip_session_refresh(), softmix_bridge_stream_sources_update(), softmix_bridge_stream_topology_changed(), stream_echo_topology_alloc(), stream_echo_write(), stream_echo_write_error(), test_media_add(), unreal_colp_stream_topology_request_change(), and validate_original_streams().

{
   ast_assert(topology != NULL);

   return AST_VECTOR_GET(&topology->streams, stream_num);
}

ast_stream_topology_map()

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.

Note

The given vectors in which mapping values are placed are reset by this function. This means if those vectors already contain mapping values they will be lost.

Parameters

topology	The topology to map
types	The media types to be mapped
v0	Index mapping of topology to types
v1	Index mapping of types to topology

Since

15

Definition at line 985 of file stream.c.

References AST_MEDIA_TYPE_END, ast_stream_get_type(), ast_stream_topology_get_count(), ast_stream_topology_get_stream(), AST_VECTOR_APPEND, AST_VECTOR_ELEM_DEFAULT_CMP, AST_VECTOR_FREE, AST_VECTOR_GET_INDEX_NTH, AST_VECTOR_INIT, AST_VECTOR_REPLACE, AST_VECTOR_SIZE, and type.

Referenced by ast_bridge_channel_stream_map(), and AST_TEST_DEFINE().

{
   int i;
   int nths[AST_MEDIA_TYPE_END] = {0};
   int size = ast_stream_topology_get_count(topology);

   /*
    * Clear out any old mappings and initialize the new ones
    */
   AST_VECTOR_FREE(v0);
   AST_VECTOR_FREE(v1);

   /*
    * Both vectors are sized to the topology. The media types vector is always
    * guaranteed to be the size of the given topology or greater.
    */
   AST_VECTOR_INIT(v0, size);
   AST_VECTOR_INIT(v1, size);

   for (i = 0; i < size; ++i) {
      struct ast_stream *stream = ast_stream_topology_get_stream(topology, i);
      enum ast_media_type type = ast_stream_get_type(stream);
      int index = AST_VECTOR_GET_INDEX_NTH(types, ++nths[type],
         type, AST_VECTOR_ELEM_DEFAULT_CMP);

      if (index == -1) {
         /*
          * If a given type is not found for an index level then update the
          * media types vector with that type. This keeps the media types
          * vector always at the max topology size.
          */
         AST_VECTOR_APPEND(types, type);
         index = AST_VECTOR_SIZE(types) - 1;
      }

      /*
       * The mapping is reflexive in the sense that if it maps in one direction
       * then the reverse direction maps back to the other's index.
       */
      AST_VECTOR_REPLACE(v0, i, index);
      AST_VECTOR_REPLACE(v1, index, i);
   }
}

ast_stream_topology_set_stream()

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.

Parameters

topology	The topology of streams
position	The topology position to set
stream	The stream to put in its place

Return values

0	success
-1	failure

Note

If an existing stream exists it will be destroyed

You can overwrite an existing position in the topology or set the first unused position. You can't set positions beyond that.

Since

15

Note

If the stream's name is empty, it'll be set to <stream_type>-<position>

Definition at line 796 of file stream.c.

References ast_assert, ast_codec_media_type2str(), ast_stream_free(), ast_strlen_zero, AST_VECTOR_APPEND, AST_VECTOR_GET, AST_VECTOR_REPLACE, AST_VECTOR_SIZE, MIN_STREAM_NAME_LEN, ast_stream::name, ast_stream::position, and ast_stream::type.

Referenced by append_all_streams(), AST_TEST_DEFINE(), handle_incoming_sdp(), remove_all_original_streams(), resolve_refresh_media_states(), sdp_requires_deferral(), t38_create_media_state(), and test_media_add().

{
   struct ast_stream *existing_stream;

   ast_assert(topology && stream);

   if (position > AST_VECTOR_SIZE(&topology->streams)) {
      return -1;
   }

   if (position < AST_VECTOR_SIZE(&topology->streams)) {
      existing_stream = AST_VECTOR_GET(&topology->streams, position);
      ast_stream_free(existing_stream);
   }

   stream->position = position;

   if (position == AST_VECTOR_SIZE(&topology->streams)) {
      return AST_VECTOR_APPEND(&topology->streams, stream);
   }

   if (ast_strlen_zero(stream->name)) {
      snprintf(stream->name, MIN_STREAM_NAME_LEN, "%s-%d", ast_codec_media_type2str(stream->type), stream->position);
   }

   return AST_VECTOR_REPLACE(&topology->streams, position, stream);
}

ast_stream_topology_to_str()

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.

Since

18

Parameters

topology	A stream topology
buf	A pointer to an ast_str* used for the output.

Return values

""	(empty string) if either buf or *buf are NULL
(null topology)	if *topology was NULL
<topology_representation>	otherwise

Warning

No attempt should ever be made to free the returned char * and it should be dup'd if needed after the ast_str is freed.

Return format: <final>? <stream> ...

Sample return: "final <audio:audio:sendrecv (ulaw,g722)> <video:video:sendonly (h264)>"

Definition at line 936 of file stream.c.

References ast_str_append(), ast_str_buffer(), ast_stream_to_str(), AST_VECTOR_GET, AST_VECTOR_SIZE, and S_COR.

Referenced by ast_channel_request_stream_topology_change(), ast_channel_set_stream_topology(), ast_sip_session_create_outgoing(), call(), chan_pjsip_call(), chan_pjsip_indicate(), chan_pjsip_request_with_stream_topology(), compatible_formats_exist(), dial_exec_full(), is_media_state_valid(), on_topology_change_response(), resolve_refresh_media_states(), send_topology_change_refresh(), session_on_tsx_state(), sip_session_refresh(), softmix_bridge_stream_sources_update(), and wait_for_answer().

{
   int i;

   if (!buf ||!*buf) {
      return "";
   }

   if (!topology) {
      ast_str_append(buf, 0, "(null topology)");
      return ast_str_buffer(*buf);
   }

   ast_str_append(buf, 0, "%s", S_COR(topology->final, "final", ""));

   for (i = 0; i < AST_VECTOR_SIZE(&topology->streams); i++) {
      struct ast_stream *stream;

      stream = AST_VECTOR_GET(&topology->streams, i);
      ast_str_append(buf, 0, " <");
      ast_stream_to_str(stream, buf);
      ast_str_append(buf, 0, ">");
   }

   return ast_str_buffer(*buf);
}

Variable Documentation

ast_stream_codec_negotiation_keep_map

const char* ast_stream_codec_negotiation_keep_map[CODEC_NEGOTIATION_KEEP_END]

"keep" enum to string map

Definition at line 69 of file stream.c.

ast_stream_codec_negotiation_operation_map

const char* ast_stream_codec_negotiation_operation_map[CODEC_NEGOTIATION_OPERATION_END]

"operation" enum to string map

Definition at line 61 of file stream.c.

ast_stream_codec_negotiation_params_map

const char* ast_stream_codec_negotiation_params_map[CODEC_NEGOTIATION_PARAM_END]

Preference enum to string map.

Definition at line 47 of file stream.c.

ast_stream_codec_negotiation_prefer_map

const char* ast_stream_codec_negotiation_prefer_map[CODEC_NEGOTIATION_PREFER_END]

"prefer" enum to string map

Definition at line 55 of file stream.c.

ast_stream_codec_negotiation_transcode_map

const char* ast_stream_codec_negotiation_transcode_map[CODEC_NEGOTIATION_TRANSCODE_END]

"transcode" state enum to string map

Definition at line 75 of file stream.c.

ast_stream_state_map

const char* ast_stream_state_map[AST_STREAM_STATE_END]

Stream state enum to string map.

Definition at line 223 of file stream.c.

Referenced by ast_stream_to_str().