RTP

RTP_VERSION

#define RTP_VERSION 2

RTP_MAX_PACKET_LEN

#define RTP_MAX_PACKET_LEN 1500

rtp_packet

typedef struct {
	/* The following are pointers to the data in the packet as    */
	/* it came off the wire. The packet it read in such that the  */
	/* header maps onto the latter part of this struct, and the   */
	/* fields in this first part of the struct point into it. The */
	/* entire packet can be freed by freeing this struct, without */
	/* having to free the csrc, data and extn blocks separately.  */
	/* WARNING: Don't change the size of the first portion of the */
	/* struct without changing RTP_PACKET_HEADER_SIZE to match.   */
	uint32_t	*csrc;
	char		*data;
	int		 data_len;
	unsigned char	*extn;
	uint16_t	 extn_len;	/* Size of the extension in 32 bit words minus one */
	uint16_t	 extn_type;	/* Extension type field in the RTP packet header   */
	/* The following map directly onto the RTP packet header...   */
#ifdef WORDS_BIGENDIAN
	unsigned short   v:2;		/* packet type                */
	unsigned short   p:1;		/* padding flag               */
	unsigned short   x:1;		/* header extension flag      */
	unsigned short   cc:4;		/* CSRC count                 */
	unsigned short   m:1;		/* marker bit                 */
	unsigned short   pt:7;		/* payload type               */
#else
	unsigned short   cc:4;		/* CSRC count                 */
	unsigned short   x:1;		/* header extension flag      */
	unsigned short   p:1;		/* padding flag               */
	unsigned short   v:2;		/* packet type                */
	unsigned short   pt:7;		/* payload type               */
	unsigned short   m:1;		/* marker bit                 */
#endif
	uint16_t          seq;		/* sequence number            */
	uint32_t          ts;		/* timestamp                  */
	uint32_t          ssrc;		/* synchronization source     */
	/* The csrc list, header extension and data follow, but can't */
	/* be represented in the struct.                              */
} rtp_packet;

The struct begins with pointers to the data in the packet as it came off the wire. The packet is read in such that the header maps onto the latter part of this struct, and the fields in this first part of the struct point into it. The entire packet can be freed by freeing this struct, without having to free the csrc, data and extn blocks separately. WARNING: Don't change the size of the first portion of the struct without changing RTP_PACKET_HEADER_SIZE to match.

RTP_PACKET_HEADER_SIZE

#define RTP_PACKET_HEADER_SIZE	((sizeof(char *) * 2) + sizeof(uint32_t *) + (2 * sizeof(int)))

This macro MUST resolve to the offset of the first packet field in the rtp_packet struct, including all padding. If you change rtp_packet, make sure to change this too.

rtcp_sr

typedef struct {
	uint32_t         ssrc;
	uint32_t         ntp_sec;
	uint32_t         ntp_frac;
	uint32_t         rtp_ts;
	uint32_t         sender_pcount;
	uint32_t         sender_bcount;
} rtcp_sr;

rtcp_rr

typedef struct {
	uint32_t	ssrc;		/* The ssrc to which this RR pertains */
#ifdef WORDS_BIGENDIAN
	uint32_t	fract_lost:8;
	uint32_t	total_lost:24;
#else
	uint32_t	total_lost:24;
	uint32_t	fract_lost:8;
#endif	
	uint32_t	last_seq;
	uint32_t	jitter;
	uint32_t	lsr;
	uint32_t	dlsr;
} rtcp_rr;

enum rtcp_sdes_type

typedef enum  {
        RTCP_SDES_END   = 0,
        RTCP_SDES_CNAME = 1,
        RTCP_SDES_NAME  = 2,
        RTCP_SDES_EMAIL = 3,
        RTCP_SDES_PHONE = 4,
        RTCP_SDES_LOC   = 5,
        RTCP_SDES_TOOL  = 6,
        RTCP_SDES_NOTE  = 7,
        RTCP_SDES_PRIV  = 8
} rtcp_sdes_type;

Possible values of Session Description (SDES) identifiers. SDES items are announced via rtp_callback (with RX_SDES events) when they are received. SDES items may be configured and queried with rtp_set_sdes and rtp_get_sdes. The RTP guidelines recommend keeping SDES items constant during an RTP session to avoid confusing end users.

rtcp_sdes_item

typedef struct {
	uint8_t		type;		/* type of SDES item              */
	uint8_t		length;		/* length of SDES item (in bytes) */
	char		data[1];	/* text, not zero-terminated      */
} rtcp_sdes_item;

rtcp_app

