rtpsessionapi.sgml

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

<refentry id="ortp-RtpSession-API">
<refmeta>
<refentrytitle>RtpSession API</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>ORTP Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>RtpSession API</refname><refpurpose>The RtpSession object provides control on a RTP session as defined in RFC 1889.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>

#include &lt;ortp.h&gt;


            <link linkend="RtpSession">RtpSession</link>;
enum        <link linkend="RtpSessionMode">RtpSessionMode</link>;
#define     <link linkend="RTP-CALLBACK-TABLE-MAX-ENTRIES:CAPS">RTP_CALLBACK_TABLE_MAX_ENTRIES</link>
<link linkend="RtpSession">RtpSession</link>* <link linkend="rtp-session-new">rtp_session_new</link>                 (<link linkend="gint">gint</link> mode);
<link linkend="void">void</link>        <link linkend="rtp-session-set-scheduling-mode">rtp_session_set_scheduling_mode</link> (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="gint">gint</link> yesno);
<link linkend="void">void</link>        <link linkend="rtp-session-set-blocking-mode">rtp_session_set_blocking_mode</link>   (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="gint">gint</link> yesno);
<link linkend="void">void</link>        <link linkend="rtp-session-set-profile">rtp_session_set_profile</link>         (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="RtpProfile">RtpProfile</link> *profile);
<link linkend="int">int</link>         <link linkend="rtp-session-set-local-addr">rtp_session_set_local_addr</link>      (<link linkend="RtpSession">RtpSession</link> *session,
                                             const <link linkend="gchar">gchar</link> *addr,
                                             <link linkend="gint">gint</link> port);
<link linkend="gint">gint</link>        <link linkend="rtp-session-set-remote-addr">rtp_session_set_remote_addr</link>     (<link linkend="RtpSession">RtpSession</link> *session,
                                             const <link linkend="gchar">gchar</link> *addr,
                                             <link linkend="gint">gint</link> port);
<link linkend="void">void</link>        <link linkend="rtp-session-set-jitter-compensation">rtp_session_set_jitter_compensation</link>
                                            (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="int">int</link> milisec);
<link linkend="void">void</link>        <link linkend="rtp-session-set-ssrc">rtp_session_set_ssrc</link>            (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="guint32">guint32</link> ssrc);
<link linkend="void">void</link>        <link linkend="rtp-session-set-seq-number">rtp_session_set_seq_number</link>      (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="guint16">guint16</link> seq);
<link linkend="int">int</link>         <link linkend="rtp-session-set-payload-type">rtp_session_set_payload_type</link>    (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="int">int</link> paytype);
<link linkend="int">int</link>         <link linkend="rtp-session-signal-connect">rtp_session_signal_connect</link>      (<link linkend="RtpSession">RtpSession</link> *session,
                                             const <link linkend="gchar">gchar</link> *signal,
                                             <link linkend="RtpCallback">RtpCallback</link> cb,
                                             <link linkend="gpointer">gpointer</link> user_data);
<link linkend="int">int</link>         <link linkend="rtp-session-signal-disconnect-by-callback">rtp_session_signal_disconnect_by_callback</link>
                                            (<link linkend="RtpSession">RtpSession</link> *session,
                                             const <link linkend="gchar">gchar</link> *signal,
                                             <link linkend="RtpCallback">RtpCallback</link> cb);
<link linkend="gint">gint</link>        <link linkend="rtp-session-send-with-ts">rtp_session_send_with_ts</link>        (<link linkend="RtpSession">RtpSession</link> *session,
                                             const <link linkend="gchar">gchar</link> *buffer,
                                             <link linkend="gint">gint</link> len,
                                             <link linkend="guint32">guint32</link> userts);
<link linkend="gint">gint</link>        <link linkend="rtp-session-recv-with-ts">rtp_session_recv_with_ts</link>        (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="gchar">gchar</link> *buffer,
                                             <link linkend="gint">gint</link> len,
                                             <link linkend="guint32">guint32</link> time,
                                             <link linkend="gint">gint</link> *have_more);
