Group PJMED_RTP¶

group PJMED_RTP

RTP format and session management.

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.

Functions

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.

See: pjmedia_rtp_session_update()

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.

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.

struct pjmedia_rtp_hdr¶

#include <rtp.h>

RTP packet header. Note that all RTP functions here will work with this header in network byte order.