uclmmbase-rtp.html

UCL Common Code Library Routines common to a number of multimedia tools. The library originates

#endif	
	uint32_t	last_seq;
	uint32_t	jitter;
	uint32_t	lsr;
	uint32_t	dlsr;
} rtcp_rr;</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN634"
></A
><H3
><A
NAME="RTCP-SDES-TYPE"
></A
>enum rtcp_sdes_type</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>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;</PRE
></TD
></TR
></TABLE
><P
>Possible values of Session Description (SDES) identifiers.  SDES items
are announced via <A
HREF="uclmmbase-rtp.html#RTP-CALLBACK"
>rtp_callback</A
> (with RX_SDES events) when they are
received.  SDES items may be configured and queried with <A
HREF="uclmmbase-rtp.html#RTP-SET-SDES"
>rtp_set_sdes</A
>
and <A
HREF="uclmmbase-rtp.html#RTP-GET-SDES"
>rtp_get_sdes</A
>.  The RTP guidelines recommend keeping SDES items
constant during an RTP session to avoid confusing end users.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN642"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#F0F0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RTCP_SDES_END</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>Indicates the end of SDES item processing when SDES data is received.  Has no meaning with <A
HREF="uclmmbase-rtp.html#RTP-SET-SDES"
>rtp_set_sdes</A
> and <A
HREF="uclmmbase-rtp.html#RTP-GET-SDES"
>rtp_get_sdes</A
>.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RTCP_SDES_CNAME</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The canonical name associated with participant. It is algorithmically derived and should never be changed.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RTCP_SDES_NAME</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The local participant's name, typically displayed in RTP session participant list. The name can take any form, and should remain constant during a session to avoid confusion.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RTCP_SDES_EMAIL</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The local participant's email address (optional).</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RTCP_SDES_PHONE</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The local participant's telephone number (optional).</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RTCP_SDES_LOC</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The local participant's geographic location (optional).</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RTCP_SDES_TOOL</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The local participant's tool (optional).</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RTCP_SDES_NOTE</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>Any additional information the local participant wishes to communicate about themselves (optional).</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RTCP_SDES_PRIV</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>Private extension SDES item see <A
HREF="http://www.ietf.org/rfc/rfc1889.txt"
TARGET="_top"
>RFC1889</A
> for details.&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN686"
></A
><H3
><A
NAME="RTCP-SDES-ITEM"
></A
>rtcp_sdes_item</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>typedef struct {
	rtcp_sdes_type	type;		/* type of SDES item              */
	uint8_t		length;		/* length of SDES item (in bytes) */
	char		data[1];	/* text, not zero-terminated      */
} rtcp_sdes_item;</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN691"
></A
><H3
><A
NAME="RTCP-APP"
></A
>rtcp_app</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>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;</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN696"
></A
><H3
><A
NAME="RTCP-APP-CALLBACK"
></A
>rtcp_app_callback ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
><A
HREF="uclmmbase-rtp.html#RTCP-APP"
>rtcp_app</A
>*   (*rtcp_app_callback)            (struct <GTKDOCLINK
HREF="RTP"
>rtp</GTKDOCLINK
> *session,
                                             <GTKDOCLINK
HREF="UINT32-T"
>uint32_t</GTKDOCLINK
> rtp_ts,
                                             int max_size);</PRE
></TD
></TR
></TABLE
><P
>This callback function crafts an RTCP APP packet to be sent with
an RTCP RR.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN704"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>session</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the session pointer (returned by <A
HREF="uclmmbase-rtp.html#RTP-INIT"
>rtp_init</A
>())</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>rtp_ts</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the current time expressed in units of the media timestamp.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>max_size</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the max allowed size of an APP packet.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><I
CLASS="EMPHASIS"
>Returns</I
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>A fully-formed RTCP APP packet as an <A
HREF="uclmmbase-rtp.html#RTCP-APP"
>rtcp_app</A
>, or NULL (???)
if no APP packet needs to be sent at this time.
&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN727"
></A
><H3
><A
NAME="RTP-EVENT-TYPE"
></A
>enum rtp_event_type</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>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;</PRE
></TD
></TR
></TABLE
><P
>The possible values for the type field in <A
HREF="uclmmbase-rtp.html#RTP-EVENT"
>rtp_event</A
>.
Each value represents an event in RTP or RTCP processing.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN733"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#F0F0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RX_RTP</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>An RTP data packet was received.
The ssrc field contains the RTP data packet's SSRC.
The data field points to a <A
HREF="uclmmbase-rtp.html#RTP-PACKET"
>rtp_packet</A
> containing the RTP data packet.
The callback must free the rtp_packet when it's done with it using the <A
HREF="uclmmbase-memory.html#XFREE"
>xfree</A
>() function.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RX_SR</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>An RTCP SR packet was received.
The ssrc field contains the SR packet's SSRC.
The data field points to an <A
HREF="uclmmbase-rtp.html#RTCP-SR"
>rtcp_sr</A
>.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RX_RR</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>An RTCP RR packet was received.
The ssrc field contains the RR packet's SSRC.
The data field points to an <A
HREF="uclmmbase-rtp.html#RTCP-RR"
>rtcp_rr</A
>.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RX_SDES</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>An RTCP SDES packet was received.
The ssrc field contains the SDES packet's SSRC.
The data field points to an <A
HREF="uclmmbase-rtp.html#RTCP-SDES-ITEM"
>rtcp_sdes_item</A
>.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RX_BYE</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>An RTCP BYE packet was received.
The ssrc field contains the BYE packet's SSRC.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>SOURCE_CREATED</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>A new session participant was heard from.
The ssrc field contains the new participant's SSRC.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>SOURCE_DELETED</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>A source was deleted from the database.
The ssrc field contains the ex-participant's SSRC.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RX_RR_EMPTY</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>An RTCP RR packet with no sources listed was received.
The ssrc field contains the RR packet's SSRC.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RX_RTCP_START</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>Called at the start of parsing an RTCP packet.
Neither the ssrc nor data fields are valid.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RX_RTCP_FINISH</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>Called at the end of parsing an RTCP packet.
Neither the ssrc nor data fields are valid.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RR_TIMEOUT</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>An RR from the given receiver has not been refreshed recently enough.
The ssrc field contains the RR packet's SSRC.
The data field points to the expiring <A
HREF="uclmmbase-rtp.html#RTCP-RR"
>rtcp_rr</A
>.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RX_APP</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>An APP packet was received.
The ssrc field contains the APP packet's SSRC.
The data field points to an <A
HREF="uclmmbase-rtp.html#RTCP-APP"
>rtcp_app</A
>.
The callback must free the app packet when it's done with it.&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN793"
></A
><H3
><A
NAME="RTP-EVENT"
></A
>rtp_event</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>typedef struct {
	uint32_t	 ssrc;
	rtp_event_type	 type;
	void		*data;
	struct timeval	*ts;
} rtp_event;</PRE
></TD
></TR
></TABLE
><P
>The event structure as passed to <A
HREF="uclmmbase-rtp.html#RTP-CALLBACK"
>rtp_callback</A
>().
The callback type is carried in the type field; see <A
HREF="uclmmbase-rtp.html#RTP-EVENT-TYPE"
>rtp_event_type</A
>
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.</P
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN800"
></A
><H3
><A
NAME="RTP-CALLBACK"
></A
>rtp_callback ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void        (*rtp_callback)                 (struct <GTKDOCLINK