\documentstyle[12pt,a4]{article}\begin{document}\author{Jori Liesenborgs (jori@lumumba.luc.ac.be)}\title{JRTPLIB (v2.8) - TUTORIAL}\date{6th January 2004}\maketitle\section{Getting started}\subsection{Creating a session}To be able to do anything useful with the library, you'll have to create a RTPsession. To do this, you have to create a variable of type RTPSession and callits Create member. The function 'Create' takes one parameter which specifiesthe portbase for the session. So a simple (and totally useless) program wouldlook something like this:    \begin{verbatim}    #include "rtpsession.h"            int main(void)    {            RTPSession sess;                sess.Create(5000);        return 0;    }    \end{verbatim}\subsection{Errors}What if something goes wrong and the session can't be created ? Well, in thelibrary, all functions returning an 'int' return a negative value if an erroroccurred, so you can detect if a function was successfull or not. Now, an'int' is probably not the most understandable error message and that's why thelibrary has the function RTPGetErrorString. This takes the return value of afunction as an argument and returns a pointer to a string which describes theerror. We could change the previous program to write out what happened:    \begin{verbatim}    #include <stdio.h>    #include "rtpsession.h"            int main(void)    {        RTPSession sess;        int status;        char *msg;                    status = sess.Create(5000);        msg = RTPGetErrorString(status);        printf("%s\n",msg);        return 0;    }    \end{verbatim}\subsection{Other initialization}One thing you'll probably need to initialize is the timestamp unit, since thisvalue is needed for various calculations. The timestamp unit can be set throughthe use of the RTPSession member function SetTimestampUnit. This function takesone argument: the timestamp unit in seconds.            For example, if you're using the session to send 8000Hz sampled audio,you'd normally use the number of samples as RTP timestamp. Since the timestampwould then increment by 8000 each second, the timestamp unit would be 1/8000seconds. This is the default value which is used in the library. For 44100Hzsampling, the code would look something like this:        \begin{verbatim}        sess.SetTimestampUnit(1.0/44100.0);        \end{verbatim}        \section{Sending and receiving data}\subsection{Specifying destinations}Before you can send data, you must specify to which destinations each packetshould be sent. You can specify this using the RTPSession member functionsAddDestination, DeleteDestination and ClearDestinations. For example:        \begin{verbatim}        unsigned long addr = ntohl(inet\_addr("127.0.0.1"));        sess.AddDestination(addr,5000);        \end{verbatim}would prepare the session to send data to the local host, to port 5000. Notethat the 'ntohl' function had to be used because 'inet\_addr' returns anaddress in network byte order and the parameters functions has to be in hostbyte order.\subsection{Sending RTP packets}When you have entered the destinations for the RTP packets, you can start tosend data to all destinations by using the SendPacket member function ofRTPSession. This is an overloaded member function. In one version you haveto pass the RTP payload type, the 'mark' flag, and the timestamp incrementas parameters. Here's an example:        \begin{verbatim}        sess.SendPacket("1234567890",10,0,false,10);        \end{verbatim}The first parameter is the data which has to be sent, the second is the lengthof the data. Next come the payload type and the 'mark' flag. Finally, the lastargument specifies the amount by which the timestamp should be incremented.If you often need the same payload type, 'mark' flag and timestamp increment,you can use the second version of the function. To use it, you must firstspecify default values for those parameters. This can be done with theRTPSession member functions SetDefaultPayloadType, SetDefaultMark andSetDefaultTimeStampIncrement. Then, you can use the SendPacket function withoutthe last three arguments. For example, once you've entered the default values        \begin{verbatim}        sess.SetDefaultPayloadType(0);        sess.SetDefaultMark(false);        sess.SetDefaultTimeStampIncrement(10);        \end{verbatim}you can do exactly what the previous example of SendPacket did, by simply doingthis:        \begin{verbatim}        sess.SendPacket("1234567890",10);        \end{verbatim}\subsection{Receiving RTP packets}First of all, you should call the RTPSession member function PollData on aregular basis. This function processes incoming RTP and RTCP packets. Toaccess the received RTP packets, you'll typically iterate over the differentparticipants in the session and get each one's RTP packets. You can iterateover the participants using the functions GotoFirstSource and GotoNextSource.If you're only interested in the participants which have data you didn't getyet, you can use GotoFirstSourceWithData and GotoNextSourceWithData. All ofthese functions return true if there's a source available and false if not.When a source is available, you can use the function GetNextPacket to get aRTP packet from this source. When you don't need the RTP packet anymore, makesure you delete it. Here's some example code:        \begin{verbatim}        if (sess.GotoFirstSourceWithData())        {            do            {                RTPPacket *pack;                                pack = sess.GetNextPacket();                                // process packet                                delete pack;                            } while (sess.GotoNextSourceWithData());        }        \end{verbatim}For a description about the RTPPacket class, you should take a look at thereference manual (manual.txt).\subsection{Receive modes}There are three receive modes. A receive mode determines which incomingpackets are accepted and which are ignored. You can set the receive mode byusing the RTPSession member function SetReceiveMode.            The first mode, RECEIVEMODE\_ALL, is the default. When you've enabledthis mode simply all incoming packets are accepted.            The second mode, RECEIVEMODE\_IGNORESOME, accepts all incoming packetsexcept the ones which are coming from certain senders. You can determine whichpackets are ignored by using AddToIgnoreList, DeleteFromIgnoreList andClearIgnoreList.            The last mode, RECEIVEMODE\_ACCEPTSOME, ignores all incoming packetsexcept the ones which are coming from certain senders. You can specify whichpackets are accepted by using AddToAcceptList, DeleteFromAcceptList andClearAcceptList.The AddTo... and DeleteFrom... functions take three arguments. The first oneis the IP address of the involved sender. The second one is a flag. If set totrue, all packets originating from the previous IP address are ignored oraccepted and the third parameter is ignored. If set to false, the thirdparameter specifies a port number. When this is the case, only packets withthe specified IP-port combination are ignored or accepted.            An important note is that the port which has to be specified is theport from which the RTP packets originate and this does not have to be the RTPportbase. More important, in this library those ports are not the same ! Theport from which packets are sent can be retrieved by the function GetSendPort.\subsection{Multicasting}\subsubsection{Sending to a multicast group}To be able to send to a multicast group you don't have to do anything special.You can simply add the multicast address for that group to the list ofdestinations and RTP and RTCP data will automatically be sent to it.            The only thing that probably needs to be set is the Time To Live (TTL)field for multicast packets. This is a field in the IP header which controlshow far (how many hops) a packet can travel. The value is initialized to oneso normally a multicast packet will not leave the local network. If you dorequire this, you can alter the value by using the RTPSession member functionSetMulticastTTL.\subsubsection{Receicing from a multicast group}You must first join a multicast group to be able to receive packets which aresent to it. You can control from which multicast groups you want to receivedata by using the functions JoinMulticastGroup, LeaveMulticastGroup andLeaveAllMulticastGroups. The first two of these functions take a multicastIP address as an argument.\subsection{About sending and receiving RTCP packets}You don't have to worry about sending and receiving RTCP packets. The librarytakes care of this. The only thing you have to make sure is that the PollDatais called on a regular basis. During a poll, the library reads incoming RTCPpackets and processes the information. It also checks if it's time to sendRTCP packets and if so, it sends them. This check is also performed when youcall the SendPacket function.\section{Control information}\subsection{Own information}You can set your local information by using the following member functions ofRTPSession: SetLocalName, SetLocalEMail, SetLocalLocation, SetLocalPhone,SetLocalTool and SetLocalNote. All of these functions take two parameters: thefirst one is a 'char *' to the data, the second one specifies how many bytesof the data should be used. For example,        \begin{verbatim}        rtpsess.SetLocalEMail("user@myhost.org",15);        \end{verbatim}could be used to set the local E-mail address.You can specify which information should be sent by using the followingRTPSession member functions: EnableSendName, EnableSendEMail,EnableSendLocation, EnableSendPhone, EnableSendTool and EnableSendNote. All ofthese functions take a boolean as argument. This argument specifies whether ornot to send certain information about the current session.\subsection{Other sessions' information}To retrieve the information about other participating RTP sessions, you haveto specify which source's information you want. You can do this by iteratingover the sources using the GotoFirst... and GotoNext... functions, as wasdescribed in section 2.3. Then, you can do a call to the RTPSession memberfunction GetCurrentSourceInfo. This function returns a data structure of typeRTPSourceData. You can use this to look at the available information aboutthe source.            There is another way to retrieve information about a source. To beable to use it, you already have to know the sychronization source identifier(SSRC) of the source. You can then call the RTPSession member functionGetSourceInfo. This function takes a SSRC as argument and returns a datastructure of type RTPSourceData.            For more information about the RTPSourceData class and all of itsmember functions, you should take a look at the reference manual, whichcan be found in the file 'manual.txt'.\section{Handlers}You can specify handlers for certain types of events. For example: when asource joins the session, when a source times out, when SSRC identifierscollide, ...            For more information about the use of handlers you should take a lookat the reference manual (manual.txt).\end{document}