typedef struct {
#ifdef WORDS_BIGENDIAN
	unsigned short  version:2;	/* RTP version            */
	unsigned short  p:1;		/* padding flag           */
	unsigned short  subtype:5;	/* application dependent  */
#else
	unsigned short  subtype:5;	/* application dependent  */
	unsigned short  p:1;		/* padding flag           */
	unsigned short  version:2;	/* RTP version            */
#endif
	unsigned short  pt:8;		/* packet type            */
	uint16_t        length;		/* packet length          */
	uint32_t        ssrc;
	char            name[4];        /* four ASCII characters  */
	char            data[1];        /* variable length field  */
} rtcp_app;

rtcp_app_callback ()

rtcp_app*   (*rtcp_app_callback)            (struct rtp *session,
                                             uint32_t rtp_ts,
                                             int max_size);

This callback function crafts an RTCP APP packet to be sent with an RTCP RR.

enum rtp_event_type

typedef enum {
        RX_RTP,
        RX_SR,
        RX_RR,
        RX_SDES,
        RX_BYE,         /* Source is leaving the session, database entry is still valid                           */
        SOURCE_CREATED,
        SOURCE_DELETED, /* Source has been removed from the database                                              */
        RX_RR_EMPTY,    /* We've received an empty reception report block                                         */
        RX_RTCP_START,  /* Processing a compound RTCP packet about to start. The SSRC is not valid in this event. */
        RX_RTCP_FINISH,	/* Processing a compound RTCP packet finished. The SSRC is not valid in this event.       */
        RR_TIMEOUT,
        RX_APP
} rtp_event_type;

The possible values for the type field in rtp_event. Each value represents an event in RTP or RTCP processing.

rtp_event

typedef struct {
	uint32_t	 ssrc;
	rtp_event_type	 type;
	void		*data;
	struct timeval	*ts;
} rtp_event;

The event structure as passed to rtp_callback(). The callback type is carried in the type field; see rtp_event_type for a description of each callback. Unless otherwise noted, the ssrc field contains the SSRC of the participant triggering this callback. The data field points to any data contained in this callback; it must be cast to the appropriate type. The ts field contains the timestamp of the packet reception that caused this event.

rtp_callback ()

void        (*rtp_callback)                 (struct rtp *session,
                                             rtp_event *e);

Handles RTP events in an application-specific way. See rtp_event for a description of the possible events and how rtp_callback() should handle each.

enum rtp_option

typedef enum {
        RTP_OPT_PROMISC =	    1,
        RTP_OPT_WEAK_VALIDATION	=   2,
        RTP_OPT_FILTER_MY_PACKETS = 3,
	RTP_OPT_REUSE_PACKET_BUFS = 4  /* Each data packet is written into the same buffer, */
	                               /* rather than malloc()ing a new buffer each time.   */
} rtp_option;

The possible options for a session that affect which RTP packets are passed to the application and when internal state for sources is created.

rtp_init ()

rtp_t       rtp_init                        (const char *addr,
                                             uint16_t rx_port,
                                             uint16_t tx_port,
                                             int ttl,
                                             double rtcp_bw,
                                             rtp_callback callback,
                                             uint8_t *userdata);

rtp_init_if ()

rtp_t       rtp_init_if                     (const char *addr,
                                             char *iface,
                                             uint16_t rx_port,
                                             uint16_t tx_port,
                                             int ttl,
                                             double rtcp_bw,
                                             rtp_callback callback,
                                             uint8_t *userdata);

Creates and initializes an RTP session.

rtp_send_bye ()

void        rtp_send_bye                    (struct rtp *session);

Sends a BYE message on the RTP session, indicating that this participant is leaving the session. The process of sending a BYE may take some time, and this function will block until it is complete. During this time, RTCP events are reported to the application via the callback function (data packets are silently discarded).

rtp_done ()

void        rtp_done                        (struct rtp *session);

Free the state associated with the given RTP session. This function does not send any packets (e.g. an RTCP BYE) - an application which wishes to exit in a clean manner should call rtp_send_bye() first.

rtp_set_option ()

int         rtp_set_option                  (struct rtp *session,
                                             rtp_option optname,
                                             int optval);

Sets the value of a session option. See rtp_option for documentation on the options and their legal values.

rtp_get_option ()

int         rtp_get_option                  (struct rtp *session,
                                             rtp_option optname,
                                             int *optval);

Retrieves the value of a session option. See rtp_option for documentation on the options and their legal values.

rtp_recv ()

int         rtp_recv                        (struct rtp *session,
                                             struct timeval *timeout,
                                             uint32_t curr_rtp_ts);

Receive RTP packets and dispatch them.

rtp_send_data ()

int         rtp_send_data                   (struct rtp *session,
                                             uint32_t rtp_ts,
                                             char pt,
                                             int m,
                                             int cc,
                                             uint32_t csrc[],
                                             char *data,
                                             int data_len,
                                             char *extn,
                                             uint16_t extn_len,
                                             uint16_t extn_type);

