rtpsessionapi.sgml

ORTP开源的rtp库

<refentry id="ortp-RtpSession-API">
<refmeta>
<refentrytitle id="top_of_page">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>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="synopsis">
<title id="synopsis.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="int">int</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="int">int</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="int">int</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="RtpProfile">RtpProfile</link>* <link linkend="rtp-session-get-profile">rtp_session_get_profile</link>         (<link linkend="RtpSession">RtpSession</link> *session);
<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="char">char</link> *addr,
                                             <link linkend="int">int</link> port);
<link linkend="int">int</link>         <link linkend="rtp-session-set-remote-addr">rtp_session_set_remote_addr</link>     (<link linkend="RtpSession">RtpSession</link> *session,
                                             const <link linkend="char">char</link> *addr,
                                             <link linkend="int">int</link> port);
<link linkend="int">int</link>         <link linkend="rtp-session-get-local-port">rtp_session_get_local_port</link>      (const <link linkend="RtpSession">RtpSession</link> *session);
<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="uint32-t">uint32_t</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="uint16-t">uint16_t</link> seq);
<link linkend="int">int</link>         <link linkend="rtp-session-set-send-payload-type">rtp_session_set_send_payload_type</link>
                                            (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="int">int</link> paytype);
<link linkend="int">int</link>         <link linkend="rtp-session-set-recv-payload-type">rtp_session_set_recv_payload_type</link>
                                            (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="int">int</link> pt);
<link linkend="int">int</link>         <link linkend="rtp-session-get-send-payload-type">rtp_session_get_send_payload_type</link>
                                            (const <link linkend="RtpSession">RtpSession</link> *session);
<link linkend="int">int</link>         <link linkend="rtp-session-get-recv-payload-type">rtp_session_get_recv_payload_type</link>
                                            (const <link linkend="RtpSession">RtpSession</link> *session);
<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> pt);
<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="char">char</link> *signal,
                                             <link linkend="RtpCallback">RtpCallback</link> cb,
                                             unsigned <link linkend="long-user-data">long user_data</link>);
<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="char">char</link> *signal,
                                             <link linkend="RtpCallback">RtpCallback</link> cb);
<link linkend="int">int</link>         <link linkend="rtp-session-send-with-ts">rtp_session_send_with_ts</link>        (<link linkend="RtpSession">RtpSession</link> *session,
                                             const <link linkend="char">char</link> *buffer,
                                             <link linkend="int">int</link> len,
                                             <link linkend="uint32-t">uint32_t</link> userts);
<link linkend="int">int</link>         <link linkend="rtp-session-recv-with-ts">rtp_session_recv_with_ts</link>        (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="char">char</link> *buffer,
                                             <link linkend="int">int</link> len,
                                             <link linkend="uint32-t">uint32_t</link> time,
                                             <link linkend="int">int</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="uint32-t">uint32_t</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="int">int</link> header_size,
                                             const <link linkend="char">char</link> *payload,
                                             <link linkend="int">int</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="int">int</link> payload_size,
                                             <link linkend="void">void</link> (*freefn) (void*));
<link linkend="int">int</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="uint32-t">uint32_t</link> userts);
<link linkend="uint32-t">uint32_t</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="int">int</link> miliseconds);
<link linkend="void">void</link>        <link linkend="rtp-session-set-recv-buf-size">rtp_session_set_recv_buf_size</link>   (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="int">int</link> bufsize);
<link linkend="void">void</link>        <link linkend="rtp-session-reset">rtp_session_reset</link>               (<link linkend="RtpSession">RtpSession</link> *session);
<link linkend="void">void</link>        <link linkend="rtp-session-set-data">rtp_session_set_data</link>            (<link linkend="RtpSession">RtpSession</link> *session,
                                             <link linkend="void">void</link> *data);
<link linkend="void">void</link>*       <link linkend="rtp-session-get-data">rtp_session_get_data</link>            (const <link linkend="RtpSession">RtpSession</link> *session);
</synopsis>
</refsynopsisdiv>









<refsect1 id="desc">
<title id="desc.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 id="details">
<title id="details.title">Details</title>
<refsect2>
<title><anchor id="RtpSession" role="struct">RtpSession</title>
<indexterm><primary>RtpSession</primary></indexterm><programlisting>typedef struct {
	RtpSession *next;	/* next RtpSession, when the session are enqueued by the scheduler */
	int mask_pos;	/* the position in the scheduler mask of RtpSession : do not move this field: it is part of the ABI since the session_set macros use it*/
	RtpProfile *profile;
	WaitPoint recv_wp;
	WaitPoint send_wp;
	ortp_mutex_t lock;
	uint32_t send_ssrc;
	uint32_t recv_ssrc;
	int send_pt;/* sent payload type */
	int recv_pt;/* recv payload type */
	int hw_recv_pt; /* recv payload type before jitter buffer */
	int recv_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;
	RtpSignalTable on_rtcp_bye;
	struct _OList *signal_tables;
	OrtpEvQueue eventq;
	RtpStream rtp;
	RtcpStream rtcp;
	RtpSessionMode mode;
	struct _RtpScheduler *sched;
	uint32_t flags;
	int multicast_ttl;
	int multicast_loopback;
	void * user_data;
	/* FIXME: Should be a table for all session participants. */
	struct timeval last_recv_time; /* Time of receiving the RTP/RTCP packet. */

	/* telephony events extension */
	int 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;
	bool_t symmetric_rtp;
	bool_t permissive; /*use the permissive algorithm*/
} RtpSession;
</programlisting>
<para>
Users should not manipulate this structure directly.
</para></refsect2>
<refsect2>
<title><anchor id="RtpSessionMode" role="enum">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" role="macro">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" role="function">rtp_session_new ()</title>
<indexterm><primary>rtp_session_new</primary></indexterm><programlisting><link linkend="RtpSession">RtpSession</link>* rtp_session_new                 (<link linkend="int">int</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" role="function">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="int">int</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>