RTP Session and Encapsulation (RFC 3550)

RTP format and session management. More...

Data Structures
struct	pjmedia_rtp_hdr
struct	pjmedia_rtp_ext_hdr
struct	pjmedia_rtp_dec_hdr
struct	pjmedia_rtp_dtmf_event
struct	pjmedia_rtp_seq_session
struct	pjmedia_rtp_session
struct	pjmedia_rtp_status
struct	pjmedia_rtp_session_setting

Macros
#define	PJMEDIA_RTP_DTMF_EVENT_END_MASK   0x80
#define	PJMEDIA_RTP_DTMF_EVENT_VOLUME_MASK   0x3F

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)
pj_status_t	pjmedia_rtp_decode_rtp2 (pjmedia_rtp_session *ses, const void *pkt, int pkt_len, const pjmedia_rtp_hdr **hdr, pjmedia_rtp_dec_hdr *dec_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)

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.

Macro Definition Documentation

PJMEDIA_RTP_DTMF_EVENT_END_MASK

#define PJMEDIA_RTP_DTMF_EVENT_END_MASK   0x80

Mask for the E ("End") bit of telephony-events payload.

See also

pjmedia_rtp_dtmf_event

PJMEDIA_RTP_DTMF_EVENT_VOLUME_MASK

#define PJMEDIA_RTP_DTMF_EVENT_VOLUME_MASK   0x3F

Mask for the Volume field of telephony-events payload.

See also

pjmedia_rtp_dtmf_event

Function Documentation

pjmedia_rtp_session_init()

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.

pjmedia_rtp_session_init2()

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.

pjmedia_rtp_encode_rtp()

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.

pjmedia_rtp_decode_rtp()

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.

pjmedia_rtp_decode_rtp2()

pj_status_t pjmedia_rtp_decode_rtp2	(	pjmedia_rtp_session *	ses,
		const void *	pkt,
		int	pkt_len,
		const pjmedia_rtp_hdr **	hdr,
		pjmedia_rtp_dec_hdr *	dec_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.
dec_hdr	Upon return will point to the location of the additional RTP header inside the packet, if any.
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.

pjmedia_rtp_session_update()

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.

pjmedia_rtp_session_update2()

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()

pjmedia_rtp_seq_init()

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.

pjmedia_rtp_seq_update()

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.

References PJ_END_DECL.