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.
Defines
-
PJMEDIA_RTP_DTMF_EVENT_END_MASK
Mask for the E (“End”) bit of telephony-events payload.
See also
-
PJMEDIA_RTP_DTMF_EVENT_VOLUME_MASK
Mask for the Volume field of telephony-events payload.
See also
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.
-
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.
-
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 also
- 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.
See also
Public Members
-
pj_uint16_t cc
CSRC count
-
pj_uint16_t x
header extension flag
-
pj_uint16_t p
padding flag
-
pj_uint16_t v
packet type/version
-
pj_uint16_t pt
payload type
-
pj_uint16_t m
marker bit
-
pj_uint16_t seq
sequence number
-
pj_uint32_t ts
timestamp
-
pj_uint32_t ssrc
synchronization source
-
pj_uint16_t cc
-
struct pjmedia_rtp_ext_hdr
- #include <rtp.h>
RTP extension header.
See also
-
struct pjmedia_rtp_dec_hdr
- #include <rtp.h>
This will contain the RTP header decode output.
See also
-
struct pjmedia_rtp_dtmf_event
- #include <rtp.h>
Declaration for DTMF telephony-events (RFC2833).
See also
Public Members
-
pj_uint8_t event
Event type ID.
-
pj_uint8_t e_vol
Event volume.
-
pj_uint16_t duration
Event duration.
-
pj_uint8_t event
-
struct pjmedia_rtp_seq_session
- #include <rtp.h>
A generic sequence number management, used by both RTP and RTCP.
See also
Public Members
-
pj_uint16_t max_seq
Highest sequence number heard
-
pj_uint32_t cycles
Shifted count of seq number cycles
-
pj_uint32_t base_seq
Base seq number
-
pj_uint32_t bad_seq
Last ‘bad’ seq number + 1
-
pj_uint32_t probation
Sequ. packets till source is valid
-
pj_uint16_t max_seq
-
struct pjmedia_rtp_session
- #include <rtp.h>
RTP session descriptor.
See also
Public Members
-
pjmedia_rtp_hdr out_hdr
Saved hdr for outgoing pkts.
-
pjmedia_rtp_seq_session seq_ctrl
Sequence number management.
-
pj_uint16_t out_pt
Default outgoing payload type.
-
pj_uint32_t out_extseq
Outgoing extended seq #.
-
pj_uint32_t peer_ssrc
Peer SSRC.
-
pj_uint32_t received
Number of received packets.
-
pjmedia_rtp_hdr out_hdr
-
struct pjmedia_rtp_status
- #include <rtp.h>
This structure is used to receive additional information about the state of incoming RTP packet.
See also
Public Members
-
int bad
General flag to indicate that sequence is bad, and application should not process this packet. More information will be given in other flags.
-
int badpt
Bad payload type.
-
int badssrc
Bad SSRC
-
int dup
Indicates duplicate packet
-
int outorder
Indicates out of order packet
-
int probation
Indicates that session is in probation until more packets are received.
-
int restart
Indicates that sequence number has made a large jump, and internal base sequence number has been adjusted.
-
struct pjmedia_rtp_status::[anonymous]::flag flag
Status flags.
-
pj_uint16_t value
Status value, to conveniently address all flags.
-
union pjmedia_rtp_status::[anonymous] status
Status information union.
-
pj_uint16_t diff
Sequence number difference from previous packet. Normally the value should be 1. Value greater than one may indicate packet loss. If packet with lower sequence is received, the value will be set to zero. If base sequence has been restarted, the value will be one.
-
int bad
-
struct pjmedia_rtp_session_setting
- #include <rtp.h>
RTP session settings.
Public Members
-
pj_uint8_t flags
Bitmask flags to specify whether such field is set. Bitmask contents are: (bit #0 is LSB) bit #0: default payload type bit #1: sender SSRC bit #2: sequence bit #3: timestamp bit #4: peer SSRC
-
int default_pt
Default payload type.
-
pj_uint32_t sender_ssrc
Sender SSRC.
-
pj_uint32_t peer_ssrc
Peer SSRC.
-
pj_uint16_t seq
Sequence.
-
pj_uint32_t ts
Timestamp.
-
pj_uint8_t flags