<link linkend="mblk-t">mblk_t</link>*     <link linkend="rtp-session-recvm-with-ts">rtp_session_recvm_with_ts</link>       (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="guint32">guint32</link> user_ts);
<link linkend="mblk-t">mblk_t</link>*     <link linkend="rtp-session-create-packet">rtp_session_create_packet</link>       (<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);
<link linkend="mblk-t">mblk_t</link>*     <link linkend="rtp-session-create-packet-with-data">rtp_session_create_packet_with_data</link>
                                            (<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*));
<link linkend="gint">gint</link>        <link linkend="rtp-session-sendm-with-ts">rtp_session_sendm_with_ts</link>       (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="mblk-t">mblk_t</link> *mp,
                                             <link linkend="guint32">guint32</link> userts);
<link linkend="guint32">guint32</link>     <link linkend="rtp-session-get-current-send-ts">rtp_session_get_current_send_ts</link> (<link linkend="RtpSession">RtpSession</link> *session);
<link linkend="void">void</link>        <link linkend="rtp-session-flush-sockets">rtp_session_flush_sockets</link>       (<link linkend="RtpSession">RtpSession</link> *session);
<link linkend="void">void</link>        <link linkend="rtp-session-set-time-jump-limit">rtp_session_set_time_jump_limit</link> (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="gint">gint</link> miliseconds);
<link linkend="void">void</link>        <link linkend="rtp-session-reset">rtp_session_reset</link>               (<link linkend="RtpSession">RtpSession</link> *session);
</synopsis>
</refsynopsisdiv>









<refsect1>
<title>Description</title>
<para>
The following api provides the application a way to define a RTP session, send or receives
data through it, and to keep informed of the evolution of the RTP session through a simple
callback mecanism (see <link linkend="rtp-session-signal-connect"><function>rtp_session_signal_connect()</function></link> for details).
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="RtpSession">RtpSession</title>
<indexterm><primary>RtpSession</primary></indexterm><programlisting>typedef struct {
	RtpSession *next;	/* next RtpSession, when the session are enqueued by the scheduler */
	RtpProfile *profile;
	WaitPoint recv_wp;
	WaitPoint send_wp;
	GMutex *lock;
	guint32 send_ssrc;
	guint32 recv_ssrc;
	gint payload_type;
	gint max_buf_size;
	RtpSignalTable on_ssrc_changed;
	RtpSignalTable on_payload_type_changed;
	RtpSignalTable on_telephone_event_packet;
	RtpSignalTable on_telephone_event;
	RtpSignalTable on_timestamp_jump;
	RtpSignalTable on_network_error;
	struct _OList *signal_tables;
	RtpStream rtp;
	RtcpStream rtcp;
	RtpSessionMode mode;
	struct _RtpScheduler *sched;
	guint32 flags;
	gint mask_pos;	/* the position in the scheduler mask of RtpSession */
	gpointer user_data;
	
	/* telephony events extension */
	gint telephone_events_pt;	/* the payload type used for telephony events */
	mblk_t *current_tev;		/* the pending telephony events */
	mblk_t *sd;
	queue_t contributing_sources;
} RtpSession;
</programlisting>
<para>
Users should not manipulate this structure directly.
</para></refsect2>
<refsect2>
<title><anchor id="RtpSessionMode">enum RtpSessionMode</title>
<indexterm><primary>RtpSessionMode</primary></indexterm><programlisting>typedef enum {
	RTP_SESSION_RECVONLY,
	RTP_SESSION_SENDONLY,
	RTP_SESSION_SENDRECV
} RtpSessionMode;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="RTP-CALLBACK-TABLE-MAX-ENTRIES:CAPS">RTP_CALLBACK_TABLE_MAX_ENTRIES</title>
<indexterm><primary>RTP_CALLBACK_TABLE_MAX_ENTRIES</primary></indexterm><programlisting>#define RTP_CALLBACK_TABLE_MAX_ENTRIES	5
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="rtp-session-new">rtp_session_new ()</title>
<indexterm><primary>rtp_session_new</primary></indexterm><programlisting><link linkend="RtpSession">RtpSession</link>* rtp_session_new                 (<link linkend="gint">gint</link> mode);</programlisting>
<para>
Creates a new rtp session.
 If the session is able to send data (RTP_SESSION_SENDONLY or RTP_SESSION_SENDRECV), then a
