Unified receive path for RTCP and backchannel RTP data. More...

#include <compy/droppable.h>
#include <compy/rtcp.h>
#include <compy/types/rtp.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <interface99.h>
#include <slice99.h>
#include <compy/priv/compiler_attrs.h>

Include dependency graph for receiver.h:

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

Go to the source code of this file.

Macros
#define	Compy_AudioReceiver_IFACE
	Application callback interface for receiving backchannel audio data.

#define	COMPY_CHANNEL_RTCP 0

#define	COMPY_CHANNEL_RTP 1

Typedefs
typedef struct Compy_RtpReceiver	Compy_RtpReceiver

Functions
	interface99 (Compy_AudioReceiver)

Compy_RtpReceiver *	Compy_RtpReceiver_new (Compy_Rtcp *rtcp, Compy_AudioReceiver audio_receiver) COMPY_PRIV_MUST_USE
	Creates a new RTP receiver for demuxing incoming data.

int	Compy_RtpReceiver_feed (Compy_RtpReceiver self, uint8_t channel_type, const uint8_t data, size_t len)
	Feeds raw received data into the receiver for demuxing.

int	Compy_RtpReceiver_feed_at (Compy_RtpReceiver self, uint8_t channel_type, const uint8_t data, size_t len, int64_t arrival_us)
	Compy_RtpReceiver_feed with the packet's arrival instant, which enables the reception statistics behind Compy_RtpReceiver_write_rr: interarrival jitter (RFC 3550 A.8) and the DLSR field measured from snooped sender reports.

void	Compy_RtpReceiver_set_clock_rate (Compy_RtpReceiver *self, uint32_t clock_rate)
	Sets the RTP clock rate used to convert arrival instants into timestamp units for jitter (RFC 3550 §6.4.1).

ssize_t	Compy_RtpReceiver_write_rr (Compy_RtpReceiver self, uint32_t reporter_ssrc, int64_t now_us, const char cname, uint8_t *buf, size_t cap)
	Writes an RTCP receiver report (RFC 3550 §6.4.2) about the RTP stream this receiver has been fed, followed by an SDES CNAME chunk when `cname` != NULL (making the packet a compliant compound).

ssize_t	Compy_RtpReceiver_write_bye (Compy_RtpReceiver self, uint32_t reporter_ssrc, int64_t now_us, const char cname, uint8_t *buf, size_t cap)
	Writes the leave compound (RFC 3550 §6.3.7): the same report Compy_RtpReceiver_write_rr produces, with a BYE for `reporter_ssrc` appended as the compound's final packet.

	declImplExtern99 (Compy_Droppable, Compy_RtpReceiver)

Detailed Description

Unified receive path for RTCP and backchannel RTP data.

Provides the #Compy_AudioReceiver interface for applications to receive backchannel audio, and the Compy_RtpReceiver demuxer that routes incoming data to either RTCP handling or audio callbacks.

Macro Definition Documentation

◆ Compy_AudioReceiver_IFACE

#define Compy_AudioReceiver_IFACE

Value:

    vfunc99(                                                                   \
        void, on_audio, VSelf99, uint8_t payload_type, uint32_t timestamp,     \
        uint32_t ssrc, U8Slice99 payload)

Application callback interface for receiving backchannel audio data.

See Interface99 for the macro usage.

Function Documentation

◆ Compy_RtpReceiver_feed()

int Compy_RtpReceiver_feed	(	Compy_RtpReceiver *	self,
		uint8_t	channel_type,
		const uint8_t *	data,
		size_t	len
	)

Feeds raw received data into the receiver for demuxing.

Parameters

[in]	self	The receiver.
[in]	channel_type	Either COMPY_CHANNEL_RTCP or COMPY_CHANNEL_RTP.
[in]	data	The raw packet data.
[in]	len	Length of `data`.

Precondition: self != NULL; data != NULL

Returns: 0 on success, -1 on parse error.

◆ Compy_RtpReceiver_feed_at()

int Compy_RtpReceiver_feed_at	(	Compy_RtpReceiver *	self,
		uint8_t	channel_type,
		const uint8_t *	data,
		size_t	len,
		int64_t	arrival_us
	)

Compy_RtpReceiver_feed with the packet's arrival instant, which enables the reception statistics behind Compy_RtpReceiver_write_rr: interarrival jitter (RFC 3550 A.8) and the DLSR field measured from snooped sender reports.

Plain Compy_RtpReceiver_feed is this call with arrival_us = 0, which records sequence accounting only.

The application is the clock owner (Compy never samples one): arrival_us must be a monotonic microsecond instant.

◆ Compy_RtpReceiver_new()

Compy_RtpReceiver * Compy_RtpReceiver_new	(	Compy_Rtcp *	rtcp,
		Compy_AudioReceiver	audio_receiver
	)

Creates a new RTP receiver for demuxing incoming data.

Parameters

[in]	rtcp	The RTCP session for handling incoming RTCP. May be NULL.
[in]	audio_receiver	The audio callback for backchannel data. The `.self` field may be NULL if no backchannel is configured.

◆ Compy_RtpReceiver_set_clock_rate()

void Compy_RtpReceiver_set_clock_rate	(	Compy_RtpReceiver *	self,
		uint32_t	clock_rate
	)

Sets the RTP clock rate used to convert arrival instants into timestamp units for jitter (RFC 3550 §6.4.1).

Defaults to 8000. On a multi-format media section, pick the offer's baseline format; jitter is only exact while the sender uses that format, while every other RR field is sequence-based and format-independent.

◆ Compy_RtpReceiver_write_bye()

ssize_t Compy_RtpReceiver_write_bye	(	Compy_RtpReceiver *	self,
		uint32_t	reporter_ssrc,
		int64_t	now_us,
		const char *	cname,
		uint8_t *	buf,
		size_t	cap
	)

Writes the leave compound (RFC 3550 §6.3.7): the same report Compy_RtpReceiver_write_rr produces, with a BYE for reporter_ssrc appended as the compound's final packet.

Send it once, when the reporting participant leaves the session.

Returns: As Compy_RtpReceiver_write_rr — in particular 0 when no RTP was ever seen, in which case no report was ever sent and no BYE is owed.

◆ Compy_RtpReceiver_write_rr()

ssize_t Compy_RtpReceiver_write_rr	(	Compy_RtpReceiver *	self,
		uint32_t	reporter_ssrc,
		int64_t	now_us,
		const char *	cname,
		uint8_t *	buf,
		size_t	cap
	)

Writes an RTCP receiver report (RFC 3550 §6.4.2) about the RTP stream this receiver has been fed, followed by an SDES CNAME chunk when cname != NULL (making the packet a compliant compound).

Interval fields (fraction lost) cover the span since the previous call. LSR/DLSR come from the last snooped sender report, or read 0 when none has been seen, as the RFC prescribes.

Returns: The number of bytes written, 0 when no RTP has been seen yet (nothing to report), or -1 when cap is too small.

Precondition: self != NULL; buf != NULL

Macros

Typedefs

Functions