multiplexing.sgml

linphone源码-1.3.5.tar.gz,linphone源码-1.3.5.tar.gz

<refentry id="ortp-Multiplexing-sessions---in-a-one-thread-design">
<refmeta>
<refentrytitle>Multiplexing sessions (in a one thread design)</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>ORTP Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Multiplexing sessions (in a one thread design)</refname><refpurpose>The SessionSet API allows applications to make I/O on mutilple rtp sessions
without making blocking I/O, but keeping the main process synchronised.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>

#include &lt;ortp.h&gt;


            <link linkend="SessionSet">SessionSet</link>;
<link linkend="SessionSet">SessionSet</link>* <link linkend="session-set-new">session_set_new</link>                 ();
#define     <link linkend="session-set-init">session_set_init</link>                (ss)
#define     <link linkend="session-set-set">session_set_set</link>                 (ss,rtpsession)
#define     <link linkend="session-set-is-set">session_set_is_set</link>              (ss,rtpsession)
#define     <link linkend="session-set-clr">session_set_clr</link>                 (ss,rtpsession)
<link linkend="int">int</link>         <link linkend="session-set-select">session_set_select</link>              (<link linkend="SessionSet">SessionSet</link> *recvs,
                                             <link linkend="SessionSet">SessionSet</link> *sends,
                                             <link linkend="SessionSet">SessionSet</link> *errors);
<link linkend="void">void</link>        <link linkend="session-set-destroy">session_set_destroy</link>             (<link linkend="SessionSet">SessionSet</link> *set);
</synopsis>
</refsynopsisdiv>









<refsect1>
<title>Description</title>
<para>
The scheduled mode must be enabled for all rtp session that are managed through the 
SessionSet API. See <link linkend="rtp-session-set-scheduling-mode"><function>rtp_session_set_scheduling_mode()</function></link>.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="SessionSet">SessionSet</title>
<indexterm><primary>SessionSet</primary></indexterm><programlisting>typedef struct {
	ortp_fd_set rtpset;
} SessionSet;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="session-set-new">session_set_new ()</title>
<indexterm><primary>session_set_new</primary></indexterm><programlisting><link linkend="SessionSet">SessionSet</link>* session_set_new                 ();</programlisting>
<para>
Allocates and initialize a new empty session set.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the session set.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="session-set-init">session_set_init()</title>
<indexterm><primary>session_set_init</primary></indexterm><programlisting>#define session_set_init(ss)		ORTP_FD_ZERO(&amp;(ss)-&gt;rtpset)
</programlisting>
<para>
Initializes a session set. It is unusefull to call this function on a session set object
returned by <link linkend="session-set-new"><function>session_set_new()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ss</parameter>&nbsp;:</term>
<listitem><simpara>	 a SessionSet statically allocated.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="session-set-set">session_set_set()</title>
<indexterm><primary>session_set_set</primary></indexterm><programlisting>#define session_set_set(ss,rtpsession)		ORTP_FD_SET((rtpsession)-&gt;mask_pos,&amp;(ss)-&gt;rtpset)
</programlisting>
<para>
This macro adds rtp session <parameter>_session</parameter> to set <parameter>_set</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ss</parameter>&nbsp;:</term>
<listitem><simpara>		a set (<link linkend="SessionSet"><type>SessionSet</type></link> object)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>rtpsession</parameter>&nbsp;:</term>
<listitem><simpara>	a rtp session
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="session-set-is-set">session_set_is_set()</title>
<indexterm><primary>session_set_is_set</primary></indexterm><programlisting>#define session_set_is_set(ss,rtpsession)	ORTP_FD_ISSET((rtpsession)-&gt;mask_pos,&amp;(ss)-&gt;rtpset)
</programlisting>
<para>
This macro tests if <parameter>_session</parameter> is part of <parameter>_set</parameter>. 1 is returned if true, 0 else.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ss</parameter>&nbsp;:</term>
<listitem><simpara>		a set (<link linkend="SessionSet"><type>SessionSet</type></link> object)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>rtpsession</parameter>&nbsp;:</term>
<listitem><simpara>	a rtp session
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="session-set-clr">session_set_clr()</title>
<indexterm><primary>session_set_clr</primary></indexterm><programlisting>#define session_set_clr(ss,rtpsession)		ORTP_FD_CLR((rtpsession)-&gt;mask_pos,&amp;(ss)-&gt;rtpset)
</programlisting>
<para>
Removes the <parameter>_session</parameter> from the _set.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ss</parameter>&nbsp;:</term>
<listitem><simpara>	a set of sessions.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>rtpsession</parameter>&nbsp;:</term>
<listitem><simpara> a rtp session.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="session-set-select">session_set_select ()</title>
<indexterm><primary>session_set_select</primary></indexterm><programlisting><link linkend="int">int</link>         session_set_select              (<link linkend="SessionSet">SessionSet</link> *recvs,
                                             <link linkend="SessionSet">SessionSet</link> *sends,
                                             <link linkend="SessionSet">SessionSet</link> *errors);</programlisting>
<para>
This function performs similarly as libc <link linkend="select"><function>select()</function></link> function, but performs on <link linkend="RtpSession"><type>RtpSession</type></link> 
instead of file descriptors.
<link linkend="session-set-select"><function>session_set_select()</function></link> suspends the calling process until some events arrive on one of the
three sets passed in argument. Two of the sets can be NULL.
The first set <parameter>recvs</parameter> is interpreted as a set of RtpSession waiting for receive events:
a new buffer (perhaps empty) is availlable on one or more sessions of the set, or the last
receive operation with <link linkend="rtp-session-recv-with-ts"><function>rtp_session_recv_with_ts()</function></link> would have finished if it were in 
blocking mode.
The second set is interpreted as a set of RtpSession waiting for send events, i.e. the last
<link linkend="rtp-session-send-with-ts"><function>rtp_session_send_with_ts()</function></link> call on a session would have finished if it were in blocking mode.
</para>
<para>
When some events arrived on some of sets, then the function returns and sets are changed
to indicate the sessions where events happened.
Sessions can be added to sets using <link linkend="session-set-set"><function>session_set_set()</function></link>, a session has to be tested to be 
part of a set using <link linkend="session-set-is-set"><function>session_set_is_set()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>recvs</parameter>&nbsp;:</term>
<listitem><simpara>		a set of rtp sessions to be watched for read events
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>sends</parameter>&nbsp;:</term>
<listitem><simpara>		a set of rtp sessions to be watched for write events
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>errors</parameter>&nbsp;:</term>
<listitem><simpara>		a set of rtp sessions to be watched for errors
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the number of sessions on which the selected events happened.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="session-set-destroy">session_set_destroy ()</title>
<indexterm><primary>session_set_destroy</primary></indexterm><programlisting><link linkend="void">void</link>        session_set_destroy             (<link linkend="SessionSet">SessionSet</link> *set);</programlisting>
<para>
</para>
<para>

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

</refsect1>



<refsect1>
<title>See Also</title>
<para>
See the mrtprecv.c and mrtpsend.c programs included in the library that uses
the SessionSet API to send or receive multiple RTP streams in one thread design.
</para>
</refsect1>

</refentry>