RTCP Extended Report (XR) - RFC 3611
[Media Sessions]

---

Detailed Description

PJMEDIA implements subsets of RTCP XR specification (RFC 3611) to monitor the quality of the real-time media (audio/video) transmission.

Data Structures
struct	pjmedia_rtcp_xr_rb_header
struct	pjmedia_rtcp_xr_rb_rr_time
struct	pjmedia_rtcp_xr_rb_dlrr_item
struct	pjmedia_rtcp_xr_rb_dlrr
struct	pjmedia_rtcp_xr_rb_stats
struct	pjmedia_rtcp_xr_rb_voip_mtc
struct	pjmedia_rtcp_xr_pkt
struct	pjmedia_rtcp_xr_stream_stat
struct	pjmedia_rtcp_xr_stat
struct	pjmedia_rtcp_xr_session
Typedefs
typedef struct pjmedia_rtcp_xr_session	pjmedia_rtcp_xr_session
Enumerations
enum	pjmedia_rtcp_xr_type {   PJMEDIA_RTCP_XR_LOSS_RLE = (1 << 0),   PJMEDIA_RTCP_XR_DUP_RLE = (1 << 1),   PJMEDIA_RTCP_XR_RCPT_TIMES = (1 << 2),   PJMEDIA_RTCP_XR_RR_TIME = (1 << 3),   PJMEDIA_RTCP_XR_DLRR = (1 << 4),   PJMEDIA_RTCP_XR_STATS = (1 << 5),   PJMEDIA_RTCP_XR_VOIP_METRICS = (1 << 6) }
enum	pjmedia_rtcp_xr_info {   PJMEDIA_RTCP_XR_INFO_SIGNAL_LVL = 1,   PJMEDIA_RTCP_XR_INFO_NOISE_LVL = 2,   PJMEDIA_RTCP_XR_INFO_RERL = 3,   PJMEDIA_RTCP_XR_INFO_R_FACTOR = 4,   PJMEDIA_RTCP_XR_INFO_MOS_LQ = 5,   PJMEDIA_RTCP_XR_INFO_MOS_CQ = 6,   PJMEDIA_RTCP_XR_INFO_CONF_PLC = 7,   PJMEDIA_RTCP_XR_INFO_CONF_JBA = 8,   PJMEDIA_RTCP_XR_INFO_CONF_JBR = 9,   PJMEDIA_RTCP_XR_INFO_JB_NOM = 10,   PJMEDIA_RTCP_XR_INFO_JB_MAX = 11,   PJMEDIA_RTCP_XR_INFO_JB_ABS_MAX = 12 }
enum	pjmedia_rtcp_xr_plc_type {   PJMEDIA_RTCP_XR_PLC_UNK = 0,   PJMEDIA_RTCP_XR_PLC_DIS = 1,   PJMEDIA_RTCP_XR_PLC_ENH = 2,   PJMEDIA_RTCP_XR_PLC_STD = 3 }
enum	pjmedia_rtcp_xr_jb_type {   PJMEDIA_RTCP_XR_JB_UNKNOWN = 0,   PJMEDIA_RTCP_XR_JB_FIXED = 2,   PJMEDIA_RTCP_XR_JB_ADAPTIVE = 3 }
Functions
void	pjmedia_rtcp_build_rtcp_xr (pjmedia_rtcp_xr_session *session, unsigned rpt_types, void **rtcp_pkt, int *len)
pj_status_t	pjmedia_rtcp_xr_update_info (pjmedia_rtcp_xr_session *session, unsigned info, pj_int32_t val)
void	pjmedia_rtcp_xr_init (pjmedia_rtcp_xr_session *session, struct pjmedia_rtcp_session *r_session, pj_uint8_t gmin, unsigned frames_per_packet)
void	pjmedia_rtcp_xr_fini (pjmedia_rtcp_xr_session *session)
void	pjmedia_rtcp_xr_rx_rtcp_xr (pjmedia_rtcp_xr_session *session, const void *rtcp_xr_pkt, pj_size_t size)
void	pjmedia_rtcp_xr_rx_rtp (pjmedia_rtcp_xr_session *session, unsigned seq, int lost, int dup, int discarded, int jitter, int toh, pj_bool_t toh_ipv4)
void	pjmedia_rtcp_xr_tx_rtp (pjmedia_rtcp_xr_session *session, unsigned ptsize)

