jrtplib.tex

jrtplib3.3.0 最新下载的jrtplib. 我现在正在用jrtplib2.7版本

			Information about participants in the session, packet retrieval
			etc, has to be done between calls to the {\tt RTPSession} member
			functions {\tt BeginDataAccess} and {\tt EndDataAccess}. This
			ensures that the background thread doesn't try to change the same
			data you're trying to access. We'll iterate over the participants
			using the {\tt GotoFirstSource} and {\tt GotoNextSource} member
			functions. Packets from the currently selected participant can
			be retrieved using the {\tt GetNextPacket} member function which
			returns a pointer to an instance of the {\tt RTPPacket} class.
			When you don't need the packet anymore, it has to be deleted. The
			processing of incoming data will then be as follows:
			\begin{lstlisting}[frame=tb]{}
session.BeginDataAccess();
if (session.GotoFirstSource())
{
	do
	{
		RTPPacket *packet = session.GetNextPacket();
		if (packet)
		{
			std::cout << "Got packet with extended sequence number " 
			          << packet->GetExtendedSequenceNumber() 
					  << " from SSRC " << packet->GetSSRC() 
					  << std::endl;
			delete packet;
		}
	} while (session.GotoNextSource());
}
session.EndDataAccess();
			\end{lstlisting}
			
			Information about the currently selected source can be obtained
			by using the {\tt GetCurrentSourceInfo} member function of 
			the {\tt RTPSession} class. This function returns a pointer to 
			an instance of {\tt RTPSourceData} which contains all information
			about that source: sender reports from that source, receiver
			reports, SDES info etc. The {\tt RTPSourceData} class is described
			in detail in section \ref{rtpsourcedata}.

			When the main loop is finished, we'll send a BYE packet to
			inform other participants of our departure and clean up the {\tt
			RTPSession} class. Also, we want to wait at most $10$ seconds for
			the BYE packet to be sent, otherwise we'll just leave the session
			without sending a BYE packet.
			\begin{lstlisting}[frame=tb]{}
