rtpsessionapi.sgml

linphone源码-1.3.5.tar.gz所需要的库文件

where the user supplied buffer <parameter>buffer</parameter> is not large enough to get all the data 
related to timestamp <parameter>time</parameter>, then *( <parameter>have_more</parameter>) is set to 1 to indicate that the application
should recall the function with the same timestamp to get more data.
</para>
<para>
 When the rtp session is scheduled (see <link linkend="rtp-session-set-scheduling-mode"><function>rtp_session_set_scheduling_mode()</function></link> ), and the 
blocking mode is on (see <link linkend="rtp-session-set-blocking-mode"><function>rtp_session_set_blocking_mode()</function></link> ), then the calling thread
is suspended until the timestamp given as argument expires, whatever a received packet 
fits the query or not.
</para>
<para>
Important note: it is clear that the application cannot know the timestamp of the first
packet of the incoming stream, because it can be random. The <parameter>time</parameter> timestamp given to the
function is used relatively to first timestamp of the stream. In simple words, 0 is a good
value to start calling this function.
</para>
<para>
This function internally calls <link linkend="rtp-session-recvm-with-ts"><function>rtp_session_recvm_with_ts()</function></link> to get a rtp packet. The content
of this packet is then copied into the user supplied buffer in an intelligent manner:
the function takes care of the size of the supplied buffer and the timestamp given in  
argument. Using this function it is possible to read continous audio data (e.g. pcma,pcmu...)
with for example a standart buffer of size of 160 with timestamp incrementing by 160 while the incoming
stream has a different packet size.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> a rtp session.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
<listitem><simpara>	a user supplied buffer to write the data.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&nbsp;:</term>
<listitem><simpara>		the length in bytes of the user supplied buffer.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>time</parameter>&nbsp;:</term>
<listitem><simpara>	the timestamp wanted.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>have_more</parameter>&nbsp;:</term>
<listitem><simpara> the address of an integer to indicate if more data is availlable for the given timestamp.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> if a packet was availlable with the corresponding timestamp supplied in argument 
then the number of bytes written in the user supplied buffer is returned. If no packets
are availlable, either because the sender has not started to send the stream, or either
because silence packet are not transmitted, or either because the packet was lost during
network transport, then the function returns zero.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rtp-session-recvm-with-ts">rtp_session_recvm_with_ts ()</title>
<indexterm><primary>rtp_session_recvm_with_ts</primary></indexterm><programlisting><link linkend="mblk-t">mblk_t</link>*     rtp_session_recvm_with_ts       (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="guint32">guint32</link> user_ts);</programlisting>
<para>
Try to get a rtp packet presented as a mblk_t structure from the rtp session.
The <parameter>user_ts</parameter> parameter is relative to the first timestamp of the incoming stream. In other
words, the application does not have to know the first timestamp of the stream, it can
simply call for the first time this function with <parameter>user_ts</parameter>=0, and then incrementing it
as it want. The RtpSession takes care of synchronisation between the stream timestamp
and the user timestamp given here.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> a rtp session.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_ts</parameter>&nbsp;:</term>
<listitem><simpara>	a timestamp.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a rtp packet presented as a mblk_t.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rtp-session-create-packet">rtp_session_create_packet ()</title>
<indexterm><primary>rtp_session_create_packet</primary></indexterm><programlisting><link linkend="mblk-t">mblk_t</link>*     rtp_session_create_packet       (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="gint">gint</link> header_size,
                                             const <link linkend="char">char</link> *payload,
                                             <link linkend="gint">gint</link> payload_size);</programlisting>
<para>
Allocates a new rtp packet. In the header, ssrc and payload_type according to the session's
context. Timestamp and seq number are not set, there will be set when the packet is going to be
sent with <link linkend="rtp-session-sendm-with-ts"><function>rtp_session_sendm_with_ts()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara>		a rtp session.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>header_size</parameter>&nbsp;:</term>
<listitem><simpara>	the rtp header size. For standart size (without extensions), it is <link linkend="RTP-FIXED-HEADER-SIZE:CAPS"><type>RTP_FIXED_HEADER_SIZE</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>payload</parameter>&nbsp;:</term>
<listitem><simpara>data to be copied into the rtp packet.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>payload_size</parameter>&nbsp;:</term>
<listitem><simpara> size of data carried by the rtp packet.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a rtp packet in a mblk_t (message block) structure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rtp-session-create-packet-with-data">rtp_session_create_packet_with_data ()</title>
<indexterm><primary>rtp_session_create_packet_with_data</primary></indexterm><programlisting><link linkend="mblk-t">mblk_t</link>*     rtp_session_create_packet_with_data
                                            (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="char">char</link> *payload,
                                             <link linkend="gint">gint</link> payload_size,
                                             <link linkend="void">void</link> (*freefn) (void*));</programlisting>
