uclmmbase-rtp.html

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

HREF="RTP"
>rtp</GTKDOCLINK
> *session,
                                             <A
HREF="uclmmbase-rtp.html#RTP-EVENT"
>rtp_event</A
> *e);</PRE
></TD
></TR
></TABLE
><P
>Handles RTP events in an application-specific way.
See <A
HREF="uclmmbase-rtp.html#RTP-EVENT"
>rtp_event</A
> for a description of the possible events and
how <A
HREF="uclmmbase-rtp.html#RTP-CALLBACK"
>rtp_callback</A
>() should handle each.&#13;</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN809"
></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 RTP Session.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>e</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>The RTP Event information.  See <A
HREF="uclmmbase-rtp.html#RTP-EVENT"
>rtp_event</A
>.
&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN823"
></A
><H3
><A
NAME="RTP-OPTION"
></A
>enum rtp_option</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>typedef enum {
        RTP_OPT_PROMISC =	    1,
        RTP_OPT_WEAK_VALIDATION	=   2,
        RTP_OPT_FILTER_MY_PACKETS = 3
} rtp_option;</PRE
></TD
></TR
></TABLE
><P
>The possible options for a session that affect which RTP packets are
passed to the application and when internal state for sources is created.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN828"
></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"
>RTP_OPT_PROMISC</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>Pass RTP packets to application irrespective of
whether a sender report has been received.  Normally, participant
state is created when a sender report is received and RTP packets that
arrive prior to the sender report are discarded.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RTP_OPT_WEAK_VALIDATION</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>Create source state when RTP packets arrive
if none exists.  This option is set by default.  Disabling the option
means source state is only created when sender reports are received.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>RTP_OPT_FILTER_MY_PACKETS</TT
></TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>Filter out packets from local participant
if they are received.  With multicast sessions, packets may be looped
back, causing senders packets to be received locally.  This may be
filtered out with this option.&#13;</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN845"
></A
><H3
><A
NAME="RTP-INIT"
></A
>rtp_init ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
><GTKDOCLINK
HREF="RTP-T"
>rtp_t</GTKDOCLINK
>       rtp_init                        (const char *addr,
                                             <GTKDOCLINK
HREF="UINT16-T"
>uint16_t</GTKDOCLINK
> rx_port,
                                             <GTKDOCLINK
HREF="UINT16-T"
>uint16_t</GTKDOCLINK
> tx_port,
                                             int ttl,
                                             <GTKDOCLINK
HREF="DOUBLE"
>double</GTKDOCLINK
> rtcp_bw,
                                             <A
HREF="uclmmbase-rtp.html#RTP-CALLBACK"
>rtp_callback</A
> callback,
                                             <GTKDOCLINK
HREF="UINT8-T"
>uint8_t</GTKDOCLINK
> *userdata);</PRE
></TD
></TR
></TABLE
><P
></P
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN857"
></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
>addr</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> IP destination of this session (unicast or multicast),
as an ASCII string.  May be a host name, which will be looked up,
or may be an IPv4 dotted quad or IPv6 literal adddress.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>rx_port</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The port to which to bind the UDP socket</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>tx_port</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The port to which to send UDP packets</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>ttl</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The TTL with which to send multicasts</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>rtcp_bw</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The total bandwidth (in units of bytes per second) that is
allocated to RTCP.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>callback</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> See section on <A
HREF="uclmmbase-rtp.html#RTP-CALLBACK"
>rtp_callback</A
>.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>userdata</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> Opaque data associated with the session.  See
<A
HREF="uclmmbase-rtp.html#RTP-GET-USERDATA"
>rtp_get_userdata</A
>().</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><I
CLASS="EMPHASIS"
>Returns</I
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> An opaque session identifier to be used in future calls to
the RTP library functions, or NULL on failure.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN896"
></A
><H3
><A
NAME="RTP-INIT-IF"
></A
>rtp_init_if ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
><GTKDOCLINK
HREF="RTP-T"
>rtp_t</GTKDOCLINK
>       rtp_init_if                     (const char *addr,
                                             char *iface,
                                             <GTKDOCLINK
HREF="UINT16-T"
>uint16_t</GTKDOCLINK
> rx_port,
                                             <GTKDOCLINK
HREF="UINT16-T"
>uint16_t</GTKDOCLINK
> tx_port,
                                             int ttl,
                                             <GTKDOCLINK
HREF="DOUBLE"
>double</GTKDOCLINK
> rtcp_bw,
                                             <A
HREF="uclmmbase-rtp.html#RTP-CALLBACK"
>rtp_callback</A
> callback,
                                             <GTKDOCLINK
HREF="UINT8-T"
>uint8_t</GTKDOCLINK
> *userdata);</PRE
></TD
></TR
></TABLE
><P
>Creates and initializes an RTP session.</P
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN908"
></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
>addr</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> IP destination of this session (unicast or multicast),
as an ASCII string.  May be a host name, which will be looked up,
or may be an IPv4 dotted quad or IPv6 literal adddress.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>iface</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> If the destination of the session is multicast,
the optional interface to bind to.  May be NULL, in which case
the default multicast interface as determined by the system
will be used.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>rx_port</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The port to which to bind the UDP socket</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>tx_port</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The port to which to send UDP packets</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>ttl</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The TTL with which to send multicasts</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>rtcp_bw</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The total bandwidth (in units of ___) that is
allocated to RTCP.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>callback</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> See section on <A
HREF="uclmmbase-rtp.html#RTP-CALLBACK"
>rtp_callback</A
>.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>userdata</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> Opaque data associated with the session.  See
<A
HREF="uclmmbase-rtp.html#RTP-GET-USERDATA"
>rtp_get_userdata</A
>().</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><I
CLASS="EMPHASIS"
>Returns</I
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> An opaque session identifier to be used in future calls to
the RTP library functions, or NULL on failure.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN951"
></A
><H3
><A
NAME="RTP-SEND-BYE"
></A
>rtp_send_bye ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void        rtp_send_bye                    (struct <GTKDOCLINK
HREF="RTP"
>rtp</GTKDOCLINK
> *session);</PRE
></TD
></TR
></TABLE
><P
>Sends a BYE message on the RTP session, indicating that this
system is leaving the session.
Should implement reverse reconsideration; right now it sends a
BYE if there are less than 50 members and sends nothing otherwise.</P
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN958"
></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 RTP session</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN967"
></A
><H3
><A
NAME="RTP-DONE"
></A
>rtp_done ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void        rtp_done                        (struct <GTKDOCLINK
HREF="RTP"
>rtp</GTKDOCLINK
> *session);</PRE
></TD
></TR
></TABLE
><P
>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 <A
HREF="uclmmbase-rtp.html#RTP-SEND-BYE"
>rtp_send_bye</A
>() first.</P
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN975"
></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 RTP session to finish</TD
></TR