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

---

Detailed Description

The RTP module is designed to be dependent only to PJLIB, it does not depend on any other parts of PJMEDIA library. The RTP module does not even depend on any transports (sockets), to promote even more use, such as in DSP development (where transport may be handled by different processor).

An RTCP implementation is available, in separate module. Please see RTCP Session and Encapsulation (RFC 3550).

The functions that are provided by this module:

• creating RTP header for each outgoing packet.
• decoding RTP packet into RTP header and payload.
• provide simple RTP session management (sequence number, etc.)

The RTP module does not use any dynamic memory at all.

How to Use the RTP Module

First application must call pjmedia_rtp_session_init() to initialize the RTP session.

When application wants to send RTP packet, it needs to call pjmedia_rtp_encode_rtp() to build the RTP header. Note that this WILL NOT build the complete RTP packet, but instead only the header. Application can then either concatenate the header with the payload, or send the two fragments (the header and the payload) using scatter-gather transport API (e.g. sendv()).

When application receives an RTP packet, first it should call pjmedia_rtp_decode_rtp to decode RTP header and payload, then it should call pjmedia_rtp_session_update to check whether we can process the RTP payload, and to let the RTP session updates its internal status. The decode function is guaranteed to point the payload to the correct position regardless of any options present in the RTP packet.

Data Structures
struct	pjmedia_rtp_hdr
struct	pjmedia_rtp_ext_hdr
struct	pjmedia_rtp_dtmf_event
struct	pjmedia_rtp_seq_session
struct	pjmedia_rtp_session
struct	pjmedia_rtp_status
struct	pjmedia_rtp_session_setting
Typedefs
typedef struct pjmedia_rtp_hdr	pjmedia_rtp_hdr
typedef struct pjmedia_rtp_ext_hdr	pjmedia_rtp_ext_hdr
typedef struct pjmedia_rtp_dtmf_event	pjmedia_rtp_dtmf_event
typedef struct pjmedia_rtp_seq_session	pjmedia_rtp_seq_session
typedef struct pjmedia_rtp_session	pjmedia_rtp_session
typedef struct pjmedia_rtp_status	pjmedia_rtp_status
Functions
pj_status_t	pjmedia_rtp_session_init (pjmedia_rtp_session *ses, int default_pt, pj_uint32_t sender_ssrc)
pj_status_t	pjmedia_rtp_session_init2 (pjmedia_rtp_session *ses, pjmedia_rtp_session_setting settings)
pj_status_t	pjmedia_rtp_encode_rtp (pjmedia_rtp_session *ses, int pt, int m, int payload_len, int ts_len, const void **rtphdr, int *hdrlen)
pj_status_t	pjmedia_rtp_decode_rtp (pjmedia_rtp_session *ses, const void *pkt, int pkt_len, const pjmedia_rtp_hdr **hdr, const void **payload, unsigned *payloadlen)
void	pjmedia_rtp_session_update (pjmedia_rtp_session *ses, const pjmedia_rtp_hdr *hdr, pjmedia_rtp_status *seq_st)
void	pjmedia_rtp_session_update2 (pjmedia_rtp_session *ses, const pjmedia_rtp_hdr *hdr, pjmedia_rtp_status *seq_st, pj_bool_t check_pt)
void	pjmedia_rtp_seq_init (pjmedia_rtp_seq_session *seq_ctrl, pj_uint16_t seq)
void	pjmedia_rtp_seq_update (pjmedia_rtp_seq_session *seq_ctrl, pj_uint16_t seq, pjmedia_rtp_status *seq_status)

---

Typedef Documentation

typedef struct pjmedia_rtp_hdr pjmedia_rtp_hdr

See also:

pjmedia_rtp_hdr

typedef struct pjmedia_rtp_ext_hdr pjmedia_rtp_ext_hdr

See also:

pjmedia_rtp_ext_hdr

typedef struct pjmedia_rtp_dtmf_event pjmedia_rtp_dtmf_event

See also:

pjmedia_rtp_dtmf_event

typedef struct pjmedia_rtp_seq_session pjmedia_rtp_seq_session

See also:

pjmedia_rtp_seq_session

typedef struct pjmedia_rtp_session pjmedia_rtp_session

See also:

pjmedia_rtp_session

