uvgrtp::media_stream Class Reference

The media_stream is an entity which represents one RTP stream. More...

#include <media_stream.hh>

Public Member Functions
rtp_error_t	start_zrtp ()
	Start the ZRTP negotiation manually.
rtp_error_t	add_srtp_ctx (uint8_t *key, uint8_t *salt)
	Add keying information for user-managed SRTP session.
rtp_error_t	push_frame (uint8_t *data, size_t data_len, int rtp_flags)
	Send data to remote participant with a custom timestamp.
rtp_error_t	push_frame (std::unique_ptr< uint8_t[]> data, size_t data_len, int rtp_flags)
	Send data to remote participant with a custom timestamp.
rtp_error_t	push_frame (uint8_t *data, size_t data_len, uint32_t ts, int rtp_flags)
	Send data to remote participant with a custom timestamp.
rtp_error_t	push_frame (uint8_t *data, size_t data_len, uint32_t ts, uint64_t ntp_ts, int rtp_flags)
	Send data to remote participant with custom RTP and NTP timestamps.
rtp_error_t	push_frame (std::unique_ptr< uint8_t[]> data, size_t data_len, uint32_t ts, int rtp_flags)
	Send data to remote participant with a custom timestamp.
rtp_error_t	push_frame (std::unique_ptr< uint8_t[]> data, size_t data_len, uint32_t ts, uint64_t ntp_ts, int rtp_flags)
	Send data to remote participant with custom RTP and NTP timestamps.
uvgrtp::frame::rtp_frame *	pull_frame ()
	Poll a frame indefinitely from the media stream object.
uvgrtp::frame::rtp_frame *	pull_frame (size_t timeout_ms)
	Poll a frame for a specified time from the media stream object.
rtp_error_t	install_receive_hook (void *arg, void(*hook)(void *, uvgrtp::frame::rtp_frame *))
	Asynchronous way of getting frames.
rtp_error_t	configure_ctx (int rcc_flag, ssize_t value)
	Configure the media stream, see RTP_CTX_CONFIGURATION_FLAGS for more details.
int	get_configuration_value (int rcc_flag)
	Get the values associated with configuration flags, see RTP_CTX_CONFIGURATION_FLAGS for more details.
uvgrtp::rtcp *	get_rtcp ()
	Get pointer to the RTCP object of the media stream.
uint32_t	get_ssrc () const
	Get SSRC identifier. You can use the SSRC value for example to find the report block belonging to this media_stream in RTCP sender/receiver report.

Detailed Description

The media_stream is an entity which represents one RTP stream.

media_stream is defined by the ports which are used for sending and/or receiving media. It is possible for media_stream to be bi- or unidirectional. The unidirectionality is achieved by specifying RCE_SEND_ONLY or RCE_RECEIVE_ONLY flag when creating media_stream.

If RCE_RTCP was given when creating media_stream, you can get the uvgrtp::rtcp object with get_rtcp()-function.

media_stream corresponds to one RTP session in RFC 3550.

Definition at line 53 of file media_stream.hh.

Member Function Documentation

add_srtp_ctx()

rtp_error_t uvgrtp::media_stream::add_srtp_ctx	(	uint8_t *	key,
		uint8_t *	salt )

Add keying information for user-managed SRTP session.

For user-managed SRTP session (flag RCE_SRTP_KMNGMNT_USER), the media stream is not started until SRTP key has been added and all calls to push_frame() will fail.

Parameters

key	SRTP master key, default is 128-bit long
salt	112-bit long salt

Returns

RTP error code

Return values

RTP_OK	On success
RTP_INVALID_VALUE	If key or salt is invalid
RTP_NOT_SUPPORTED	If user-managed SRTP was not specified in create_stream()

configure_ctx()

rtp_error_t uvgrtp::media_stream::configure_ctx	(	int	rcc_flag,
		ssize_t	value )

Configure the media stream, see RTP_CTX_CONFIGURATION_FLAGS for more details.

Returns

RTP error code

Return values

RTP_OK	On success
RTP_INVALID_VALUE	If the provided value is not valid for a given configuration flag
RTP_GENERIC_ERROR	If setsockopt(2) failed

get_configuration_value()

int uvgrtp::media_stream::get_configuration_value

(

int

rcc_flag

)

Get the values associated with configuration flags, see RTP_CTX_CONFIGURATION_FLAGS for more details.

Returns

Value of the configuration flag

Return values

int	value on success
-1	on error

get_rtcp()

uvgrtp::rtcp * uvgrtp::media_stream::get_rtcp

(

)

Get pointer to the RTCP object of the media stream.

This object is used to control all RTCP-related functionality and RTCP documentation can be found from uvgrtp::rtcp

Returns

Pointer to RTCP object

Return values

uvgrtp::rtcp*	If RTCP has been enabled (RCE_RTCP has been given to uvgrtp::session::create_stream())
nullptr	If RTCP has not been enabled

get_ssrc()

uint32_t uvgrtp::media_stream::get_ssrc

(

)

const

Get SSRC identifier. You can use the SSRC value for example to find the report block belonging to this media_stream in RTCP sender/receiver report.