delay = RTPTime(10.0);
session.BYEDestroy(delay,"Time's up",9);
			\end{lstlisting}

			The complete code of the program is given in {\tt example2.cpp} and
			is shown on the following pages. More detailed information about
			the {\tt RTPSession} class can be found in section \ref{rtpsession}.

			\newpage
			\lstinputlisting{../examples/example2.cpp}
			\newpage
			
		\subsection{The complete API}

			Here, the complete API of the library will be explained. This
			will be done in a more or less bottom-to-top fashion.

			\subsubsection{Library version}\headerfile{rtplibraryversion.h}
				
				The {\tt RTPLibraryVersion} class has a static member which
				creates an instance of this class:
				\begin{verbatim}
					static RTPLibraryVersion GetVersion();
				\end{verbatim}

				The user can access the version data using the following
				member functions:
				\begin{itemize}
					\item {\tt int GetMajorNumber() const}\\
						Returns the major version number.
					\item {\tt int GetMinorNumber() const}\\
						Returns the minor version number.
					\item {\tt int GetDebugNumber() const}\\
						Returns the debug version number.
					\item {\tt std::string GetVersionString() const}\\
						Returns a string describing the library version.
				\end{itemize}
			
			\subsubsection{Error codes}\headerfile{rtperrors.h}

				Unless specified otherwise, functions with a return type {\tt int}
				will return a negative value when an error occurred and zero or a
				positive value upon success. A description of the error code can
				be obtained by using the following function:
				\begin{verbatim}
					std::string RTPGetErrorString(int errcode)
				\end{verbatim}
			
			\subsubsection{Time utilities}\headerfile{rtptimeutilities.h}

				\Paragraph{\tt RTPNTPTime}

					This is a simple wrapper for the most significant word (MSW)
					and least significant word (LSW) of an NTP timestamp. The
					class has the following members:
					\begin{itemize}
						\item {\tt RTPNTPTime(u\_int32\_t m, u\_int32\_t l)}\\
							This constructor creates and instance with MSW {\tt m}
							and LSW {\tt l}.
						\item {\tt u\_int32\_t GetMSW() const}\\
							Returns the most significant word.
						\item {\tt u\_int32\_t GetLSW() const}\\
							Returns the least significant word.
					\end{itemize}
	
				\Paragraph{\tt RTPTime}
					
					This class is used to specify wallclock time, delay intervals
					etc. It stores a number of seconds and a number of microseconds and
					it has the following interface:
					\begin{itemize}
						\item {\tt RTPTime(u\_int32\_t seconds, u\_int32\_t microseconds)}\\
							Creates an instance corresponding to {\tt seconds} and
							{\tt microseconds}.
						\item {\tt RTPTime(double t)}\\
							Creates an {\tt RTPTime} instance representing {\tt t} which
							is expressed in units of seconds.
						\item {\tt RTPTime(RTPNTPTime ntptime)}\\
							Creates an instance that corresponds to {\tt ntptime}. If
							the conversion cannot be made, both the seconds and the
							microseconds are set to zero.
						\item {\tt u\_int32\_t GetSeconds() const}\\
							Returns the number of seconds stored in this instance.
						\item {\tt u\_int32\_t GetMicroSeconds() const}\\
							Returns the number of microseconds stored in this instance.
						\item {\tt double GetDouble() const}\\
							Returns the time stored in this instance, expressed in
							units of seconds.
						\item {\tt RTPNTPTime GetNTPTime() const}\\
							Returns the NTP time corresponding to the time stored in
							this instance.
						\item {\tt static RTPTime CurrentTime()}\\
							Returns an RTPTime instance representing the current
							wallclock time. This is expressed as a number of seconds
							since 00:00:00 UTC, January 1, 1970.
						\item {\tt static void Wait(const RTPTime \&delay)}\\
							This function waits the amount of time specified in
							{\tt delay}.
					\end{itemize}

					The following operators are defined in the {\tt RTPTime} class:
					\begin{itemize}
						\item {\tt operator-=}
						\item {\tt operator+=}
						\item {\tt operator<}
						\item {\tt operator>}
						\item {\tt operator<=}
						\item {\tt operator>=}
					\end{itemize}

			\subsubsection{\tt RTPRandom}\headerfile{rtprandom.h}
				
				The {\tt RTPRandom} class can be used to generate random numbers.
				It has the following member functions:
				\begin{itemize}
					\item {\tt u\_int8\_t GetRandom8()}\\
						Returns a random eight bit value.
					\item {\tt u\_int16\_t GetRandom16()}\\
						Returns a random sixteen bit value.
					\item {\tt u\_int32\_t GetRandom32()}\\
						Returns a random thirty-two bit value.
					\item {\tt double GetRandomDouble()}\\
						Returns a random number between $0.0$ and $1.0$.
				\end{itemize}
				
			\subsubsection{\tt RTCPSDESInfo}\headerfile{rtcpsdesinfo.h}

				The class {\tt RTCPSDESInfo} is a container for RTCP SDES
				information. The interface is the following:
				\begin{itemize}
					\item {\tt void Clear()}\\
						Clears all SDES information.
					\item {\tt int SetCNAME(const u\_int8\_t *s, size\_t l)}\\
						Sets the SDES CNAME item to {\tt s} with length {\tt l}.
					\item {\tt int SetName(const u\_int8\_t *s, size\_t l)}\\
						Sets the SDES name item to {\tt s} with length {\tt l}.
					\item {\tt int SetEMail(const u\_int8\_t *s, size\_t l)}\\
						Sets the SDES e-mail item to {\tt s} with length {\tt l}.
					\item {\tt int SetPhone(const u\_int8\_t *s, size\_t l)}\\
						Sets the SDES phone item to {\tt s} with length {\tt l}.
					\item {\tt int SetLocation(const u\_int8\_t *s, size\_t l)}\\
						Sets the SDES location item to {\tt s} with length {\tt l}.
					\item {\tt int SetTool(const u\_int8\_t *s, size\_t l)}\\
						Sets the SDES tool item to {\tt s} with length {\tt l}.
					\item {\tt int SetNote(const u\_int8\_t *s, size\_t l)}\\
						Sets the SDES note item to {\tt s} with length {\tt l}.
					\item {\tt u\_int8\_t *GetCNAME(size\_t *len) const}\\
						Returns the SDES CNAME item and stores its length in {\tt len}.
					\item {\tt u\_int8\_t *GetName(size\_t *len) const}\\
						Returns the SDES name item and stores its length in {\tt len}.
					\item {\tt u\_int8\_t *GetEMail(size\_t *len) const}\\
						Returns the SDES e-mail item and stores its length in {\tt len}.
					\item {\tt u\_int8\_t *GetPhone(size\_t *len) const}\\
						Returns the SDES phone item and stores its length in {\tt len}.
					\item {\tt u\_int8\_t *GetLocation(size\_t *len) const}\\
						Returns the SDES location item and stores its length in {\tt len}.
					\item {\tt u\_int8\_t *GetTool(size\_t *len) const}\\
						Returns the SDES tool item and stores its length in {\tt len}.
					\item {\tt u\_int8\_t *GetNote(size\_t *len) const }\\
						Returns the SDES note item and stores its length in {\tt len}.
				\end{itemize}

				If SDES private item support was enabled at compile time, the following
				member functions are also available:
				\begin{itemize}
					\item {\tt int SetPrivateValue(const u\_int8\_t *prefix, size\_t prefixlen, const u\_int8\_t *value, size\_t valuelen)}\\
						Sets the entry for the prefix string specified by {\tt prefix} with
						length {\tt prefixlen} to contain the value string specified by
						{\tt value} with length {\tt valuelen}. If the maximum allowed
						number of prefixes was reached, the error code
						{\tt ERR\_\-RTP\_\-SDES\_\-MAX\-PRIV\-ITEMS} is returned.
					\item {\tt int DeletePrivatePrefix(const u\_int8\_t *s, size\_t len)}\\
						Deletes the entry for the prefix specified by {\tt s} with length
						{\tt len}.
					\item {\tt void GotoFirstPrivateValue()}\\
						Starts the iteration over the stored SDES private item prefixes
						and their associated values.
					\item {\tt bool GetNextPrivateValue(u\_int8\_t **prefix, size\_t *prefixlen, u\_int8\_t **value, size\_t *valuelen)}\\
						If available, returns {\tt true} and stores the next SDES
						private item prefix in {\tt prefix} and its length in
						{\tt prefixlen}. The associated value and its length are
						then stored in {\tt value} and {\tt valuelen}. Otherwise,
						it returns {\tt false}.
					\item {\tt bool GetPrivateValue(const u\_int8\_t *prefix, size\_t prefixlen, u\_int8\_t **value, size\_t *valuelen) const}\\ 
						Looks for the entry which corresponds to the SDES private
						item prefix {\tt prefix} with length {\tt prefixlen}. If found,
						the function returns {\tt true} and stores the associated
						value and its length in {\tt value} and {\tt valuelen}
						respectively.
					\end{itemize}

            \subsubsection{\tt RTPTransmitter}\headerfile{rtptransmitter.h}

				The abstract class {\tt RTPTransmitter} specifies the interface for
				actual transmission components. Currently, three implementations exist:
				an UDP over IPv4 transmitter, an UDP over IPv6 transmitter and a 
				GStreamer transmission component. The {\tt TransmissionProtocol} type 
				is used to specify a specific kind of transmitter:
				\begin{verbatim}
					enum TransmissionProtocol { IPv4UDPProto, IPv6UDPProto, 
					                            IPv4GSTProto, UserDefinedProto };
				\end{verbatim}
				The {\tt UserDefinedProto} can be used to select your own transmission
				component when using the {\tt RTPSession} class. In this case, you'll
				have to implement the {\tt RTPSession} member function 
				{\tt NewUserDefinedTransmitter()} which should return a pointer to your
				own {\tt RTPTransmitter} implementation.

				Three kind of receive modes can be specified using the {\tt ReceiveMode}
				type:
				\begin{verbatim}
					enum ReceiveMode { AcceptAll, AcceptSome, IgnoreSome };
				\end{verbatim}
				Depending on the mode set, incoming data is processed differently:
				\begin{itemize}
					\item {\tt AcceptAll}\\
						All incoming data is accepted, no matter where it originated
						from.
					\item {\tt AcceptSome}\\
						Only data coming from specific sources will be accepted.
					\item {\tt IgnoreSome}\\
						All incoming data is accepted, except for data coming from
						a specific set of sources.
				\end{itemize}