typedef struct pjmedia_rtp_status pjmedia_rtp_status

See also:

pjmedia_rtp_status

---

Function Documentation

pj_status_t pjmedia_rtp_session_init	(	pjmedia_rtp_session *	ses,
		int	default_pt,
		pj_uint32_t	sender_ssrc
	)

This function will initialize the RTP session according to given parameters.

Parameters:

	ses	The session.
	default_pt	Default payload type.
	sender_ssrc	SSRC used for outgoing packets, in host byte order.

Returns:

PJ_SUCCESS if successfull.

pj_status_t pjmedia_rtp_session_init2	(	pjmedia_rtp_session *	ses,
		pjmedia_rtp_session_setting	settings
	)

This function will initialize the RTP session according to given parameters defined in RTP session settings.

Parameters:

	ses	The session.
	settings	RTP session settings.

Returns:

PJ_SUCCESS if successfull.

pj_status_t pjmedia_rtp_encode_rtp	(	pjmedia_rtp_session *	ses,
		int	pt,
		int	m,
		int	payload_len,
		int	ts_len,
		const void **	rtphdr,
		int *	hdrlen
	)

Create the RTP header based on arguments and current state of the RTP session.

Parameters:

	ses	The session.
	pt	Payload type.
	m	Marker flag.
	payload_len	Payload length in bytes.
	ts_len	Timestamp length.
	rtphdr	Upon return will point to RTP packet header.
	hdrlen	Upon return will indicate the size of RTP packet header

Returns:

PJ_SUCCESS if successfull.

pj_status_t pjmedia_rtp_decode_rtp	(	pjmedia_rtp_session *	ses,
		const void *	pkt,
		int	pkt_len,
		const pjmedia_rtp_hdr **	hdr,
		const void **	payload,
		unsigned *	payloadlen
	)

This function decodes incoming packet into RTP header and payload. The decode function is guaranteed to point the payload to the correct position regardless of any options present in the RTP packet.

Note that this function does not modify the returned RTP header to host byte order.

Parameters:

	ses	The session.
	pkt	The received RTP packet.
	pkt_len	The length of the packet.
	hdr	Upon return will point to the location of the RTP header inside the packet. Note that the RTP header will be given back as is, meaning that the fields will be in network byte order.
	payload	Upon return will point to the location of the payload inside the packet.
	payloadlen	Upon return will indicate the size of the payload.

Returns:

PJ_SUCCESS if successfull.

void pjmedia_rtp_session_update	(	pjmedia_rtp_session *	ses,
		const pjmedia_rtp_hdr *	hdr,
		pjmedia_rtp_status *	seq_st
	)

Call this function everytime an RTP packet is received to check whether the packet can be received and to let the RTP session performs its internal calculations.

Parameters:

	ses	The session.
	hdr	The RTP header of the incoming packet. The header must be given with fields in network byte order.
	seq_st	Optional structure to receive the status of the RTP packet processing.

void pjmedia_rtp_session_update2	(	pjmedia_rtp_session *	ses,
		const pjmedia_rtp_hdr *	hdr,
		pjmedia_rtp_status *	seq_st,
		pj_bool_t	check_pt
	)

Call this function everytime an RTP packet is received to check whether the packet can be received and to let the RTP session performs its internal calculations.

Parameters:

	ses	The session.
	hdr	The RTP header of the incoming packet. The header must be given with fields in network byte order.
	seq_st	Optional structure to receive the status of the RTP packet processing.
	check_pt	Flag to indicate whether payload type needs to be validate.

See also:

pjmedia_rtp_session_update()

void pjmedia_rtp_seq_init	(	pjmedia_rtp_seq_session *	seq_ctrl,
		pj_uint16_t	seq
	)

Internal function for creating sequence number control, shared by RTCP implementation.

Parameters:

	seq_ctrl	The sequence control instance.
	seq	Sequence number to initialize.

void pjmedia_rtp_seq_update	(	pjmedia_rtp_seq_session *	seq_ctrl,
		pj_uint16_t	seq,
		pjmedia_rtp_status *	seq_status
	)

Internal function update sequence control, shared by RTCP implementation.

Parameters:

	seq_ctrl	The sequence control instance.
	seq	Sequence number to update.
	seq_status	Optional structure to receive additional information about the packet.