Returns

SSRC value

install_receive_hook()

rtp_error_t uvgrtp::media_stream::install_receive_hook	(	void *	arg,
		void(*	hook )(void *, uvgrtp::frame::rtp_frame *) )

Asynchronous way of getting frames.

Receive hook is an alternative to polling frames using uvgrtp::media_stream::pull_frame(). Instead of application asking from uvgRTP if there are any new frames available, uvgRTP will notify the application when a frame has been received

The hook should not be used for media processing as it will block the receiver from reading more frames. Instead, it should only be used as an interface between uvgRTP and the calling application where the frame hand-off happens.

Parameters

arg	Optional argument that is passed to the hook when it is called, can be set to nullptr
hook	Function pointer to the receive hook that uvgRTP should call

Returns

RTP error code

Return values

RTP_OK	On success
RTP_INVALID_VALUE	If hook is nullptr

pull_frame() [1/2]

uvgrtp::frame::rtp_frame * uvgrtp::media_stream::pull_frame

(

)

Poll a frame indefinitely from the media stream object.

Returns

RTP frame

Return values

uvgrtp::frame::rtp_frame*	On success
nullptr	If an unrecoverable error happened

pull_frame() [2/2]

uvgrtp::frame::rtp_frame * uvgrtp::media_stream::pull_frame

(

size_t

timeout_ms

)

Poll a frame for a specified time from the media stream object.

Parameters

timeout_ms

How long is a frame waited, in milliseconds

Returns

RTP frame

Return values

uvgrtp::frame::rtp_frame*	On success
nullptr	If a frame was not received within the specified time limit or in case of an error

push_frame() [1/6]

rtp_error_t uvgrtp::media_stream::push_frame	(	std::unique_ptr< uint8_t[]>	data,
		size_t	data_len,
		int	rtp_flags )

Send data to remote participant with a custom timestamp.

If so specified either by the selected media format and/or given RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1492 bytes, or to any other size defined by the application using RCC_MTU_SIZE

The frame is automatically reconstructed by the receiver if all fragments have been received successfully.

Parameters

data	Smart pointer to data the that should be sent
data_len	Length of data
rtp_flags	Optional flags, see RTP_FLAGS for more details

Returns

RTP error code

Return values

RTP_OK	On success
RTP_INVALID_VALUE	If one of the parameters are invalid
RTP_MEMORY_ERROR	If the data chunk is too large to be processed
RTP_SEND_ERROR	If uvgRTP failed to send the data to remote
RTP_GENERIC_ERROR	If an unspecified error occurred

push_frame() [2/6]

rtp_error_t uvgrtp::media_stream::push_frame	(	std::unique_ptr< uint8_t[]>	data,
		size_t	data_len,
		uint32_t	ts,
		int	rtp_flags )

Send data to remote participant with a custom timestamp.

If so specified either by the selected media format and/or given RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1492 bytes, or to any other size defined by the application using RCC_MTU_SIZE

The frame is automatically reconstructed by the receiver if all fragments have been received successfully.

If application so wishes, it may override uvgRTP's own timestamp calculations and provide timestamping information for the stream itself. This requires that the application provides a sensible value for the ts parameter. If RTCP has been enabled, uvgrtp::rtcp::set_ts_info() should have been called.

Parameters

data	Smart pointer to data the that should be sent
data_len	Length of data
ts	32-bit timestamp value for the data
rtp_flags	Optional flags, see RTP_FLAGS for more details

Returns

RTP error code

Return values

RTP_OK	On success
RTP_INVALID_VALUE	If one of the parameters are invalid
RTP_MEMORY_ERROR	If the data chunk is too large to be processed
RTP_SEND_ERROR	If uvgRTP failed to send the data to remote
RTP_GENERIC_ERROR	If an unspecified error occurred

push_frame() [3/6]

rtp_error_t uvgrtp::media_stream::push_frame	(	std::unique_ptr< uint8_t[]>	data,
		size_t	data_len,
		uint32_t	ts,
		uint64_t	ntp_ts,
		int	rtp_flags )

Send data to remote participant with custom RTP and NTP timestamps.

If so specified either by the selected media format and/or given RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1492 bytes, or to any other size defined by the application using RCC_MTU_SIZE

The frame is automatically reconstructed by the receiver if all fragments have been received successfully.

If application so wishes, it may override uvgRTP's own timestamp calculations and provide timestamping information for the stream itself. This requires that the application provides a sensible value for the ts parameter. If RTCP has been enabled, uvgrtp::rtcp::set_ts_info() should have been called.

Parameters

data	Smart pointer to data the that should be sent
data_len	Length of data
ts	32-bit RTP timestamp for the packet
ntp_ts	64-bit NTP timestamp value of when the packets data was sampled. NTP timestamp is a 64-bit unsigned fixed-point number with the integer part (seconds) in the first 32 bits and the fractional part (fractional seconds) in the last 32 bits. Used for synchronizing multiple streams.
rtp_flags	Optional flags, see RTP_FLAGS for more details

Returns

RTP error code

Return values

