mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-05 12:16:00 +00:00
d4f3b17dd3
When both Asterisk and a UA send re-invites at the same time, both
send 491 "Transaction in progress" responses to each other and back
off a specified amount of time before retrying. When Asterisk
prepares to send its re-invite, it sets up the session's pending
media state with the new topology it wants, then sends the
re-invite. Unfortunately, when it received the re-invite from the
UA, it partially processed the media in the re-invite and reset
the pending media state before sending the 491 losing the state it
set in its own re-invite.
Asterisk also was not tracking re-invites received while an existing
re-invite was queued resulting in sending stale SDP with missing
or duplicated streams, or no re-invite at all because we erroneously
determined that a re-invite wasn't needed.
There was also an issue in bridge_softmix where we were using a stream
from the wrong topology to determine if a stream was added. This also
caused us to erroneously determine that a re-invite wasn't needed.
Regardless of how the delayed re-invite was triggered, we need to
reconcile the topology that was active at the time the delayed
request was queued, the pending topology of the queued request,
and the topology currently active on the session. To do this we
need a topology resolver AND we need to make stream named unique
so we can accurately tell what a stream has been added or removed
and if we can re-use a slot in the topology.
Summary of changes:
* bridge_softmix:
* We no longer reset the stream name to "removed" in
remove_all_original_streams(). That was causing multiple streams
to have the same name and wrecked the checks for duplicate streams.
* softmix_bridge_stream_sources_update() was checking the old_stream
to see if it had the softmix prefix and not considering the stream
as "new" if it did. If the stream in that slot has something in it
because another re-invite happened, then that slot in old might
have a softmix stream but the same stream in new might actually
be a new one. Now we check the new_stream's name instead of
the old_stream's.
* stream:
* Instead of using plain media type name ("audio", "video", etc) as
the default stream name, we now append the stream position to it
to make it unique. We need to do this so we can distinguish multiple
streams of the same type from each other.
* When we set a stream's state to REMOVED, we no longer reset its
name to "removed" or destroy its metadata. Again, we need to
do this so we can distinguish multiple streams of the same
type from each other.
* res_pjsip_session:
* Added resolve_refresh_media_states() that takes in 3 media states
and creates an up-to-date pending media state that includes the changes
that might have happened while a delayed session refresh was in the
delayed queue.
* Added is_media_state_valid() that checks the consistency of
a media state and returns a true/false value. A valid state has:
* The same number of stream entries as media session entries.
Some media session entries can be NULL however.
* No duplicate streams.
* A valid stream for each non-NULL media session.
* A stream that matches each media session's stream_num
and media type.
* Updated handle_incoming_sdp() to set the stream name to include the
stream position number in the name to make it unique.
* Updated the ast_sip_session_delayed_request structure to include both
the pending and active media states and updated the associated delay
functions to process them.
* Updated sip_session_refresh() to accept both the pending and active
media states that were in effect when the request was originally queued
and to pass them on should the request need to be delayed again.
* Updated sip_session_refresh() to call resolve_refresh_media_states()
and substitute its results for the pending state passed in.
* Updated sip_session_refresh() with additional debugging.
* Updated session_reinvite_on_rx_request() to simply return PJ_FALSE
to pjproject if a transaction is in progress. This stops us from
creating a partial pending media state that would be invalid later on.
* Updated reschedule_reinvite() to clone both the current pending and
active media states and pass them to delay_request() so the resolver
can tell what the original intention of the re-invite was.
* Added a large unit test for the resolver.
ASTERISK-29014
Change-Id: Id3440972943c611a15f652c6c569fa0e4536bfcb
988 lines
28 KiB
C
988 lines
28 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 Internal macro to assist converting enums to strings
|
|
* \internal
|
|
* \since 18
|
|
*
|
|
* This macro checks that _value is in the bounds
|
|
* of the enum/string map.
|
|
*/
|
|
#define _stream_maps_to_str(_mapname, _value) \
|
|
({ \
|
|
const char *_rtn = ""; \
|
|
if (ARRAY_IN_BOUNDS(_value, _mapname)) { \
|
|
_rtn = _mapname[_value]; \
|
|
} \
|
|
_rtn; \
|
|
})
|
|
|
|
/*!
|
|
* \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 Sentinel
|
|
*/
|
|
AST_STREAM_STATE_END
|
|
};
|
|
|
|
/*!
|
|
* \brief Stream state enum to string map
|
|
* \internal
|
|
* \since 18
|
|
*/
|
|
extern const char *ast_stream_state_map[AST_STREAM_STATE_END];
|
|
|
|
/*!
|
|
* \brief Safely get the name of a stream state
|
|
* \since 18
|
|
*
|
|
* \param 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.
|
|
*/
|
|
#define ast_stream_state_to_str(stream_state) _stream_maps_to_str(ast_stream_state_map, stream_state)
|
|
|
|
/*!
|
|
* \brief Advanced Codec Negotiation Preferences
|
|
* \since 18
|
|
*/
|
|
|
|
/*!
|
|
* \brief The preference parameters themselves
|
|
* \since 18
|
|
*/
|
|
enum ast_stream_codec_negotiation_params {
|
|
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,
|
|
};
|
|
|
|
/*!
|
|
* \brief The "prefer" values
|
|
* \since 18
|
|
*/
|
|
enum ast_stream_codec_negotiation_prefs_prefer_values {
|
|
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,
|
|
};
|
|
|
|
/*!
|
|
* \brief The "operation" values
|
|
* \since 18
|
|
*/
|
|
enum ast_stream_codec_negotiation_prefs_operation_values {
|
|
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,
|
|
};
|
|
|
|
/*!
|
|
* \brief The "keep" values
|
|
* \since 18
|
|
*/
|
|
enum ast_stream_codec_negotiation_prefs_keep_values {
|
|
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,
|
|
};
|
|
|
|
/*!
|
|
* \brief The "transcode" values
|
|
* \since 18
|
|
*/
|
|
enum ast_stream_codec_negotiation_prefs_transcode_values {
|
|
CODEC_NEGOTIATION_TRANSCODE_UNSPECIFIED = 0,
|
|
/*! "allow" transcoding */
|
|
CODEC_NEGOTIATION_TRANSCODE_ALLOW,
|
|
/*! "prevent" transcoding */
|
|
CODEC_NEGOTIATION_TRANSCODE_PREVENT,
|
|
/*! Sentinel */
|
|
CODEC_NEGOTIATION_TRANSCODE_END,
|
|
};
|
|
|
|
/*!
|
|
* \brief Preference enum to string map
|
|
* \internal
|
|
* \since 18
|
|
*/
|
|
extern const char *ast_stream_codec_negotiation_params_map[CODEC_NEGOTIATION_PARAM_END];
|
|
|
|
/*!
|
|
* \brief "prefer" enum to string map
|
|
* \internal
|
|
* \since 18
|
|
*/
|
|
extern const char *ast_stream_codec_negotiation_prefer_map[CODEC_NEGOTIATION_PREFER_END];
|
|
|
|
/*!
|
|
* \brief "operation" enum to string map
|
|
* \internal
|
|
* \since 18
|
|
*/
|
|
extern const char *ast_stream_codec_negotiation_operation_map[CODEC_NEGOTIATION_OPERATION_END];
|
|
|
|
/*!
|
|
* \brief "keep" enum to string map
|
|
* \internal
|
|
* \since 18
|
|
*/
|
|
extern const char *ast_stream_codec_negotiation_keep_map[CODEC_NEGOTIATION_KEEP_END];
|
|
|
|
/*!
|
|
* \brief "transcode" state enum to string map
|
|
* \internal
|
|
* \since 18
|
|
*/
|
|
extern const char *ast_stream_codec_negotiation_transcode_map[CODEC_NEGOTIATION_TRANSCODE_END];
|
|
|
|
/*!
|
|
* \brief Safely get the name of a preference parameter
|
|
* \since 18
|
|
*
|
|
* \param value One of enum \ref 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.
|
|
*/
|
|
#define ast_stream_codec_param_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_params_map, value)
|
|
|
|
/*!
|
|
* \brief Safely get the name of a "prefer" parameter value
|
|
* \since 18
|
|
*
|
|
* \param value One of enum \ref 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.
|
|
*/
|
|
#define ast_stream_codec_prefer_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_prefer_map, value)
|
|
|
|
/*!
|
|
* \brief Safely get the name of an "operation" parameter value
|
|
* \since 18
|
|
*
|
|
* \param value One of enum \ref 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.
|
|
*/
|
|
#define ast_stream_codec_operation_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_operation_map, value)
|
|
|
|
/*!
|
|
* \brief Safely get the name of a "keep" parameter value
|
|
* \since 18
|
|
*
|
|
* \param value One of enum \ref 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.
|
|
*/
|
|
#define ast_stream_codec_keep_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_keep_map, value)
|
|
|
|
/*!
|
|
* \brief Safely get the name of a "transcode" parameter value
|
|
* \since 18
|
|
*
|
|
* \param value One of enum \ref 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.
|
|
*/
|
|
#define ast_stream_codec_transcode_to_str(value) _stream_maps_to_str(ast_stream_codec_negotiation_transcode_map, value)
|
|
|
|
/*!
|
|
* \brief
|
|
* \since 18
|
|
*
|
|
* The structure that makes up a codec negotiation preference object
|
|
*/
|
|
struct ast_stream_codec_negotiation_prefs {
|
|
/*! Which codec list to prefer */
|
|
enum ast_stream_codec_negotiation_prefs_prefer_values prefer;
|
|
/*! The operation to perform on the lists */
|
|
enum ast_stream_codec_negotiation_prefs_operation_values operation;
|
|
/*! What to keep after the operation is performed */
|
|
enum ast_stream_codec_negotiation_prefs_keep_values keep;
|
|
/*! To allow or prevent transcoding */
|
|
enum ast_stream_codec_negotiation_prefs_transcode_values transcode;
|
|
};
|
|
|
|
/*!
|
|
* \brief Define for allocating buffer space for to_str() functions
|
|
* \since 18
|
|
*/
|
|
#define AST_STREAM_MAX_CODEC_PREFS_LENGTH (128)
|
|
|
|
/*!
|
|
* \brief 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
|
|
*
|
|
* \param prefs A pointer to a ast_stream_codec_negotiation_prefs structure
|
|
* \param 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"
|
|
*/
|
|
const char *ast_stream_codec_prefs_to_str(const struct ast_stream_codec_negotiation_prefs *prefs,
|
|
struct ast_str **buf);
|
|
|
|
/*!
|
|
* \brief 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.
|
|
*
|
|
* \param pref_string A string in the format described by ast_stream_codec_prefs_to_str().
|
|
* \param prefs Pointer to a ast_stream_codec_negotiation_prefs structure to receive the parsed values.
|
|
* \param error_message An optional ast_str** into which parsing errors will be placed.
|
|
*
|
|
* \retval 0 if success
|
|
* \retval -1 if failed
|
|
*
|
|
* \details
|
|
* 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"
|
|
*/
|
|
int ast_stream_codec_prefs_parse(const char *pref_string, struct ast_stream_codec_negotiation_prefs *prefs,
|
|
struct ast_str **error_message);
|
|
|
|
/*!
|
|
* \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
|
|
*/
|
|
const struct ast_format_cap *ast_stream_get_formats(const struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief Get a string representing the stream for debugging/display purposes
|
|
* \since 18
|
|
*
|
|
* \param stream A stream
|
|
* \param buf A pointer to an ast_str* used for the output.
|
|
*
|
|
* \retval "" (empty string) if either buf or *buf are NULL
|
|
* \retval "(null stream)" if *stream was NULL
|
|
* \retval <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.
|
|
*
|
|
* \details
|
|
*
|
|
* Return format:
|
|
* <name>:<media_type>:<stream_state> (formats)
|
|
*
|
|
* Sample return:
|
|
* "audio:audio:sendrecv (ulaw,g722)"
|
|
*
|
|
*/
|
|
const char *ast_stream_to_str(const struct ast_stream *stream, struct ast_str **buf);
|
|
|
|
/*!
|
|
* \brief Get a stack allocated string representing the stream for debugging/display purposes
|
|
*
|
|
* \param 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.
|
|
*
|
|
*/
|
|
#define ast_stream_to_stra(__stream) ast_str_tmp(128, ast_stream_to_str(__stream, &STR_TMP))
|
|
|
|
/*!
|
|
* \brief Get the count of the current negotiated formats of a stream
|
|
*
|
|
* \param stream The media stream
|
|
*
|
|
* \return The count of negotiated formats
|
|
*
|
|
* \since 18
|
|
*/
|
|
int ast_stream_get_format_count(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 a stream metadata value
|
|
*
|
|
* \param stream The media stream
|
|
* \param m_key An arbitrary metadata key
|
|
*
|
|
* \retval non-NULL metadata value
|
|
* \retval NULL failure or not found
|
|
*
|
|
* \since 15.5
|
|
*/
|
|
const char *ast_stream_get_metadata(const struct ast_stream *stream,
|
|
const char *m_key);
|
|
|
|
/*!
|
|
* \brief Get all stream metadata keys
|
|
*
|
|
* \param stream The media stream
|
|
*
|
|
* \retval An ast_variable list of the metadata key/value pairs.
|
|
* \retval 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
|
|
*/
|
|
struct ast_variable *ast_stream_get_metadata_list(const struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief Set a stream metadata value
|
|
*
|
|
* \param stream The media stream
|
|
* \param m_key An arbitrary metadata key
|
|
* \param value String metadata value or NULL to remove existing value
|
|
*
|
|
* \retval -1 failure
|
|
* \retval 0 success
|
|
*
|
|
* \since 15.5
|
|
*/
|
|
int ast_stream_set_metadata(struct ast_stream *stream, const char *m_key, const char *value);
|
|
|
|
/*!
|
|
* \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 Get rtp_codecs associated with the stream
|
|
*
|
|
* \param stream The media stream
|
|
*
|
|
* \return The rtp_codecs
|
|
*
|
|
* \since 15.5
|
|
*/
|
|
struct ast_rtp_codecs *ast_stream_get_rtp_codecs(const struct ast_stream *stream);
|
|
|
|
/*!
|
|
* \brief Set rtp_codecs associated with the stream
|
|
*
|
|
* \param stream The media stream
|
|
* \param rtp_codecs The rtp_codecs
|
|
*
|
|
* \since 15.5
|
|
*/
|
|
void ast_stream_set_rtp_codecs(struct ast_stream *stream, struct ast_rtp_codecs *rtp_codecs);
|
|
|
|
/*!
|
|
* \brief Create a resolved stream from 2 streams
|
|
* \since 18
|
|
*
|
|
* \param pending_stream The "live" stream created from an SDP,
|
|
* passed through the core, or used to create an SDP.
|
|
* \param configured_stream The static stream used to validate the pending stream.
|
|
* \param prefs A pointer to an ast_stream_codec_negotiation_prefs structure.
|
|
* \param error_message If supplied, error messages will be appended.
|
|
*
|
|
* \details
|
|
* 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.
|
|
*
|
|
* \retval NULL if there was some allocation failure.
|
|
* \retval A new, resolved stream.
|
|
*
|
|
*/
|
|
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);
|
|
|
|
/*!
|
|
* \brief Create a stream topology
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \since 15
|
|
*
|
|
* \note This returns an ao2 refcounted object
|
|
*/
|
|
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
|
|
*
|
|
* \note This returns an ao2 refcounted object
|
|
*/
|
|
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 Unreference and 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
|
|
*
|
|
* \note If the stream's name is empty, it'll be set to <stream_type>-<position>
|
|
*/
|
|
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 the number of active (non-REMOVED) streams in a topology
|
|
*
|
|
* \param topology The topology of streams
|
|
*
|
|
* \return the number of active streams
|
|
*
|
|
* \since 18
|
|
*/
|
|
int ast_stream_topology_get_active_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
|
|
*
|
|
* \note If the stream's name is empty, it'll be set to <stream_type>-<position>
|
|
*/
|
|
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 (the resulting format caps must be unreffed by the caller)
|
|
* \retval NULL failure
|
|
*
|
|
* \note The stream topology is NOT altered by this function.
|
|
*
|
|
* \since 15
|
|
*/
|
|
struct ast_format_cap *ast_stream_topology_get_formats(
|
|
struct ast_stream_topology *topology);
|
|
|
|
/*!
|
|
* \brief Get a string representing the topology for debugging/display purposes
|
|
* \since 18
|
|
*
|
|
* \param topology A stream topology
|
|
* \param buf A pointer to an ast_str* used for the output.
|
|
*
|
|
* \retval "" (empty string) if either buf or *buf are NULL
|
|
* \retval "(null topology)" if *topology was NULL
|
|
* \retval <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)>"
|
|
*
|
|
*/
|
|
const char *ast_stream_topology_to_str(const struct ast_stream_topology *topology, struct ast_str **buf);
|
|
|
|
/*!
|
|
* \brief Create a format capabilities structure containing all the formats from all the streams
|
|
* of a particular type in the topology.
|
|
* \since 18
|
|
*
|
|
* \details
|
|
* 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.
|
|
*
|
|
* \param topology The topology of streams
|
|
* \param type The media type
|
|
*
|
|
* \retval non-NULL success (the resulting format caps must be unreffed by the caller)
|
|
* \retval NULL failure
|
|
*
|
|
* \note The stream topology is NOT altered by this function.
|
|
*
|
|
*/
|
|
struct ast_format_cap *ast_stream_topology_get_formats_by_type(
|
|
struct ast_stream_topology *topology, enum ast_media_type type);
|
|
|
|
/*!
|
|
* \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);
|
|
|
|
/*!
|
|
* \brief Create a resolved stream topology from 2 topologies
|
|
* \since 18
|
|
*
|
|
* \param pending_topology The "live" topology created from an SDP,
|
|
* passed through the core, or used to create an SDP.
|
|
* \param configured_topology The static topology used to validate the pending topology.
|
|
* It MUST have only 1 stream per media type.
|
|
* \param prefs A pointer to an ast_stream_codec_negotiation_prefs structure.
|
|
* \param error_message If supplied, error messages will be appended.
|
|
*
|
|
* \details
|
|
* 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.
|
|
*
|
|
* \retval NULL if there was some allocation failure.
|
|
* \retval The joint topology.
|
|
*/
|
|
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);
|
|
|
|
/*!
|
|
* \brief Get a stack allocated string representing the topology for debugging/display purposes
|
|
*
|
|
* \param 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.
|
|
*
|
|
*/
|
|
#define ast_stream_topology_to_stra(__topology) ast_str_tmp(256, ast_stream_topology_to_str(__topology, &STR_TMP))
|
|
|
|
#endif /* _AST_STREAM_H */
|