/**\mainpage JRTPLIB * * \author Jori Liesenborgs * \author Developed at the The Expertise Centre for Digital Media (EDM), a research  *         institute of the Hasselt University * * \section ack 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. *  * \section intro Introduction * 	 * 	This document describes JRTPLIB, 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 idea Design idea *		 *		The library provides several classes which can be helpful in *		creating RTP applications. Most users will probably need just the *		RTPSession class for building an application. This class *		provides the necessary functions for sending RTP data and handles *		the RTCP part internally. * *	\subsection changes 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 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 *		RTPTransmitter. This makes it easy for different underlying *		protocols to be supported. Currently there is support for UDP over *		IPv4 and UDP over IPv6. * *		For applications such as a mixer or translator using the *		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. * \section copyright Copyright license * 	 * 	The library code uses the following copyright license: * * 	\code * 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. * 	\endcode * * 	There are two reasons 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 starting Getting started with the RTPSession class * 	 * 	To use RTP, you'll have to create an RTPSession object. The constructor * 	accepts one parameter, an instance of RTPMemoryManager. By default, no * 	memory manager will be used. For now, we'll keep it simple, so this is * 	our code so far: * * 	\code * RTPSession session;  * 	\endcode *  * 	To actually create the session, you'll have to call the Create member  * 	function which takes three arguments: the first one is of type RTPSessionParams  * 	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: * * 	\code * RTPSessionParams sessionparams; * * sessionparams.SetOwnTimestampUnit(1.0/8000.0); * 	\endcode * * 	The other session parameters will probably depend on the actual RTP profile * 	you intend to work with.  * * 	The second argument of the Create function is a pointer to an RTPTransmissionParams  * 	instance and describes the parameters for the transmission component. The third * 	parameter selects the type of transmission component which will be used. By default, * 	an UDP over IPv4 transmitter is used, and for this particular transmitter, the * 	transmission parameters should be of type RTPUDPv4TransmissionParams. Assuming  * 	that we want our RTP portbase to be 8000, we can do the following: * * 	\code * RTPUDPv4TransmissionParams transparams; *  * transparams.SetPortbase(8000); * 	\endcode * * 	Now, we're ready to call the Create member function of RTPSession. The return  * 	value is stored in the integer \c 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 * 	RTPGetErrorString: * * 	\code * int status = session.Create(sessionparams,&transparams); * if (status < 0) * { *	std::cerr << RTPGetErrorString(status) << std::endl; *	exit(-1); * } *	\endcode * *	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 RTPSession member function AddDestination. This  *	function takes an argument of type RTPAddress. This is an abstract  *	class and for the UDP over IPv4 transmitter the actual class to be  *	used is 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: *	 *	\code * uint8_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); * } * 	\endcode * * 	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 RTPSession * 	member function 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: * 	 * 	\code * session.SetDefaultPayloadType(96); * session.SetDefaultMark(false); * session.SetDefaultTimestampIncrement(160); * 	\endcode * * 	Next, we'll create the buffer which contains 160 silence samples * 	and create an 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. * 	 * 	\code * uint8_t silencebuffer[160]; *  * for (int i = 0 ; i < 160 ; i++) * 	silencebuffer[i] = 128; *  * RTPTime delay(0.020); * RTPTime starttime = RTPTime::CurrentTime(); * 	\endcode * * 	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: *	 *	\code * 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; * } * 	\endcode * * 	Information about participants in the session, packet retrieval * 	etc, has to be done between calls to the RTPSession member * 	functions BeginDataAccess and 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  * 	GotoFirstSource and GotoNextSource member functions. Packets from  * 	the currently selected participant can be retrieved using the  * 	GetNextPacket member function which returns a pointer to an  * 	instance of the 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: * 	 * 	\code * session.BeginDataAccess(); * if (session.GotoFirstSource()) * { * 	do * 	{ * 		RTPPacket *packet; * 		while ((packet = session.GetNextPacket()) != 0) * 		{ * 			std::cout << "Got packet with extended sequence number "  * 			          << packet->GetExtendedSequenceNumber()  * 					  << " from SSRC " << packet->GetSSRC()  * 					  << std::endl; * 			session.DeletePacket(packet); * 		} * 	} while (session.GotoNextSource()); * } * session.EndDataAccess(); *	\endcode * *	Information about the currently selected source can be obtained *	by using the GetCurrentSourceInfo member function of the RTPSession class.  *	This function returns a pointer to an instance of  RTPSourceData which  *	contains all information about that source: sender reports from that  *	source, receiver reports, SDES info etc.  * *	When the main loop is finished, we'll send a BYE packet to inform other  *	participants of our departure and clean up the 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. * 	 * 	\code * delay = RTPTime(10.0); * session.BYEDestroy(delay,"Time's up",9); *	\endcode *	 *	The complete code of the program is given in \c example2.cpp. * * \section errors Error codes * *	Unless specified otherwise, functions with a return type \c 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 RTPGetErrorString function, declared  *  	in rtperrors.h                                             *  * \section memory Memory management *  *	You can write you own memory manager by deriving a class from RTPMemoryManager. *	The following example shows a very basic implementation. *	 *	\code * class MyMemoryManager : public RTPMemoryManager * { * public: *	MyMemoryManager() { } *	~MyMemoryManager() { } *	 *	void *AllocateBuffer(size_t numbytes, int memtype) *	{ *		return malloc(numbytes); *	} * *	void FreeBuffer(void *p) *	{ *		free(p); *	} * }; *	\endcode *  * 	In the constructor of RTPSession, you can specify that you would like to use * 	this memory manager: * 	 * 	\code * MyMemoryManager mgr; * RTPSession session(&mgr); * 	\endcode * * 	Now, all memory allocation and deallocation will be done using the AllocateBuffer * 	and FreeBuffer implementations of \c mgr. * * 	The second parameter of the RTPMemoryManager::AllocateBuffer member function * 	indicates what the purpose is of this memory block. This allows you to handle * 	different kinds of data in different ways. * * 	With the introduction of the memory management system, the RTPSession class was * 	extended with member function RTPSession::DeletePacket and RTPSession::DeleteTransmissionInfo. * 	These functions should be used to deallocate RTPPacket instances and RTPTransmissionInfo * 	instances respectively. * * \section contact Contact * * 	If you have any questions, remarks or requests about the library or * 	if you think you've discovered a bug, you can contact me at * 	\c jori(\c dot)\c liesenborgs(\c at)\c gmail(\c dot)\c com * * 	The home page of the library is *	http://research.edm.uhasselt.be/jori/jrtplib/jrtplib.html * * 	There is also a mailing list for the library. To subscribe to the list,  * 	send an e-mail with the text \c subscribe \c jrtplib as the message body  * 	(not the subject) to \c majordomo(\c at)\c edm(\c dot)\c uhasselt(\c dot)\c be  * 	and you'll receive further instructions. */