BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJMEDIA Reference

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
 

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.

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
sesThe session.
default_ptDefault payload type.
sender_ssrcSSRC 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
sesThe session.
settingsRTP 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
sesThe session.
ptPayload type.
mMarker flag.
payload_lenPayload length in bytes.
ts_lenTimestamp length.
rtphdrUpon return will point to RTP packet header.
hdrlenUpon 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
sesThe session.
pktThe received RTP packet.
pkt_lenThe length of the packet.
hdrUpon 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.
payloadUpon return will point to the location of the payload inside the packet.
payloadlenUpon return will indicate the size of the payload.
Returns
PJ_SUCCESS if successfull.
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
sesThe session.
pktThe received RTP packet.
pkt_lenThe length of the packet.
hdrUpon 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_hdrUpon return will point to the location of the additional RTP header inside the packet, if any.
payloadUpon return will point to the location of the payload inside the packet.
payloadlenUpon 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
sesThe session.
hdrThe RTP header of the incoming packet. The header must be given with fields in network byte order.
seq_stOptional 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
sesThe session.
hdrThe RTP header of the incoming packet. The header must be given with fields in network byte order.
seq_stOptional structure to receive the status of the RTP packet processing.
check_ptFlag 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_ctrlThe sequence control instance.
seqSequence 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_ctrlThe sequence control instance.
seqSequence number to update.
seq_statusOptional structure to receive additional information about the packet.

 


PJMEDIA small footprint Open Source media stack
Copyright (C) 2006-2008 Teluu Inc.