\documentstyle[12pt,a4]{article}\begin{document}\title{JRTPLIB (v2.8) -  REFERENCE MANUAL}\author{Jori Liesenborgs (jori@lumumba.luc.ac.be)}\date{6th January 2004}\maketitle\section{General Information}\subsection{Description}JRTPLIB (Jori's RTP Library) is an object oriented library for the use of RTP(Real-Time Transport Protocol). Normally, it should follow the specificationsaccording to RFC 1889. This textfile describes the classes and functions which form the interface of the library. If some of the used terms aren'tclear, you should consult RFC 1889.\subsection{Author \& contact}The library was written completely from scratch by Jori Liesenborgs. Anycomments, bugreports, ideas for improvements,... can be sent to the followinge-mail address:		jori@lumumba.luc.ac.be\subsection{Platforms}The library uses the socket mechanism for network communications. This meansit can be compiled (perhaps with some minor modifications) and used on various platforms. It has been tested on a Linux platform and on a Windowsplatform (using the Winsock library). It's also known to work on Solaris,HP-UX, FreeBSD and VxWorks platforms.\subsection{Important general information}All of the functions with return type 'int', return 0 or more on success. Thus, with these functions an error is always indicated by a negative number.\subsection{What the library doesn't do}An important remark is that the library will not necessarily filter out duplicate packets. The packets from one sender which are in the received packetsqueue after a call to 'Poll', won't be duplicates of other packets in the queue.Once out of the queue, however, there is no guarantee that some accepted packet won't have been received already. There is a good reason for this: the application using the library probably hasmore information about which packets are expected. Using this information it's possible to filter out duplicate packets using less memory than would be required inside the library.\subsection{Copyright \& disclaimer}  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.\section{class RTPSession}\subsection{Description}This class is used to set up a RTP session.\subsection{Member functions}\begin{itemize}\item {\tt int Create(int localportbase)}\\	This function attempts to create a RTP session with a given portbase.	It creates an initial timestamp and an initial packet sequence	number. It also creates a local synchronization source identifier	(SSRC). When doing this, the list of illegal SSRCs is checked. This	list can be modified by the functions AddIllegalLocalSSRC,	DeleteIllegalLocalSSRC and ClearInvalidLocalSSRCList. In a newly	created session, there are no destinations to send the RTP and RTCP	packets to. Destinations can be set by the functions AddDestination,	DeleteDestination and ClearDestinations.\item {\tt int GetPortBase()}\\	Returns the portbase of this session.\item {\tt int GetLocalSSRC(unsigned long *ssrc)}\\	This function retrieves the local synchronization source identifier.\item {\tt int Destroy()}\\	Destroys the session. All info is destroyed, including destinations,	default values for SendPacket, invalid local SSRC values,...	\item {\tt int GetRTPSocket(RTPSOCKET *sock)}\\	Retrieves the RTP socket (used for receiving RTP data). This way,	the socket can be used outside the library. A practical use would be	in the 'select' function.\item {\tt int GetRTCPSocket(RTPSOCKET *sock)}\\	Retrieves the RTCP socket (used for receiving RTCP data). This way,	the socket can be used outside the library. A practical use would	be in the 'select' function.\item {\tt int GetSendSocket(RTPSOCKET *sock)}\\	Retrieves the socket which is used for sending the RTP data. This	way, the socket can be used outside the library. A practical use	would be in the 'select' function.\item {\tt int GetSendPort()}\\	Retrieves the port to which the sending socket was bound.\item {\tt int GetLocalIP(unsigned long *ip)}\\ 	Puts the local IP address which is used by the library in 'ip'.\item {\tt int SetToS(int tos)}\\ 	Set the IP type of service (ToS) field for outgoing RTP and RTCP	packets. \item {\tt int AddDestination(unsigned long remoteIP,int remoteportbase)}\\ 	Adds a destination to send RTP and RTCP data to.\item {\tt int DeleteDestination(unsigned long remoteIP,int remoteportbase)}\\	Deletes a destination from the list of destinations.	\item {\tt void ClearDestinations()}\\	Clears the list of destinations.\item {\tt bool SupportsMulticasting()}\\	Returns 'true' if the library is compiled with multicasting support,	otherwise the function returns 'false'.\item {\tt int JoinMulticastGroup(unsigned long mcastIP)}\\ 	This function attempts to join the multicast group specified by the 	address in 'mcastIP'. Note that you only have to join a multicast 	group to receive packets which are sent to it. You don't have to be 	in a group to send packets to it.\item {\tt int LeaveMulticastGroup(unsigned long mcastIP)}\\ 	This function attempts to leave the multicast group specified by the 	address in 'mcastIP'\item {\tt void LeaveAllMulticastGroups()}\\ 	Leaves all multicast groups to which the session was previously joined 	through the use of JoinMulticastGroup 	\item {\tt int SetMulticastTTL(unsigned char ttl)}\\ 	Use this function to change the Time To Live (TTL) field for multicast 	packets. The TTL field is a field in the IP header which determines 	the lifetime for a packet (normally, this the maximum number of hops 	for a packet).	\item {\tt int SendPacket(void *data,int len)}\\	Sends a RTP packet with a payload containing of 'len' bytes of	'data'. To be able to use this function, you must first set the	default values for the payload type, the mark bit and the timestamp	increment value. These default values can be set with the functions	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement.\item {\tt int SendPacket(void *data,int len,unsigned char pt,bool mark,unsigned long timestampinc)}\\	Sends a RTP packet with a payload containing of 'len' bytes of	'data'. The packet type is specified by 'pt', the mark bit by 'mark'	and the timestamp increment by 'timestampinc'. The values set by	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement	are ignored.	\item {\tt int SendPacket(void *data,int len,unsigned short hdrextID,void *hdrextdata,int numhdrextwords)}\\	Sends a RTP packet with a payload containing of 'len' bytes of	'data'. To be able to use this function, you must first set the	default values for the payload type, the mark bit and the timestamp	increment value. These default values can be set with the functions	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement.	This function also causes a RTP header extension to be included in the	packet. This extension has identifier 'hdrextID' and the length of the	extension data is specified in 32-bit words by 'numhdrextwords'. The	data itself is contained in 'hdrextdata'.\item {\tt int SendPacket(void *data,int len,unsigned char pt,bool mark,unsigned long timestampinc,unsigned short hdrextID,void *hdrextdata,int numhdrextwords)}\\	Sends a RTP packet with a payload containing of 'len' bytes of	'data'. The packet type is specified by 'pt', the mark bit by 'mark'	and the timestamp increment by 'timestampinc'. The values set by	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement	are ignored. This function also causes a RTP header extension to be	included in the packet. This extension has identifier 'hdrextID' and	the length of the extension data is specified in 32-bit words by	'numhdrextwords'. The data itself is contained in 'hdrextdata'.\item {\tt void SetDefaultPayloadType(unsigned char pt)}\\	Sets the default packet type.\item {\tt void SetDefaultMark(bool mark)}\\	Sets the default value for the mark bit.\item {\tt void SetDefaultTimeStampIncrement(unsigned long inc)}\\	Sets the default timestamp increment value.\item {\tt int IncrementTimeStamp(unsigned long inc)}\\	Increments the current timestamp with value 'inc'.\item {\tt int IncrementTimeStampDefault()}\\	Increments the current timestamp with the default value, set by the	function SetDefaultTimeStampIncrement.\item {\tt int PollData()}\\	Checks for data on RTP and RTCP ports. If any data is present, it's	immediately processed. To retrieve RTP packets or info gathered from	RTCP packets, you can use the functions GotoFirstSource, GotoNextSource,	GotoFirstSourceWithData, GotoNextSourceWithData, GetNextPacket,	GetCurrentSourceInfo and GetSourceInfo. After calling PollData, you	should always use one of the GotoFirst functions before one of the	GotoNext functions, as the list of participating sources may have	changed: sources could have joined the session or may have left the	session.	Note that currently own RTCP packets are always discarded.\item {\tt bool GotoFirstSource()}\\	This function goes sets a pointer to the first participating source.	You can use this function to start an iteration over the participating	sources. It returns 'true' if there are any participating sources,	otherwise the function returns 'false'.	\item {\tt bool GotoNextSource()}\\	You can use this function to iterate over the participating sources.	If there is a source that hasn't been processed yet, the function	returns 'true'. If all sources were covered, 'false' is returned.\item {\tt bool GotoFirstSourceWithData()}\\	This function is similar to GotoFirstSource, but it skips sources	that haven't got any data pending on their input queues. Returns	'true' is a source with data on its queue exists. Returns 'false'	otherwise.\item {\tt bool GotoNextSourceWithData()}\\	This function is similar to GotoNextSource, but it skips sources	that haven't got any data pending on their input queues. If there	aren't any sources left to process 'false' is returned. If another	source was found, 'true' is returned.\item {\tt RTPPacket *GetNextPacket()}\\	When iterating over the participating sources with GotoFirst and	GotoNext functions, you can use this function to extract a packet	from the current source's queue. If data is available, the function	returns an instance of the class RTPPacket containing the data.	Otherwise, NULL is returned. If a packet is returned, it must be	destroyed by a call to 'delete' when it is no longer needed.\item {\tt RTPSourceData *GetCurrentSourceInfo()}\\	When iterating over the participating sources with GotoFirst and	GotoNext functions, you can use this function to get information	about the current source. If the iteration has stopped NULL is	returned, otherwise the function returns an instance of the class	RTPSourceData containing the info about the current source.\item {\tt RTPSourceData *GetSourceInfo(unsigned long ssrc)}\\	Retrieves information about the participating source with	synchronization source identifier 'ssrc'. If there is an entry for	that source, an instance of the class RTPSourceData is returned.	Otherwise the function returns NULL.\item {\tt AddInvalidLocalSSRC(unsigned long ssrc)}\\	Adds the synchronization source identifier 'ssrc' to the list of	invalid local sychronization source identifiers. This list is checked	when the local SSRC identifier is created.\item {\tt int RemoveInvalidLocalSSRC(unsigned long ssrc)}\\	Removes an entry from the list of invalid local SSRCs.\item {\tt void ClearInvalidLocalSSRCList()}\\	Clears the list of invalid local SSRCs.\item {\tt int AddCSRC(unsigned long csrc)}\\	Adds an entry to the list of contributing sources. Info about these	sources can be set with SetCSRC functions.\item {\tt int DeleteCSRC(unsigned long csrc)}\\	Deletes an entry from the list of contributing sources.\item {\tt void ClearCSRCList()}\\	Clears the list of contributing sources.\item {\tt int SetReceiveMode(int mode)}\\	Sets the receive mode. The parameter 'mode' has three legal values:	\begin{itemize}	\item RECEIVEMODE\_ALL \\		Accept all incoming data on RTP and RTCP ports.	\item RECEIVEMODE\_IGNORESOME \\		Ignore packets from the ip-port pairs in the ignore list, but		accept all other packets.			\item RECEIVEMODE\_ACCEPTSOME \\		Ignore all packets, except those whose ip-port origin is		found in the accept list.	\end{itemize}	The ignore list can be modified with the function AddToIgnoreList,	DeleteFromIgnoreList and ClearIgnoreList. The accept list can be