RTCP Session and Encapsulation (RFC 3550)
[Media Sessions]

---

Detailed Description

PJMEDIA implements subsets of RTCP specification (RFC 3550) to monitor the quality of the real-time media (audio/video) transmission. In addition to the standard quality monitoring and reporting with RTCP SR and RR types, PJMEDIA's RTCP implementation is able to report extended statistics for incoming streams, such as packet duplications, reorder, discarded, and loss period (to distinguish between random and burst loss).

The bidirectional media quality statistic is represented with pjmedia_rtcp_stat structure.

When application uses the stream interface (see Streams), application may retrieve the RTCP statistic by calling pjmedia_stream_get_stat() function.

Data Structures
struct	pjmedia_rtcp_sr
struct	pjmedia_rtcp_rr
struct	pjmedia_rtcp_common
struct	pjmedia_rtcp_sr_pkt
struct	pjmedia_rtcp_rr_pkt
struct	pjmedia_rtcp_ntp_rec
struct	pjmedia_rtcp_stream_stat
struct	pjmedia_rtcp_stat
struct	pjmedia_rtcp_session
Typedefs
typedef struct pjmedia_rtcp_sr	pjmedia_rtcp_sr
typedef struct pjmedia_rtcp_rr	pjmedia_rtcp_rr
typedef struct pjmedia_rtcp_common	pjmedia_rtcp_common
typedef struct pjmedia_rtcp_ntp_rec	pjmedia_rtcp_ntp_rec
typedef struct pjmedia_rtcp_stream_stat	pjmedia_rtcp_stream_stat
typedef struct pjmedia_rtcp_stat	pjmedia_rtcp_stat
typedef struct pjmedia_rtcp_session	pjmedia_rtcp_session
Functions
void	pjmedia_rtcp_init (pjmedia_rtcp_session *session, char *name, unsigned clock_rate, unsigned samples_per_frame, pj_uint32_t ssrc)
pj_status_t	pjmedia_rtcp_get_ntp_time (const pjmedia_rtcp_session *sess, pjmedia_rtcp_ntp_rec *ntp)
void	pjmedia_rtcp_fini (pjmedia_rtcp_session *session)
void	pjmedia_rtcp_rx_rtp (pjmedia_rtcp_session *session, unsigned seq, unsigned ts, unsigned payload)
void	pjmedia_rtcp_rx_rtp2 (pjmedia_rtcp_session *session, unsigned seq, unsigned ts, unsigned payload, pj_bool_t discarded)
void	pjmedia_rtcp_tx_rtp (pjmedia_rtcp_session *session, unsigned ptsize)
void	pjmedia_rtcp_rx_rtcp (pjmedia_rtcp_session *session, const void *rtcp_pkt, pj_size_t size)
void	pjmedia_rtcp_build_rtcp (pjmedia_rtcp_session *session, void **rtcp_pkt, int *len)
pj_status_t	pjmedia_rtcp_enable_xr (pjmedia_rtcp_session *session, pj_bool_t enable)

---

Typedef Documentation

typedef struct pjmedia_rtcp_sr pjmedia_rtcp_sr

See also:

pjmedia_rtcp_sr

typedef struct pjmedia_rtcp_rr pjmedia_rtcp_rr

See also:

pjmedia_rtcp_rr

typedef struct pjmedia_rtcp_common pjmedia_rtcp_common

See also:

pjmedia_rtcp_common

typedef struct pjmedia_rtcp_ntp_rec pjmedia_rtcp_ntp_rec

See also:

pjmedia_rtcp_ntp_rec

typedef struct pjmedia_rtcp_stream_stat pjmedia_rtcp_stream_stat

See also:

pjmedia_rtcp_stream_stat

typedef struct pjmedia_rtcp_stat pjmedia_rtcp_stat

See also:

pjmedia_rtcp_stat

typedef struct pjmedia_rtcp_session pjmedia_rtcp_session

See also:

pjmedia_rtcp_session

---

Function Documentation

void pjmedia_rtcp_init	(	pjmedia_rtcp_session *	session,
		char *	name,
		unsigned	clock_rate,
		unsigned	samples_per_frame,
		pj_uint32_t	ssrc
	)

Initialize RTCP session.

Parameters:

	session	The session
	name	Optional name to identify the session (for logging purpose).
	clock_rate	Codec clock rate in samples per second.
	samples_per_frame	Average number of samples per frame.
	ssrc	The SSRC used in to identify the session.

pj_status_t pjmedia_rtcp_get_ntp_time	(	const pjmedia_rtcp_session *	sess,
		pjmedia_rtcp_ntp_rec *	ntp
	)

Utility function to retrieve current NTP timestamp.

Parameters:

	sess	RTCP session.
	ntp	NTP record.

Returns:

PJ_SUCCESS on success.

void pjmedia_rtcp_fini

(

pjmedia_rtcp_session *

session

)

Deinitialize RTCP session.

Parameters:

session

The session.

void pjmedia_rtcp_rx_rtp	(	pjmedia_rtcp_session *	session,
		unsigned	seq,
		unsigned	ts,
		unsigned	payload
	)

Call this function everytime an RTP packet is received to let the RTCP session do its internal calculations.

Parameters:

	session	The session.
	seq	The RTP packet sequence number, in host byte order.
	ts	The RTP packet timestamp, in host byte order.
	payload	Size of the payload.

void pjmedia_rtcp_rx_rtp2	(	pjmedia_rtcp_session *	session,
		unsigned	seq,
		unsigned	ts,
		unsigned	payload,
		pj_bool_t	discarded
	)

Call this function everytime an RTP packet is received to let the RTCP session do its internal calculations.

Parameters:

	session	The session.
	seq	The RTP packet sequence number, in host byte order.
	ts	The RTP packet timestamp, in host byte order.
	payload	Size of the payload.
	discarded	Flag to specify whether the packet is discarded.

void pjmedia_rtcp_tx_rtp	(	pjmedia_rtcp_session *	session,
		unsigned	ptsize
	)

Call this function everytime an RTP packet is sent to let the RTCP session do its internal calculations.

Parameters:

	session	The session.
	ptsize	The payload size of the RTP packet (ie packet minus RTP header) in bytes.

void pjmedia_rtcp_rx_rtcp	(	pjmedia_rtcp_session *	session,
		const void *	rtcp_pkt,
		pj_size_t	size
	)

Call this function when an RTCP packet is received from remote peer. This RTCP packet received from remote is used to calculate the end-to- end delay of the network.

Parameters:

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

void pjmedia_rtcp_build_rtcp	(	pjmedia_rtcp_session *	session,
		void **	rtcp_pkt,
		int *	len
	)

Build a RTCP packet to be transmitted to remote RTP peer. This will create RTCP Sender Report (SR) or Receiver Report (RR) depending on whether the endpoint has been transmitting RTP since the last interval. Note that this function will reset the interval counters (such as the ones to calculate fraction lost) in the session.

Parameters:

	session	The RTCP session.
	rtcp_pkt	Upon return, it will contain pointer to the RTCP packet, which can be RTCP SR or RR.
	len	Upon return, it will indicate the size of the RTCP packet.

pj_status_t pjmedia_rtcp_enable_xr	(	pjmedia_rtcp_session *	session,
		pj_bool_t	enable
	)

Call this function if RTCP XR needs to be enabled/disabled in the RTCP session.

Parameters:

	session	The RTCP session.
	enable	Enable/disable RTCP XR.

Returns:

PJ_SUCCESS on success.