Send an RTP packet. Most media applications will only set the session, rtp_ts, pt, m, data, data_len arguments.

Mixers and translators typically set additional contributing sources arguments (cc, csrc).

Extensions fields (extn, extn_len, extn_type) are for including application specific information. When the widest amount of inter-operability is required these fields should be avoided as some applications discard packets with extensions they do not recognize.

rtp_send_ctrl ()

void        rtp_send_ctrl                   (struct rtp *session,
                                             uint32_t rtp_ts,
                                             rtcp_app_callback appcallback);

Checks RTCP timer and sends RTCP data when nececessary. The interval between RTCP packets is randomized over an interval that depends on the session bandwidth, the number of participants, and whether the local participant is a sender. This function should be called at least once per second, and can be safely called more frequently.

rtp_update ()

void        rtp_update                      (struct rtp *session);

Trawls through the internal data structures and performs housekeeping. This function should be called at least once per second. It uses an internal timer to limit the number of passes through the data structures to once per second, it can be safely called more frequently.

rtp_my_ssrc ()

uint32_t    rtp_my_ssrc                     (struct rtp *session);

rtp_add_csrc ()

int         rtp_add_csrc                    (struct rtp *session,
                                             uint32_t csrc);

Adds csrc to list of contributing sources used in SDES items. Used by mixers and transcoders.

rtp_del_csrc ()

int         rtp_del_csrc                    (struct rtp *session,
                                             uint32_t csrc);

Removes csrc from list of contributing sources used in SDES items. Used by mixers and transcoders.

rtp_set_sdes ()

int         rtp_set_sdes                    (struct rtp *session,
                                             uint32_t ssrc,
                                             rtcp_sdes_type type,
                                             const char *value,
                                             int length);

Sets session description information associated with participant ssrc. Under normal circumstances applications always use the ssrc of the local participant, this SDES information is transmitted in receiver reports. Setting SDES information for other participants affects the local SDES entries, but are not transmitted onto the network.

rtp_get_sdes ()

const char* rtp_get_sdes                    (struct rtp *session,
                                             uint32_t ssrc,
                                             rtcp_sdes_type type);

Recovers session description (SDES) information on participant identified with ssrc. The SDES information associated with a source is updated when receiver reports are received. There are several different types of SDES information, e.g. username, location, phone, email. These are enumerated by rtcp_sdes_type.

rtp_get_sr ()

const rtcp_sr* rtp_get_sr                   (struct rtp *session,
                                             uint32_t ssrc);

Retrieve the latest sender report made by sender with ssrc identifier.

rtp_get_rr ()

const rtcp_rr* rtp_get_rr                   (struct rtp *session,
                                             uint32_t reporter,
                                             uint32_t reportee);

Retrieve the latest receiver report on reportee made by reporter. Provides an indication of other receivers reception service.

rtp_set_encryption_key ()

int         rtp_set_encryption_key          (struct rtp *session,
                                             const char *passphrase);

Converts the user supplied key into a form suitable for use with RTP and install it as the active key. Passing in NULL as the passphrase disables encryption. The passphrase is converted into a DES key as specified in RFC1890, that is:

- convert to canonical form

- derive an MD5 hash of the canonical form

- take the first 56 bits of the MD5 hash

- add parity bits to form a 64 bit key

Note that versions of rat prior to 4.1.2 do not convert the passphrase to canonical form before taking the MD5 hash, and so will not be compatible for keys which are non-invarient under this step.

Determine from the user's encryption key which encryption mechanism we're using. Per the RTP RFC, if the key is of the form

string/key

then "string" is the name of the encryption algorithm, and "key" is the key to be used. If no / is present, then the algorithm is assumed to be (the appropriate variant of) DES.

rtp_set_my_ssrc ()

int         rtp_set_my_ssrc                 (struct rtp *session,
                                             uint32_t ssrc);

This function coerces the local SSRC identifer to be ssrc. For this function to succeed it must be called immediately after rtp_init or rtp_init_if. The intended purpose of this function is to co-ordinate SSRC's between layered sessions, it should not be used otherwise.

rtp_get_addr ()

char*       rtp_get_addr                    (struct rtp *session);

rtp_get_rx_port ()

uint16_t    rtp_get_rx_port                 (struct rtp *session);

rtp_get_tx_port ()

uint16_t    rtp_get_tx_port                 (struct rtp *session);

rtp_get_ttl ()

int         rtp_get_ttl                     (struct rtp *session);

rtp_get_userdata ()

uint8_t*    rtp_get_userdata                (struct rtp *session);

This function returns the userdata pointer that was passed to the rtp_init() or rtp_init_if() function when creating this session.