random SSRC number is choosed for the outgoing stream.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>mode</parameter>&nbsp;:</term>
<listitem><simpara> One of the <link linkend="RtpSessionMode"><type>RtpSessionMode</type></link> flags.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the newly created rtp session.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rtp-session-set-scheduling-mode">rtp_session_set_scheduling_mode ()</title>
<indexterm><primary>rtp_session_set_scheduling_mode</primary></indexterm><programlisting><link linkend="void">void</link>        rtp_session_set_scheduling_mode (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="gint">gint</link> yesno);</programlisting>
<para>
Sets the scheduling mode of the rtp session. If <parameter>yesno</parameter> is TRUE, the rtp session is in
the scheduled mode, that means that you can use <link linkend="session-set-select"><function>session_set_select()</function></link> to block until it's time
to receive or send on this session according to the timestamp passed to the respective functions.
 You can also use blocking mode (see <link linkend="rtp-session-set-blocking-mode"><function>rtp_session_set_blocking_mode()</function></link> ), to simply block within
the receive and send functions.
If <parameter>yesno</parameter> is FALSE, the ortp scheduler will not manage those sessions, meaning that blocking mode 
 and the use of <link linkend="session-set-select"><function>session_set_select()</function></link> for this session are disabled.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> a rtp session.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>yesno</parameter>&nbsp;:</term>
<listitem><simpara>	a boolean to indicate the scheduling mode.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rtp-session-set-blocking-mode">rtp_session_set_blocking_mode ()</title>
<indexterm><primary>rtp_session_set_blocking_mode</primary></indexterm><programlisting><link linkend="void">void</link>        rtp_session_set_blocking_mode   (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="gint">gint</link> yesno);</programlisting>
<para>
Using this function implies that you previously enabled scheduled mode on the session
 (see <link linkend="rtp-session-set-scheduling-mode"><function>rtp_session_set_scheduling_mode()</function></link> ).
<link linkend="rtp-session-set-blocking-mode"><function>rtp_session_set_blocking_mode()</function></link> defines the behaviour of the <link linkend="rtp-session-recv-with-ts"><function>rtp_session_recv_with_ts()</function></link> and 
<link linkend="rtp-session-send-with-ts"><function>rtp_session_send_with_ts()</function></link> functions. If <parameter>yesno</parameter> is TRUE, <link linkend="rtp-session-recv-with-ts"><function>rtp_session_recv_with_ts()</function></link>
will block until it is time for the packet to be received, according to the timestamp
passed to the function. After this time, the function returns.
For <link linkend="rtp-session-send-with-ts"><function>rtp_session_send_with_ts()</function></link>, it will block until it is time for the packet to be sent.
If <parameter>yesno</parameter> is FALSE, then the two functions will return immediately.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>session</parameter>&nbsp;:</term>
<listitem><simpara> a rtp session
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>yesno</parameter>&nbsp;:</term>
<listitem><simpara> a boolean
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="rtp-session-set-profile">rtp_session_set_profile ()</title>
<indexterm><primary>rtp_session_set_profile</primary></indexterm><programlisting><link linkend="void">void</link>        rtp_session_set_profile         (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="RtpProfile">RtpProfile</link> *profile);</programlisting>
<para>
Set the RTP profile to be used for the session. By default, all session are created by
<link linkend="rtp-session-new"><function>rtp_session_new()</function></link> are initialized with the AV profile, as defined in RFC 1890. The application
can set any other profile instead using that function.</para>
<para>

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