jrtplib.tex

jrtplib 的最新版本,比较好用的

\documentclass[12pt,a4paper]{article}

\newcommand{\jversion}{3.1.0}
\newcommand{\headerfile}[1]{\marginpar{\scriptsize Header:\\{\tt #1}}}
\newcommand{\inherits}[1]{\marginpar{\scriptsize Inherits:\\{\tt #1}}}
\newcommand{\Paragraph}[1]{\paragraph{#1}\ \\\addcontentsline{toc}{subsection}{\ \hspace{3cm}\ {#1}}}
%\newcommand{\headerfile}[1]{\marginpar{\pdfannot width 10cm depth 7cm{/Subtype/Text/Contents(Header: #1)}}}

\usepackage{listings}
\lstset{language=C++}
\lstset{tabsize=4}

\setlength{\hoffset}{-1.0in}
\addtolength{\hoffset}{1.5cm}
\setlength{\textwidth}{14.5cm}
\setlength{\voffset}{-1.0in}
\addtolength{\voffset}{1.0cm}
\setlength{\textheight}{23.5cm}
\setlength{\topmargin}{0.5cm}
\setlength{\footskip}{2.0cm}

\begin{document}
	\title{\ \vspace{3.5cm}\ \\{\bf JRTPLIB \jversion}}
	\author{Jori Liesenborgs\\{\tt [e-mail]}}
	\date{October 1, 2004\\\vspace{0.5cm}\ \\
	      {\small{\em Developed at the The Expertise Centre for \\Digital Media (EDM),
	      a research institute of\\ the Limburgs Universitair Centrum (LUC)}\\\ \\
		  {\tt http://www.edm.luc.ac.be/}\\
		  {\tt http://www.luc.ac.be/}}}
	\maketitle
	
	\newpage
	\tableofcontents

\setlength{\parindent}{0cm}
\setlength{\parskip}{0.3cm}

	\newpage
	\section*{Acknowledgment}\addcontentsline{toc}{section}{Acknowledgment}

		I would like thank the people at the Expertise Centre for Digital Media
		for giving me the opportunity to create this rewrite of the library.

	\newpage
	\section{Introduction}

		This document describes JRTPLIB version \jversion, an object-oriented
		library written in C++ which aims to help developers in using the 
		Real-time Transport Protocol (RTP) as described in RFC 3550.

		The library makes it possible for the user to send and receive data
		using RTP, without worrying about SSRC collisions, scheduling and
		transmitting RTCP data etc. The user only needs to provide the library
		with the payload data to be sent and the library gives the user access
		to incoming RTP and RTCP data.

		\subsection{Design idea}

			The library provides several classes which can be helpful in
			creating RTP applications. Most users will probably need just the
			{\tt RTPSession} class for building an application. This class
			provides the necessary functions for sending RTP data and handles
			the RTCP part internally.

			For applications such as a mixer or translator using the {\tt
			RTPSession} class will not be a good solution. Other components can
			be used for this purpose: a transmission component, an SSRC table,
			an RTCP scheduler etc. Using these, it should be much easier to
			build all kinds of applications.

		\subsection{Changes from version 2.x}

			One of the most important changes is probably the fact that this
			version is based on RFC 3550 and the 2.x versions were based upon
			RFC 1889 which is now obsolete.

			Also, the 2.x series was created with the idea that the user would
			only need to use the {\tt RTPSession} class which meant that the
			other classes were not very useful by themselves. This version on
			the other hand, aims to provide many useful components to aid the
			user in building RTP capable applications.

			In this version, the code which is specific for the underlying
			protocol by which RTP packets are transported, is bundled in
			a class which inherits its interface from a class called {\tt
			RTPTransmitter}. This makes it easy for different underlying
			protocols to be supported. Currently there is support for UDP over
			IPv4 and UDP over IPv6.

	\section{Copyright license}

		The library code uses the following copyright license:

			{\em Permission is hereby granted, free of charge, to any person
			obtaining a copy of this software and associated documentation files
			(the "Software"), to deal in the Software without restriction,
			including without limitation the rights to use, copy, modify, merge,
			publish, distribute, sublicense, and/or sell copies of the Software,
			and to permit persons to whom the Software is furnished to do so,
			subject to the following conditions:

			The above copyright notice and this permission notice shall be
			included in all copies or substantial portions of the Software.

			THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
			KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
			WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
			NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
			BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
			ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
			CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
			SOFTWARE.}

		There are two reason for using this license. First, since this is the
		license of the 2.x series, it only seemed natural that this rewrite
		would contain the same license. Second, since the RTP protocol is
		deliberately incomplete RTP profiles can, for example, define additional
		header fields. The best way to deal with this is to adapt the library
		code itself and that's why I like to keep the license as free as
		possible.

	\section{Using JRTPLIB \jversion}
		
		This section gives information about how to use the library. First, some
		simple examples will be given which illustrate how you can work with the
		{\tt RTPSession} class. Afterwards, a complete description of the API
		will be given.

		\subsection{Getting started with the {\tt RTPSession} class}

			To use RTP, you'll have to create an {\tt RTPSession} object. The
			constructor of the {\tt RTPSession} class takes a parameter of
			type {\tt RTPTrans\-mitter::Trans\-mission\-Protocol} and defaults
			to {\tt RTPTrans\-mitter::IPv4UDPProto}. This means that unless
			specified otherwise, the UDP over IPv4 transmission component will
			be used. Let's suppose that this is the kind of session you want to
			create, then this is our code so far:

            \begin{lstlisting}[frame=tb]{} 
RTPSession session; 
			\end{lstlisting}

			To actually create the session, you'll have to call the {\tt Create}
			member function which takes two arguments: the first one is of type
			{\tt RTPSession\-Params} and specifies the general options for
			the session. One parameter of this class must be set explicitly,
			otherwise the session will not be created successfully. This
			parameter is the timestamp unit of the data you intend to send and
			can be calculated by dividing a certain time interval (in seconds)
			by the number of samples in that interval. So, assuming that we'll
			send $8000 Hz$ voice data, we can use this code:

            \begin{lstlisting}[frame=tb]{} 
RTPSessionParams sessionparams;

sessionparams.SetOwnTimestampUnit(1.0/8000.0);
			\end{lstlisting}
			The other parameters will probably depend on the actual RTP profile
			you intend to work with. For a complete description of the {\tt
			RTPSession\-Params} class, see section \ref{rtpsessionparams}.

			The second argument of the {\tt Create} function is a pointer to
			an {\tt RTPTrans\-mission\-Params} instance and describes the
			parameters for the transmission component. Since there can be
			several transmission components, you'll have to use a class which
			inherits {\tt RTPTrans\-mission\-Params} and which is appropriate
			for the component you've chosen. For our UDP over IPv4 component,
			the class to be used is {\tt RTPUDPv4Trans\-mission\-Params}.
			Assuming that we want our RTP portbase to be $8000$, we can do the
			following:
			\begin{lstlisting}[frame=tb]{}
RTPUDPv4TransmissionParams transparams;

transparams.SetPortbase(8000);
			\end{lstlisting}

			Now, we're ready to call the {\tt Create} member function of
			{\tt RTPSession}. The return value is stored in the integer {\tt
			status} so we can check if something went wrong. If this value is
			negative, it indicates that some error occurred. A description
			of what this error code means can be retrieved by calling {\tt
			RTPGetErrorString}:
			\begin{lstlisting}[frame=tb]{}
int status = session.Create(sessionparams,&transparams);
if (status < 0)
{
	std::cerr << RTPGetErrorString(status) << std::endl;
	exit(-1);
}
			\end{lstlisting}
			
			If the session was created with success, this is probably a good
			point to specify to which destinations RTP and RTCP data should be
			sent. This is done by a call to the {\tt RTPSession} member function
			{\tt AddDestination}. This function takes an argument of type {\tt
			RTPAddress}. This is an abstract class and for the UDP over IPv4
			transmitter the actual class to be used is {\tt RTPIPv4Address}.
			Suppose that we want to send our data to a process running on the
			same host at port $9000$, we can do the following:
			\begin{lstlisting}[frame=tb]{}
u_int8_t localip[]={127,0,0,1};
RTPIPv4Address addr(localip,9000);

status = session.AddDestination(addr);
if (status < 0)
{
	std::cerr << RTPGetErrorString(status) << std::endl;
	exit(-1);
}
			\end{lstlisting}

			If the library was compiled with JThread support, incoming data is
			processed in the background. If JThread support was not enabled at
			compile time or if you specified in the session parameters that no
			poll thread should be used, you'll have to call the {\tt RTPSession}
			member function {\tt Poll} regularly to process incoming data and
			to send RTCP data when necessary. For now, let's assume that we're
			working with the poll thread enabled.

			Lets suppose that for a duration of one minute, we want to send
			packets containing $20 ms$ (or $160$ samples) of silence and we want
			to indicate when a packet from someone else has been received. Also
			suppose we have $L8$ data as defined in RFC 3551 and want to use
			payload type $96$. First, we'll set some default values:
			\begin{lstlisting}[frame=tb]{}
session.SetDefaultPayloadType(96);
session.SetDefaultMark(false);
session.SetDefaultTimestampIncrement(160);
			\end{lstlisting}

			Next, we'll create the buffer which contains $160$ silence samples
			and create an {\tt RTPTime} instance which indicates $20 ms$ or
			$0.020$ seconds. We'll also store the current time so we'll know
			when one minute has passed.
			\begin{lstlisting}[frame=tb]{}
u_int8_t silencebuffer[160];

for (int i = 0 ; i < 160 ; i++)
	silencebuffer[i] = 128;

RTPTime delay(0.020);
RTPTime starttime = RTPTime::CurrentTime();
			\end{lstlisting}

			Next, the main loop will be shown. In this loop, a packet containing
			$160$ bytes of payload data will be sent. Then, data handling can
			take place but this part is described later in the text. Finally,
			we'll wait $20 ms$ and check if sixty seconds have passed:
			\begin{lstlisting}[frame=tb]{}
bool done = false;
while (!done)
{
	status = session.SendPacket(silencebuffer,160);
	if (status < 0)
	{
		std::cerr << RTPGetErrorString(status) << std::endl;
		exit(-1);
	}
	
	//
	// Inspect incoming data here
	//
	
	RTPTime::Wait(delay);
	
	RTPTime t = RTPTime::CurrentTime();
	t -= starttime;
	if (t > RTPTime(60.0))
		done = true;
}
			\end{lstlisting}