rtpsessionapi.sgml

ortp协议栈（实时传输协议）

<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;


struct      <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);
void        <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);
void        <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);
void        <link linkend="rtp-session-set-profile">rtp_session_set_profile</link>         (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="RtpProfile">RtpProfile</link> *profile);
int         <link linkend="rtp-session-set-local-addr">rtp_session_set_local_addr</link>      (<link linkend="RtpSession">RtpSession</link> *session,
                                             <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,
                                             struct <link linkend="sockaddr-in">sockaddr_in</link> *dest);
void        <link linkend="rtp-session-set-jitter-compensation">rtp_session_set_jitter_compensation</link>
                                            (<link linkend="RtpSession">RtpSession</link> *session,
                                             int milisec);
void        <link linkend="rtp-session-set-ssrc">rtp_session_set_ssrc</link>            (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="guint32">guint32</link> ssrc);
int         <link linkend="rtp-session-set-payload-type">rtp_session_set_payload_type</link>    (<link linkend="RtpSession">RtpSession</link> *session,
                                             int paytype);
int         <link linkend="rtp-session-signal-connect">rtp_session_signal_connect</link>      (<link linkend="RtpSession">RtpSession</link> *session,
                                             char *signal,
                                             <link linkend="RtpCallback">RtpCallback</link> cb,
                                             <link linkend="gpointer">gpointer</link> user_data);
int         <link linkend="rtp-session-signal-disconnect-by-callback">rtp_session_signal_disconnect_by_callback</link>
                                            (<link linkend="RtpSession">RtpSession</link> *session,
                                             char *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,
                                             <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="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="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,
                                             char *payload,
                                             <link linkend="gint">gint</link> payload_size);
</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">rtp_session_signal_connect</link>() for details).
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="RtpSession">struct RtpSession</title>
<programlisting>struct RtpSession
{
	RtpSession *next;	/* next RtpSession, when the session are enqueued by the scheduler */
	RtpProfile *profile;
	GMutex *lock;
	guint32 ssrc;
	gint payload_type;
#ifndef TARGET_IS_HPUXKERNEL
	gint highest_fd;
	fd_set scanfd;
#else
	mblk_t *dest_mproto; 	/* a M_PROTO that contains the destination address for outgoing packets*/
#endif
	gint max_buf_size;
	RtpSignalTable on_ssrc_changed;
	RtpSignalTable on_payload_type_changed;
	RtpSignalTable on_telephone_event_packet;
	RtpSignalTable on_telephone_event;
	RtpStream rtp;
	RtcpStream rtcp;
	RtpSessionMode mode;
#ifdef BUILD_SCHEDULER
	struct _RtpScheduler *sched;
#endif
	guint32 flags;
	rtp_stats_t stats;
	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 */
};
</programlisting>
<para>
Users should not manipulate this structure directly.
</para></refsect2>
<refsect2>
<title><anchor id="RtpSessionMode">enum RtpSessionMode</title>
<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>
<programlisting>#define RTP_CALLBACK_TABLE_MAX_ENTRIES	5
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="rtp-session-new">rtp_session_new ()</title>
<programlisting><link linkend="RtpSession">RtpSession</link>* rtp_session_new                 (<link linkend="gint">gint</link> mode);</programlisting>
<para>
Creates a new rtp session.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>mode</parameter>&nbsp;:</entry>
<entry> One of the <link linkend="RtpSessionMode">RtpSessionMode</link> flags.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the newly created rtp session.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="rtp-session-set-scheduling-mode">rtp_session_set_scheduling_mode ()</title>
<programlisting>void        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 1, the rtp session is in
the scheduled mode: this means that packet input/output for that session
is done by a thread that is in charge of getting and sending packet at regular time
interval. This is very usefull for outgoing packets, that have to be sent at a time that
matches their timestamp.
If <parameter>yesno</parameter> is zero, then the session is not scheduled. All recv and send operation will
occur when calling respectively <link linkend="rtp-session-recv-with-ts">rtp_session_recv_with_ts</link>() and <link linkend="rtp-session-send-with-ts">rtp_session_send_with_ts</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>session</parameter>&nbsp;:</entry>
<entry> a rtp session.
</entry></row>
<row><entry align="right"><parameter>yesno</parameter>&nbsp;:</entry>
<entry>	a boolean to indicate the scheduling mode.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="rtp-session-set-blocking-mode">rtp_session_set_blocking_mode ()</title>
<programlisting>void        rtp_session_set_blocking_mode   (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="gint">gint</link> yesno);</programlisting>
<para>
This function defines the behaviour of the <link linkend="rtp-session-recv-with-ts">rtp_session_recv_with_ts</link>() and 
<link linkend="rtp-session-send-with-ts">rtp_session_send_with_ts</link>() functions. If <parameter>yesno</parameter> is 1, <link linkend="rtp-session-recv-with-ts">rtp_session_recv_with_ts</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">rtp_session_send_with_ts</link>(), it will block until it is time for the packet to be sent.
If <parameter>yesno</parameter> is 0, then the two functions will return immediately.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>session</parameter>&nbsp;:</entry>
<entry> a rtp session
</entry></row>
<row><entry align="right"><parameter>yesno</parameter>&nbsp;:</entry>