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.