uclmmbase-rtp.html

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

></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN984"
></A
><H3
><A
NAME="RTP-SET-OPTION"
></A
>rtp_set_option ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>int         rtp_set_option                  (struct <GTKDOCLINK
HREF="RTP"
>rtp</GTKDOCLINK
> *session,
                                             <A
HREF="uclmmbase-rtp.html#RTP-OPTION"
>rtp_option</A
> optname,
                                             int optval);</PRE
></TD
></TR
></TABLE
><P
>Sets the value of a session option.  See <A
HREF="uclmmbase-rtp.html#RTP-OPTION"
>rtp_option</A
> for
documentation on the options and their legal values.</P
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN993"
></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
>optname</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The option name, see <A
HREF="uclmmbase-rtp.html#RTP-OPTION"
>rtp_option</A
>.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>optval</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The value to set.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><I
CLASS="EMPHASIS"
>Returns</I
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> TRUE on success, else FALSE.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN1015"
></A
><H3
><A
NAME="RTP-GET-OPTION"
></A
>rtp_get_option ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>int         rtp_get_option                  (struct <GTKDOCLINK
HREF="RTP"
>rtp</GTKDOCLINK
> *session,
                                             <A
HREF="uclmmbase-rtp.html#RTP-OPTION"
>rtp_option</A
> optname,
                                             int *optval);</PRE
></TD
></TR
></TABLE
><P
>Retrieves the value of a session option.  See <A
HREF="uclmmbase-rtp.html#RTP-OPTION"
>rtp_option</A
> for
documentation on the options and their legal values.</P
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN1024"
></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
>optname</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The option name, see <A
HREF="uclmmbase-rtp.html#RTP-OPTION"
>rtp_option</A
>.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>optval</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The return value.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><I
CLASS="EMPHASIS"
>Returns</I
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> TRUE and the value of the option in optval on success, else FALSE.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN1046"
></A
><H3
><A
NAME="RTP-RECV"
></A
>rtp_recv ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>int         rtp_recv                        (struct <GTKDOCLINK
HREF="RTP"
>rtp</GTKDOCLINK
> *session,
                                             struct <GTKDOCLINK
HREF="TIMEVAL"
>timeval</GTKDOCLINK
> *timeout,
                                             <GTKDOCLINK
HREF="UINT32-T"
>uint32_t</GTKDOCLINK
> curr_rtp_ts);</PRE
></TD
></TR
></TABLE
><P
>Receive RTP packets and dispatch them.</P
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN1055"
></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
>timeout</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> the amount of time that <GTKDOCLINK
HREF="RTCP-RECV"
>rtcp_recv</GTKDOCLINK
>() is allowed to block</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>curr_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"
><I
CLASS="EMPHASIS"
>Returns</I
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> TRUE if data received, FALSE if the timeout occurred.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN1078"
></A
><H3
><A
NAME="RTP-SEND-DATA"
></A
>rtp_send_data ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>int         rtp_send_data                   (struct <GTKDOCLINK
HREF="RTP"
>rtp</GTKDOCLINK
> *session,
                                             <GTKDOCLINK
HREF="UINT32-T"
>uint32_t</GTKDOCLINK
> rtp_ts,
                                             char pt,
                                             int m,
                                             int cc,
                                             <GTKDOCLINK
HREF="UINT32-T"
>uint32_t</GTKDOCLINK
> csrc[],
                                             char *data,
                                             int data_len,
                                             char *extn,
                                             <GTKDOCLINK
HREF="UINT16-T"
>uint16_t</GTKDOCLINK
> extn_len,
                                             <GTKDOCLINK
HREF="UINT16-T"
>uint16_t</GTKDOCLINK
> extn_type);</PRE
></TD
></TR
></TABLE
><P
>Send an RTP packet.  Most media applications will only set the
<TT
CLASS="PARAMETER"
><I
>session</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>rtp_ts</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>pt</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>m</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>data</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>data_len</I
></TT
> arguments.</P
><P
>Mixers and translators typically set additional contributing sources 
arguments (<TT
CLASS="PARAMETER"
><I
>cc</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>csrc</I
></TT
>).</P
><P
>Extensions fields (<TT
CLASS="PARAMETER"
><I
>extn</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>extn_len</I
></TT
>, <TT
CLASS="PARAMETER"
><I
>extn_type</I
></TT
>) 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.</P
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN1102"
></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 timestamp reflects the sampling instant of the first octet of the RTP data to be sent.  The timestamp is expressed in media units.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>pt</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The payload type identifying the format of the data.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>m</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> Marker bit, interpretation defined by media profile of payload.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>cc</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> Number of contributing sources (excluding local participant)</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>csrc</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> Array of SSRC identifiers for contributing sources.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>data</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The RTP data to be sent.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>data_len</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The size <TT
CLASS="PARAMETER"
><I
>data</I
></TT
> in bytes.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>extn</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> Extension data (if present).</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>extn_len</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> size of <TT
CLASS="PARAMETER"
><I
>extn</I
></TT
> in bytes.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>extn_type</I
></TT
>&nbsp;:</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> extension type indicator.</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><I
CLASS="EMPHASIS"
>Returns</I
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> Number of bytes transmitted.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN1158"
></A
><H3
><A
NAME="RTP-SEND-CTRL"
></A
>rtp_send_ctrl ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void        rtp_send_ctrl                   (struct <GTKDOCLINK
HREF="RTP"
>rtp</GTKDOCLINK
> *session,
                                             <GTKDOCLINK
HREF="UINT32-T"
>uint32_t</GTKDOCLINK
> rtp_ts,