mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-23 22:45:39 +00:00
4c535f5c30
In WebRTC streams (or media tracks in their world) can be grouped together using the mslabel. This informs the browser that each should be synchronized with each other. This change extends the stream API so this information can be stored with streams. The PJSIP support has been extended to use the mslabel to determine grouped streams and store this association on the streams. Finally when creating the SDP the group information is used to cause each media stream to use the same mslabel. ASTERISK-27379 Change-Id: Id6299aa031efe46254edbdc7973c534d54d641ad
501 lines
12 KiB
C
501 lines
12 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 Convert a string to a stream state
|
|
*
|
|
* \param str The string to convert
|
|
*
|
|
* \return The stream state
|
|
*
|
|
* \since 15.0.0
|
|
*/
|
|
enum ast_stream_state ast_stream_str2state(const char *str);
|
|
|
|
/*!
|
|
* \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 Compare two stream topologies to see if they are equal
|
|
*
|
|
* \param left The left topology
|
|
* \param right The right topology
|
|
*
|
|
* \retval 1 topologies are equivalent
|
|
* \retval 0 topologies differ
|
|
*
|
|
* \since 15
|
|
*/
|
|
int ast_stream_topology_equal(const struct ast_stream_topology *left,
|
|
const struct ast_stream_topology *right);
|
|
|
|
/*!
|
|
* \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 Delete a specified stream from the given topology.
|
|
* \since 15.0.0
|
|
*
|
|
* \param topology The topology of streams.
|
|
* \param 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.
|
|
*
|
|
* \retval 0 on success.
|
|
* \retval -1 on failure.
|
|
*
|
|
* \return Nothing
|
|
*/
|
|
int ast_stream_topology_del_stream(struct ast_stream_topology *topology,
|
|
unsigned int position);
|
|
|
|
/*!
|
|
* \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: "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 Create a format capabilities structure representing the topology.
|
|
*
|
|
* \details
|
|
* A helper function that, given a stream topology, creates a format
|
|
* capabilities structure containing all formats from all active 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 active 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);
|
|
|
|
/*!
|
|
* \brief Get the stream group that a stream is part of
|
|
*
|
|
* \param stream The stream
|
|
*
|
|
* \return the numerical stream group (-1 if not in a group)
|
|
*
|
|
* \since 15.2.0
|
|
*/
|
|
int ast_stream_get_group(const struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief Set the stream group for a stream
|
|
*
|
|
* \param stream The stream
|
|
* \param group The group the stream is part of
|
|
*
|
|
* \since 15.2.0
|
|
*/
|
|
void ast_stream_set_group(struct ast_stream *stream, int group);
|
|
|
|
#endif /* _AST_STREAM_H */
|