<para>
Creates a new rtp packet using the given payload buffer (no copy). The header will be allocated separetely.
 In the header, ssrc and payload_type according to the session's
context. Timestamp and seq number are not set, there will be set when the packet is going to be
sent with <link linkend="rtp-session-sendm-with-ts"><function>rtp_session_sendm_with_ts()</function></link>.
oRTP will send this packet using libc's <link linkend="sendmsg"><function>sendmsg()</function></link> (if this function is availlable!) so that there will be no
packet concatenation involving copies to be done in user-space.
 <parameter>freefn</parameter> can be NULL, in that case payload will be kept untouched.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara>		a rtp session.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>payload</parameter>&nbsp;:</term>
<listitem><simpara> the data to be sent with this packet
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>payload_size</parameter>&nbsp;:</term>
<listitem><simpara> size of data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>freefn</parameter>&nbsp;:</term>
<listitem><simpara> a function that will be called when the payload buffer is no more needed.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a rtp packet in a mblk_t (message block) structure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rtp-session-sendm-with-ts">rtp_session_sendm_with_ts ()</title>
<indexterm><primary>rtp_session_sendm_with_ts</primary></indexterm><programlisting><link linkend="gint">gint</link>        rtp_session_sendm_with_ts       (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="mblk-t">mblk_t</link> *mp,
                                             <link linkend="guint32">guint32</link> userts);</programlisting>
<para>
Send the rtp datagram <parameter>mp</parameter> to the destination set by <link linkend="rtp-session-set-remote-addr"><function>rtp_session_set_remote_addr()</function></link> 
with timestamp <parameter>timestamp</parameter>. For audio data, the timestamp is the number
of the first sample resulting of the data transmitted. See rfc1889 for details.
 The packet (<parameter>mp</parameter>) is freed once it is sended.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> a rtp session.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mp</parameter>&nbsp;:</term>
<listitem><simpara>	a rtp packet presented as a mblk_t.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>userts</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the number of bytes sent over the network.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rtp-session-get-current-send-ts">rtp_session_get_current_send_ts ()</title>
<indexterm><primary>rtp_session_get_current_send_ts</primary></indexterm><programlisting><link linkend="guint32">guint32</link>     rtp_session_get_current_send_ts (<link linkend="RtpSession">RtpSession</link> *session);</programlisting>
<para>
When the rtp session is scheduled and has started to send packets, this function
computes the timestamp that matches to the present time. Using this function can be 
usefull when sending discontinuous streams. Some time can be elapsed between the end
of a stream burst and the begin of a new stream burst, and the application may be not
not aware of this elapsed time. In order to get a valid (current) timestamp to pass to 
#<link linkend="rtp-session-send-with-ts"><function>rtp_session_send_with_ts()</function></link> or #<link linkend="rtp-session-sendm-with-ts"><function>rtp_session_sendm_with_ts()</function></link>, the application may
use <link linkend="rtp-session-get-current-send-ts"><function>rtp_session_get_current_send_ts()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> a rtp session.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the current send timestamp for the rtp session.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rtp-session-flush-sockets">rtp_session_flush_sockets ()</title>
<indexterm><primary>rtp_session_flush_sockets</primary></indexterm><programlisting><link linkend="void">void</link>        rtp_session_flush_sockets       (<link linkend="RtpSession">RtpSession</link> *session);</programlisting>
<para>
Flushes the sockets for all pending incoming packets.
This can be usefull if you did not listen to the stream for a while
and wishes to start to receive again. During the time no receive is made
packets get bufferised into the internal kernel socket structure.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> a rtp session
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rtp-session-set-time-jump-limit">rtp_session_set_time_jump_limit ()</title>
<indexterm><primary>rtp_session_set_time_jump_limit</primary></indexterm><programlisting><link linkend="void">void</link>        rtp_session_set_time_jump_limit (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="gint">gint</link> miliseconds);</programlisting>
<para>
oRTP has the possibility to inform the application through a callback registered 
with rtp_session_signal_connect about crazy incoming RTP stream that jumps from 
a timestamp N to N+&lt;some crazy value&gt;. This lets the opportunity for the application
to reset the session in order to resynchronize, or any other action like stopping the call
and reporting an error.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> the rtp session
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>miliseconds</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rtp-session-reset">rtp_session_reset ()</title>
<indexterm><primary>rtp_session_reset</primary></indexterm><programlisting><link linkend="void">void</link>        rtp_session_reset               (<link linkend="RtpSession">RtpSession</link> *session);</programlisting>
<para>
Reset the session: local and remote addresses are kept unchanged but the internal
queue for ordering and buffering packets is flushed, the session is ready to be
re-synchronised to another incoming stream.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> a rtp session.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>