41
V. Liberatore
Pervasive Computing
RTPlib
Session Initialization
RTPCreate();
RTPMemberInfoSetSDES();
…
…
Open a Session
...
RTPOpenConnection();
...
Usage
...
RTPSend();
RTPReceive();
...
Close a Session
...
RTPCloseConnection();
RTPDestroy();
...
RTPCreate():
The first of the first of these is RTPCreate(), which establishes a context. A context is an identifier used by the library to determine which RTP session a function call is to be associated with. An application can run many sessions at the same time, each created with a separate call to RTPCreate, resulting in a different context for each.

RTPSessionSetBandwidth():
RTCP packets are sent at a rate that depends on the session bandwidth. This is a global parameter for the RTP session. The application should set this value before calling RTPOpenConnection() in order to ensure proper RTCP transmission rates. If it is not set, the default rate of 120 kbps.

RTPMemberInfoSetSDES():
One RTCP packet type, SDES, contains information about each user. This includes the name, email, and CNAME for the user. It is the responsibility of the application to set these fields. In particular, the CNAME field MUST be set prior to calling RTPOpenConnection. All of the other SDES fields are optional.

RTPSend():
The RTPSend() function is used to tell the library to send an RTP packet. It requires the user to pass a pointer to a buffer, a length, a value for the marker field in the RTP header, an increment for the timestamp, and the context. The library will take the buffer, add the RTP header, perform any required operations, and send the packet. The library will automatically send RTCP packets. The initial timestamp and sequence number are chosen randomly.

RTPReceive():

In order to know if a packet is available for reading, a process can block, it can poll, or use any other kind of mechanism. The library does not dictate this policy, it is up to the user to determine when data is available for reading.
Steps involved in receiving a packet:
   1. The functions RTPSessionGetRTPSocket() and RTPSessionGetRTCPSocket() are used. They take as input the context and a pointer to a    socket. When they return, the socket has been filled in. The user application may then check for the presence on an RTP packet on these sockets in    any fashion.
   2. When a packet is present on either socket, the application calls the function RTPReceive(). This function takes the context, the socket on which    data is present, a pointer to a buffer, and a pointer to a length value. The length value should be initialized to the amount of room in the buffer.    The library will read and process the RTP or RTCP packet. For RTCP, it will perform all statistics collection and parsing. Generally, there will be no    further action required from the user. For an RTP packet, the library will also update some statistics and variables. The buffer will be filled in with    the entire RTP/RTCP packet, including the header.
   3. Once RTPReceive() is complete, the user may want to access data in the packet if it is an RTP packet. However, the packet in the original    buffer used in the RTPReceive still contains the header. To gain access to the header fields, and the payload, the function RTPGetRTPPacket() is    provided. This function accepts the buffer as an input, and returns a pointer to an RTP packet structure. This pointer is of type rtp_packet, and    contains fields for the various RTP headers, and a pointer to the payload. The user application can then access these fields for whatever purposes it    likes.

RTPCloseConnection():
When the function RTPCloseConnection() is called, it closes all active receive sockets, sends a BYE packet, and then closes all send sockets. It does not delete internal storage or statistics that have been collected, however. RTPCloseConnection() accepts a reason string. This string is sent in the BYE packet. If set to NULL, the library will not include any reason in the BYE.

RTPDestroy():
It destroys all internal information about the session. It takes the context as its sole argument, and frees all memory associated with the context.