mirror of
https://github.com/asterisk/asterisk.git
synced 2025-11-14 05:48:54 +00:00
2da869408a
This sets up the "plumbing" in bridge_softmix to be able to accommodate Asterisk asking as an SFU (selective forwarding unit) for conferences. The way this works is that whenever a channel enters or leaves a conference, all participants in the bridge get sent a stream topology change request. The topologies consist of the channels' original topology, along with video destination streams corresponding to each participants' source video streams. So for instance, if Alice, Bob, and Carol are in the conference, and each supplies one video stream, then the topologies for each would look like so: Alice: Audio, Source video(Alice), Destination Video(Bob), Destination video (Carol) Bob: Audio, Source video(Bob) Destination Video(Alice), Destination video (Carol) Carol: Audio, Source video(Carol) Destination Video(Alice), Destination video (Bob) This way, video that arrives from a source video stream can then be copied out to the destination video streams on the other participants' channels. Once the bridge gets told that a topology on a channel has changed, the bridge constructs a map in order to get the video frames routed to the proper destination streams. This is done using the bridge channel's stream_map. This change is bare-bones with regards to SFU support. Some key features are missing at this point: * Stream limits. This commit makes no effort to limit the number of streams on a specific channel. This means that if there were 50 video callers in a conference, bridge_softmix will happily send out topology change requests to every channel in the bridge, requesting 50+ streams. * Configuration. The plumbing has been added to bridge_softmix, but there has been nothing added as of yet to app_confbridge to enable SFU video mode. * Testing. Some functions included here have unit tests. However, the functionality as a whole has only been verified by hand-tracing the code. * Selectivenss. For a "selective" forwarding unit, this does not currently have any means of being selective. * Features. Presumably, someone might wish to only receive video from specific sources. There are no external-facing functions at the moment that allow for users to select who they receive video from. * Efficiency. The current scheme treats all video streams as being unidirectional. We could be re-using a source video stream as a desetnation, too. But to simplify things on this first round, I did it this way. Change-Id: I7c44a829cc63acf8b596a337b2dc3c13898a6c4d
433 lines
10 KiB
C
433 lines
10 KiB
C
/*
|
|
* Asterisk -- An open source telephony toolkit.
|
|
*
|
|
* Copyright (C) 2017, Digium, Inc.
|
|
*
|
|
* Joshua Colp <jcolp@digium.com>
|
|
*
|
|
* See http://www.asterisk.org for more information about
|
|
* the Asterisk project. Please do not directly contact
|
|
* any of the maintainers of this project for assistance;
|
|
* the project provides a web site, mailing lists and IRC
|
|
* channels for your use.
|
|
*
|
|
* This program is free software, distributed under the terms of
|
|
* the GNU General Public License Version 2. See the LICENSE file
|
|
* at the top of the source tree.
|
|
*/
|
|
|
|
/*!
|
|
* \file
|
|
* \brief Media Stream API
|
|
*
|
|
* \author Joshua Colp <jcolp@digium.com>
|
|
*/
|
|
|
|
#ifndef _AST_STREAM_H_
|
|
#define _AST_STREAM_H_
|
|
|
|
#include "asterisk/codec.h"
|
|
#include "asterisk/vector.h"
|
|
|
|
/*!
|
|
* \brief Forward declaration for a stream, as it is opaque
|
|
*/
|
|
struct ast_stream;
|
|
|
|
/*!
|
|
* \brief Forward declaration for a format capability
|
|
*/
|
|
struct ast_format_cap;
|
|
|
|
/*!
|
|
* \brief The topology of a set of streams
|
|
*/
|
|
struct ast_stream_topology;
|
|
|
|
/*!
|
|
* \brief A mapping of two topologies.
|
|
*/
|
|
struct ast_stream_topology_map;
|
|
|
|
typedef void (*ast_stream_data_free_fn)(void *);
|
|
|
|
/*!
|
|
* \brief States that a stream may be in
|
|
*/
|
|
enum ast_stream_state {
|
|
/*!
|
|
* \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 Stream data slots
|
|
*/
|
|
enum ast_stream_data_slot {
|
|
/*!
|
|
* \brief Data slot for RTP instance
|
|
*/
|
|
AST_STREAM_DATA_RTP_CODECS = 0,
|
|
/*!
|
|
* \brief Controls the size of the data pointer array
|
|
*/
|
|
AST_STREAM_DATA_SLOT_MAX
|
|
};
|
|
|
|
/*!
|
|
* \brief Create a new media stream representation
|
|
*
|
|
* \param name A name for the stream
|
|
* \param type The media type the stream is handling
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \note This is NOT an AO2 object and has no locking. It is expected that a higher level object provides protection.
|
|
*
|
|
* \note The stream will default to an inactive state until changed.
|
|
*
|
|
* \since 15
|
|
*/
|
|
struct ast_stream *ast_stream_alloc(const char *name, enum ast_media_type type);
|
|
|
|
/*!
|
|
* \brief Destroy a media stream representation
|
|
*
|
|
* \param stream The media stream
|
|
*
|
|
* \since 15
|
|
*/
|
|
void ast_stream_free(struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief Create a deep clone of an existing stream
|
|
*
|
|
* \param stream The existing stream
|
|
* \param Optional name for cloned stream. If NULL, then existing stream's name is copied.
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval 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
|
|
*/
|
|
struct ast_stream *ast_stream_clone(const struct ast_stream *stream, const char *name);
|
|
|
|
/*!
|
|
* \brief Get the name of a stream
|
|
*
|
|
* \param stream The media stream
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \since 15
|
|
*/
|
|
const char *ast_stream_get_name(const struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief Get the media type of a stream
|
|
*
|
|
* \param stream The media stream
|
|
*
|
|
* \return The media type of the stream (AST_MEDIA_TYPE_UNKNOWN on error)
|
|
*
|
|
* \since 15
|
|
*/
|
|
enum ast_media_type ast_stream_get_type(const struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief Change the media type of a stream
|
|
*
|
|
* \param stream The media stream
|
|
* \param type The new media type
|
|
*
|
|
* \since 15
|
|
*/
|
|
void ast_stream_set_type(struct ast_stream *stream, enum ast_media_type type);
|
|
|
|
/*!
|
|
* \brief Get the current negotiated formats of a stream
|
|
*
|
|
* \param stream The media stream
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \note The reference count is not increased
|
|
*
|
|
* \since 15
|
|
*/
|
|
struct ast_format_cap *ast_stream_get_formats(const struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief Set the current negotiated formats of a stream
|
|
*
|
|
* \param stream The media stream
|
|
* \param 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
|
|
*/
|
|
void ast_stream_set_formats(struct ast_stream *stream, struct ast_format_cap *caps);
|
|
|
|
/*!
|
|
* \brief Get the current state of a stream
|
|
*
|
|
* \param stream The media stream
|
|
*
|
|
* \return The state of the stream (AST_STREAM_STATE_UNKNOWN on error)
|
|
*
|
|
* \since 15
|
|
*/
|
|
enum ast_stream_state ast_stream_get_state(const struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief Set the state of a stream
|
|
*
|
|
* \param stream The media stream
|
|
* \param state The new state that the stream is in
|
|
*
|
|
* \note Used by stream creator to update internal state
|
|
*
|
|
* \since 15
|
|
*/
|
|
void ast_stream_set_state(struct ast_stream *stream, enum ast_stream_state state);
|
|
|
|
/*!
|
|
* \brief Convert the state of a stream into a string
|
|
*
|
|
* \param state The stream state
|
|
*
|
|
* \return The state of the stream in string format
|
|
*
|
|
* \since 15
|
|
*/
|
|
const char *ast_stream_state2str(enum ast_stream_state state);
|
|
|
|
/*!
|
|
* \brief Get the opaque stream data
|
|
*
|
|
* \param stream The media stream
|
|
* \param slot The data slot to retrieve
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \since 15
|
|
*/
|
|
void *ast_stream_get_data(struct ast_stream *stream, enum ast_stream_data_slot slot);
|
|
|
|
/*!
|
|
* \brief Set the opaque stream data
|
|
*
|
|
* \param stream The media stream
|
|
* \param slot The data slot to set
|
|
* \param data Opaque data
|
|
* \param data_free_fn Callback to free data when stream is freed. May be NULL for no action.
|
|
*
|
|
* \return data
|
|
*
|
|
* \since 15
|
|
*/
|
|
void *ast_stream_set_data(struct ast_stream *stream, enum ast_stream_data_slot slot,
|
|
void *data, ast_stream_data_free_fn data_free_fn);
|
|
|
|
/*!
|
|
* \brief Get the position of the stream in the topology
|
|
*
|
|
* \param stream The media stream
|
|
*
|
|
* \return The position of the stream (-1 on error)
|
|
*
|
|
* \since 15
|
|
*/
|
|
int ast_stream_get_position(const struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief Create a stream topology
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \since 15
|
|
*/
|
|
struct ast_stream_topology *ast_stream_topology_alloc(void);
|
|
|
|
/*!
|
|
* \brief Create a deep clone of an existing stream topology
|
|
*
|
|
* \param topology The existing topology of streams
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \since 15
|
|
*/
|
|
struct ast_stream_topology *ast_stream_topology_clone(
|
|
const struct ast_stream_topology *topology);
|
|
|
|
/*!
|
|
* \brief Destroy a stream topology
|
|
*
|
|
* \param topology The topology of streams
|
|
*
|
|
* \note All streams contained within the topology will be destroyed
|
|
*
|
|
* \since 15
|
|
*/
|
|
void ast_stream_topology_free(struct ast_stream_topology *topology);
|
|
|
|
/*!
|
|
* \brief Append a stream to the topology
|
|
*
|
|
* \param topology The topology of streams
|
|
* \param stream The stream to append
|
|
*
|
|
* \returns the position of the stream in the topology (-1 on error)
|
|
*
|
|
* \since 15
|
|
*/
|
|
int ast_stream_topology_append_stream(struct ast_stream_topology *topology,
|
|
struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief Get the number of streams in a topology
|
|
*
|
|
* \param topology The topology of streams
|
|
*
|
|
* \return the number of streams (-1 on error)
|
|
*
|
|
* \since 15
|
|
*/
|
|
int ast_stream_topology_get_count(const struct ast_stream_topology *topology);
|
|
|
|
/*!
|
|
* \brief Get a specific stream from the topology
|
|
*
|
|
* \param topology The topology of streams
|
|
* \param position The topology position to get
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \since 15
|
|
*/
|
|
struct ast_stream *ast_stream_topology_get_stream(
|
|
const struct ast_stream_topology *topology, unsigned int position);
|
|
|
|
/*!
|
|
* \brief Set a specific position in a topology
|
|
*
|
|
* \param topology The topology of streams
|
|
* \param position The topology position to set
|
|
* \param stream The stream to put in its place
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*
|
|
* \note If an existing stream exists it will be destroyed
|
|
*
|
|
* \note You can overwrite an existing position in the topology or set
|
|
* the first unused position. You can't set positions beyond that.
|
|
*
|
|
* \since 15
|
|
*/
|
|
int ast_stream_topology_set_stream(struct ast_stream_topology *topology,
|
|
unsigned int position, struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief A helper function that, given a format capabilities structure,
|
|
* creates a topology and separates the media types in format_cap into
|
|
* separate streams.
|
|
*
|
|
* \param caps The format capabilities structure (NULL creates an empty topology)
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval 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.
|
|
*
|
|
* \note Each stream will have its name set to the corresponding media type.
|
|
* For example: "AST_MEDIA_TYPE_AUDIO".
|
|
*
|
|
* \note Each stream will be set to the sendrecv state.
|
|
*
|
|
* \since 15
|
|
*/
|
|
struct ast_stream_topology *ast_stream_topology_create_from_format_cap(
|
|
struct ast_format_cap *cap);
|
|
|
|
/*!
|
|
* \brief A helper function that, given a stream topology, creates a format
|
|
* capabilities structure containing all formats from all streams.
|
|
*
|
|
* \param topology The topology of streams
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \note The stream topology is NOT altered by this function.
|
|
*
|
|
* \since 15
|
|
*/
|
|
struct ast_format_cap *ast_format_cap_from_stream_topology(
|
|
struct ast_stream_topology *topology);
|
|
|
|
/*!
|
|
* \brief Gets the first stream of a specific type from the topology
|
|
*
|
|
* \param topology The topology of streams
|
|
* \param type The media type
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \since 15
|
|
*/
|
|
struct ast_stream *ast_stream_topology_get_first_stream_by_type(
|
|
const struct ast_stream_topology *topology,
|
|
enum ast_media_type type);
|
|
|
|
/*!
|
|
* \brief 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.
|
|
*
|
|
* \param topology The topology to map
|
|
* \param types The media types to be mapped
|
|
* \param v0 Index mapping of topology to types
|
|
* \param v1 Index mapping of types to topology
|
|
*
|
|
* \since 15
|
|
*/
|
|
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);
|
|
|
|
#endif /* _AST_STREAM_H */
|