RTP_OK	On success
RTP_INVALID_VALUE	If one of the parameters are invalid
RTP_MEMORY_ERROR	If the data chunk is too large to be processed
RTP_SEND_ERROR	If uvgRTP failed to send the data to remote
RTP_GENERIC_ERROR	If an unspecified error occurred

push_frame() [4/6]

rtp_error_t uvgrtp::media_stream::push_frame	(	uint8_t *	data,
		size_t	data_len,
		int	rtp_flags )

Send data to remote participant with a custom timestamp.

If so specified either by the selected media format and/or given RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1492 bytes, or to any other size defined by the application using RCC_MTU_SIZE

The frame is automatically reconstructed by the receiver if all fragments have been received successfully.

Parameters

data	Pointer to data the that should be sent, uvgRTP does not take ownership of the memory
data_len	Length of data
rtp_flags	Optional flags, see RTP_FLAGS for more details

Returns

RTP error code

Return values

RTP_OK	On success
RTP_INVALID_VALUE	If one of the parameters are invalid
RTP_MEMORY_ERROR	If the data chunk is too large to be processed
RTP_SEND_ERROR	If uvgRTP failed to send the data to remote
RTP_GENERIC_ERROR	If an unspecified error occurred

push_frame() [5/6]

rtp_error_t uvgrtp::media_stream::push_frame	(	uint8_t *	data,
		size_t	data_len,
		uint32_t	ts,
		int	rtp_flags )

Send data to remote participant with a custom timestamp.

If so specified either by the selected media format and/or given RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1492 bytes, or to any other size defined by the application using RCC_MTU_SIZE

The frame is automatically reconstructed by the receiver if all fragments have been received successfully.

If application so wishes, it may override uvgRTP's own timestamp calculations and provide timestamping information for the stream itself. This requires that the application provides a sensible value for the ts parameter. If RTCP has been enabled, uvgrtp::rtcp::set_ts_info() should have been called.

Parameters

data	Pointer to data the that should be sent, uvgRTP does not take ownership of the memory
data_len	Length of data
ts	32-bit timestamp value for the data
rtp_flags	Optional flags, see RTP_FLAGS for more details

Returns

RTP error code

Return values

RTP_OK	On success
RTP_INVALID_VALUE	If one of the parameters are invalid
RTP_MEMORY_ERROR	If the data chunk is too large to be processed
RTP_SEND_ERROR	If uvgRTP failed to send the data to remote
RTP_GENERIC_ERROR	If an unspecified error occurred

push_frame() [6/6]

rtp_error_t uvgrtp::media_stream::push_frame	(	uint8_t *	data,
		size_t	data_len,
		uint32_t	ts,
		uint64_t	ntp_ts,
		int	rtp_flags )

Send data to remote participant with custom RTP and NTP timestamps.

If so specified either by the selected media format and/or given RTP_CTX_ENABLE_FLAGS, uvgRTP fragments the input data into RTP packets of 1492 bytes, or to any other size defined by the application using RCC_MTU_SIZE

The frame is automatically reconstructed by the receiver if all fragments have been received successfully.

If application so wishes, it may override uvgRTP's own timestamp calculations and provide timestamping information for the stream itself. This requires that the application provides a sensible value for the ts parameter. If RTCP has been enabled, uvgrtp::rtcp::set_ts_info() should have been called.

Parameters

data	Pointer to data the that should be sent, uvgRTP does not take ownership of the memory
data_len	Length of data
ts	32-bit RTP timestamp for the packet
ntp_ts	64-bit NTP timestamp value of when the packets data was sampled. NTP timestamp is a 64-bit unsigned fixed-point number with the integer part (seconds) in the first 32 bits and the fractional part (fractional seconds) in the last 32 bits. Used for synchronizing multiple streams.
rtp_flags	Optional flags, see RTP_FLAGS for more details

Returns

RTP error code

Return values

RTP_OK	On success
RTP_INVALID_VALUE	If one of the parameters are invalid
RTP_MEMORY_ERROR	If the data chunk is too large to be processed
RTP_SEND_ERROR	If uvgRTP failed to send the data to remote
RTP_GENERIC_ERROR	If an unspecified error occurred

start_zrtp()

rtp_error_t uvgrtp::media_stream::start_zrtp

(

)

Start the ZRTP negotiation manually.

There is two ways to use ZRTP.

1. Use flags RCE_SRTP + RCE_SRTP_KMNGMNT_ZRTP + (RCE_ZRTP_DIFFIE_HELLMAN_MODE/RCE_ZRTP_MULTISTREAM_MODE) to automatically start ZRTP negotiation when creating a media stream.
2. Use flags RCE_SRTP + (RCE_ZRTP_DIFFIE_HELLMAN_MODE/RCE_ZRTP_MULTISTREAM_MODE) and after creating the media stream, call start_zrtp() to manually start the ZRTP negotiation

Returns

RTP error code

Return values

RTP_OK	On success
RTP_TIMEOUT	if ZRTP timed out
RTP_GENERIC_ERROR	on other errors

---

The documentation for this class was generated from the following file:

• media_stream.hh