---

Enumeration Type Documentation

enum pjmedia_rtcp_xr_type

Enumeration of report types of RTCP XR. Useful for user to enable varying combinations of RTCP XR report blocks.

enum pjmedia_rtcp_xr_info

Enumeration of info need to be updated manually to RTCP XR. Most info could be updated automatically each time RTP received.

enum pjmedia_rtcp_xr_plc_type

Enumeration of PLC types definitions for RTCP XR report.

enum pjmedia_rtcp_xr_jb_type

Enumeration of jitter buffer types definitions for RTCP XR report.

---

Function Documentation

void pjmedia_rtcp_build_rtcp_xr	(	pjmedia_rtcp_xr_session *	session,
		unsigned	rpt_types,
		void **	rtcp_pkt,
		int *	len
	)

Build an RTCP XR packet which contains one or more RTCP XR report blocks. There are seven report types as defined in RFC 3611.

Parameters:

	session	The RTCP XR session.
	rpt_types	Report types to be included in the packet, report types are defined in pjmedia_rtcp_xr_type, set this to zero will make this function build all reports appropriately.
	rtcp_pkt	Upon return, it will contain pointer to the RTCP XR packet.
	len	Upon return, it will indicate the size of the generated RTCP XR packet.

pj_status_t pjmedia_rtcp_xr_update_info	(	pjmedia_rtcp_xr_session *	session,
		unsigned	info,
		pj_int32_t	val
	)

Call this function to manually update some info needed by RTCP XR to generate report which could not be populated directly when receiving RTP.

Parameters:

	session	The RTCP XR session.
	info	Info type to be updated,

See also:

pjmedia_rtcp_xr_info.

Parameters:

val

Value.

void pjmedia_rtcp_xr_init	(	pjmedia_rtcp_xr_session *	session,
		struct pjmedia_rtcp_session *	r_session,
		pj_uint8_t	gmin,
		unsigned	frames_per_packet
	)

This function is called internally by RTCP session when RTCP XR is enabled to initialize the RTCP XR session.

Parameters:

	session	RTCP XR session.
	r_session	RTCP session.
	gmin	Gmin value (defined in RFC 3611), set to 0 for default (16).
	ptime	Packet time.
	frames_per_packet	Number of frames per packet.

void pjmedia_rtcp_xr_fini

(

pjmedia_rtcp_xr_session *

session

)

This function is called internally by RTCP session to destroy the RTCP XR session.

Parameters:

session

RTCP XR session.

void pjmedia_rtcp_xr_rx_rtcp_xr	(	pjmedia_rtcp_xr_session *	session,
		const void *	rtcp_xr_pkt,
		pj_size_t	size
	)

This function is called internally by RTCP session when it receives incoming RTCP XR packets.

Parameters:

	session	RTCP XR session.
	rtcp_pkt	The received RTCP XR packet.
	size	Size of the incoming packet.

void pjmedia_rtcp_xr_rx_rtp	(	pjmedia_rtcp_xr_session *	session,
		unsigned	seq,
		int	lost,
		int	dup,
		int	discarded,
		int	jitter,
		int	toh,
		pj_bool_t	toh_ipv4
	)

This function is called internally by RTCP session whenever an RTP packet is received or lost to let the RTCP XR session update its statistics. Data passed to this function is a result of analyzation by RTCP and the jitter buffer. Whenever some info is available, the value should be zero or more (no negative info), otherwise if info is not available the info should be -1 so no update will be done for this info in the RTCP XR session.

Parameters:

	session	RTCP XR session.
	seq	Sequence number of RTP packet.
	lost	Info if this packet is lost.
	dup	Info if this packet is a duplication.
	discarded	Info if this packet is discarded (not because of duplication).
	jitter	Info jitter of this packet.
	toh	Info Time To Live or Hops Limit of this packet.
	toh_ipv4	Set PJ_TRUE if packet is transported over IPv4.

void pjmedia_rtcp_xr_tx_rtp	(	pjmedia_rtcp_xr_session *	session,
		unsigned	ptsize
	)

This function is called internally by RTCP session whenever an RTP packet is sent to let the RTCP XR session do its internal calculations.

Parameters:

	session	RTCP XR session.
	ptsize	Size of RTP payload being sent.