jni/ccrtp-android/doc/ccrtp.texi

\input texinfo    @c -*-texinfo-*-
@c %** start of header
@setfilename ccrtp.info
@settitle GNU ccRTP Manual
@afourpaper
@setchapternewpage odd
@documentlanguage en
@documentencoding ISO-8859-1
@c %** end of header

@set EDITION 1.3
@set VERSION 1.3
@set UPDATED Jan 2006

@dircategory Development
@direntry
* GNU ccRTP: (ccrtp).        GNU ccRTP Real-Time Transport Protocol Framework.
@end direntry


@c -----------------------------------------------------------------------

@c %** start of summary description and copyright
@ifnottex
GNU ccRTP is a C++ class framework for the development of Real Time
Transport Protocol (@acronym{RTP}) based applications. It is based on
GNU Common C++.

Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006 Federico Montesino Pouzols
@email{fedemp@@altern.org}.
@include fdlnotice.texi
@end ifnottex
@c %** end of summary description and copyright

@c -----------------------------------------------------------------------

@c %** start of title and copyright page
@shorttitlepage @titlefont{GNU ccRTP}
@titlepage
@sp 10
@title GNU ccRTP Manual
@subtitle A Real-Time Transport Protocol Framework based on GNU Common C++
@subtitle @value{EDITION}th Edition, covering ccRTP version @value{VERSION}
@subtitle @value{UPDATED}
@author Federico Montesino Pouzols

@page
@vskip 0pt plus 1filll
@center{Copyright @copyright{} 2001, 2002, 2003, 2004, 2005 Federico Montesino Pouzols}
@include fdlnotice.texi
@page
@end titlepage
@c %** end of title and copyright page


@c -----------------------------------------------------------------------

@c %** start of top node and master menu
@ifnottex
@node Top
@top
This manual describes GNU ccRTP, a C++ class framework for the
development of Real Time Transport Protocol (@acronym{RTP}) based
applications.

This is the edition @value{EDITION} of this manual and documents
GNU ccRTP version @value{VERSION}.
@end ifnottex


@contents


@menu
* Introduction::                What @acronym{RTP} and ccRTP are.
* Distribution::                How to get @acronym{GNU} ccRTP.
* ccRTP Overview::              The library at a glance.
* Using ccRTP::                 Programming with GNU ccRTP overview.
* Specialized Payload Formats:: Supported payload specific extensions.
* Standards Tracking::          @acronym{IETF} Standards conformance.
* Upgrading::                   Upgrading applications based on old releases.
* ccRTP Internals::             How @acronym{GNU} ccRTP is done. 
* Related Work::                Other @acronym{RTP} related libraries and tools.
* Future Work::                 Future of @acronym{RTP} and ccRTP.
* Licenses::                    Library and documentation licenses.
* Class and Data Type Index::   Index of classes and data types in ccRTP.
* Method and Function Index::   Index of methods and functions in ccRTP.
* Concept Index::               Index of concepts.
@end menu
@c %** end of top node and master menu

@c %** start of body

@c -----------------------------------------------------------------------
@node Introduction
@chapter Introduction
@cindex Introduction

@cindex Common C++
@cindex C++
@cindex IETF
@cindex Internet Ingeneering Task Force
@cindex Audio/Video Working Group
@cindex class framework
ccRTP is a C++ framework for developing applications based on the Real
Time Transport Protocol (@acronym{RTP} henceforth). @acronym{RTP}
provides end-to-end delivery services for data with real-time
characteristics and is being developed by the Audio/Video Working
Group of the Internet Engineering Task Force (@acronym{IETF}).

ccRTP aims to be an efficient and flexible framework valid for almost
any kind of application that uses @acronym{RTP}, ranging from high
loaded servers and gateways to personal phone applications. Default
constructs and values are provided however for the most common choices
in the use of @acronym{RTP}. ccRTP conforms to the latest
@acronym{RTP} specifications (@pxref{Standards Tracking}).

@cindex MD5
@cindex Common C++
@cindex system services
@cindex threading
@cindex synchronization
@cindex sockets
ccRTP is based on the @acronym{GNU} Common C++ framework, though most
of the library does not require it. Common C++ provides basic system
services such as threading, synchronization and sockets@footnote{As
well as other more specialized services, such as MD5 computation.},
which makes it possible to provide a complete solution for the use of
@acronym{RTP}. However, although ccRTP provides facilities and
abstractions useful for the @acronym{RTP} specific components of
applications that use @acronym{RTP}, such applications generally
require similar system services for other tasks. Besides supporting
ccRTP, Common C++ provides a portable and efficient framework for
these kind of services.

@acronym{RTP} has been defined as an application level protocol
framework rather than a typical Internet transport protocol such as
TCP and UDP. Thus, @acronym{RTP} is hardly ever implemented as a layer
separated from the application. Consequently, @acronym{RTP}
applications often must customize the adaptable @acronym{RTP} packet
layout and processing rules, timing constraints, session membership
rules as well as other @acronym{RTP} and @acronym{RTCP}
mechanisms. ccRTP aims to provide a framework for the @acronym{RTP}
framework, rather than being just an @acronym{RTP} packet manipulation
library.

@cindex signalization
@cindex RTSP
@cindex SIP
@cindex H.323
As a clarification of the scope of the ccRTP library and the
@acronym{RTP} protocol, we note that ccRTP exclusively deals with the
transport of data over the @acronym{RTP} protocol. Once parameters such
as destination IP address and transport port, payload type identifier
and timestamp frequency are known, ccRTP can be used to open an
@acronym{RTP} session and send and receive RTP and RTCP packets. A
multimedia application will have those parameters previously set or,
more usually, they can be fetched for example from SDP multimedia
session descriptions, which can be interchanged (and negotiated) between
servers and clients by means of some signaling protocol: @acronym{SIP},
@acronym{RTSP}, or even H.323. Signaling functions are not handled by
ccRTP.

This document is an introductory programmer's manual, for a more
exhaustive reference see the reference manual distributed with GNU
ccRTP. In @ref{ccRTP Overview}, the most important concepts and some
basic examples are introduced. A deeper and step by step description
as well as short examples are provided in @ref{Using ccRTP}.

Finally, if after reading this document and/or using ccRTP you think
it fails to provide some functionality that seems to be needed for
some application, we encourage you to contact the developers of ccRTP
and ask or propose them improvements and/or additions. You are also
encouraged to provide these improvements and to join the development
team. Bug reports, suggestions and criticisms are gladly accepted.


@c -----------------------------------------------------------------------
@node Distribution
@chapter Distribution
@cindex distribution

@cindex free software
@cindex GNU GPL
@cindex linking exception
@cindex GNU FDL
@cindex philosophy
@acronym{GNU} ccRTP is free software (see
@url{http://www.gnu.org/philosophy/philosophy.html}. It is licensed
under the terms of the @acronym{GNU} General Public License, @xref{GNU
General Public License}, plus a linking exception, @xref{GNU ccRTP
Linking Exception}. 

The linking exception is the same that is used for gcc libstdc++.  This
was done in the case of libstdc++ because the language of the LGPL is
neither clear nor correct if one uses C++ features such as templates and
method implimentation directly in headers, as the division between the
C++ library and another's application is no longer purely a linking one.
From the practical standpoint, the exact effect is the same as the LGPL,
but with language that matches these C++ features.  This is all
explained at
@url{http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/license.html}.

This manual is licensed under the terms of the @acronym{GNU} Free
Documentation License, @xref{GNU Free Documentation License}.

There are several ways to get @acronym{GNU} ccRTP, refer to
@url{http://www.gnu.org} and
@url{http://www.gnu.org/software/ccrtp/}. The development of ccRTP is
hosted at Savannah @url{http://sv.gnu.org/projects/ccrtp/}.


@c -----------------------------------------------------------------------
@node ccRTP Overview
@chapter ccRTP Overview
@cindex ccRTP Overview

At its highest level, ccRTP provides classes for the real-time
transport of data through @acronym{RTP} sessions, as well as the
control functions of @acronym{RTCP}.

@cindex packet queue
The main concept in the ccRTP implementation of @acronym{RTP} sessions
is the use of packet queues to handle transmission and reception of
@acronym{RTP} data packets/application data units. In ccRTP, a data
block is transmitted by putting it into the transmission (outgoing
packets) queue, and received by getting it from the reception
(incoming packets) queue.

Starting with 1.0 releases, ccRTP fully supports @acronym{RTP} and
@acronym{RTCP}. Here is a brief list of some features of ccRTP:

@itemize

@item Highly extensible to specialized stacks.

@item Supports unicast, multi-unicast and multicast. Handles multiple sources (including synchronization sources and contributing sources) and destinations. Also supports symmetric RTP.

@item Automatic RTCP functions handling, such as association of synchronization sources from the same participant or NTP-RTP timestamp mapping.

@item Genericity as for underlying network and transport protocols through templates.

@item It is threadsafe and supports almost any threading model.

@cindex header check
@cindex header validity
@item Generic and extensible @acronym{RTP} and @acronym{RTCP} header validity checks.

@item Handles source states and information as well as statistics recording.

@cindex SSRC collision
@cindex loop detection
@item Automatically handles SSRC collisions and performs loop detection.

@cindex reconsideration
@cindex timer reconsideration
@cindex reverse reconsideration
@item Implements timer reconsideration and reverse reconsideration.

@cindex Random numbers
@cindex /dev/urandom
@cindex MD5
@item Provides good random numbers, based on @file{/dev/urandom} or, alternatively, on MD5.

@end itemize

@cindex demo program
@cindex rtphello
@cindex rtplisten
@tindex RTPSession
@findex onGotSR
@findex getMRSenderInfo
@cindex SR
@cindex RTCP SR
There are several levels of interface (public interface, public or
protected inheritance, etc) in ccRTP. For instance, the
@code{rtphello} demo program distributed with ccRTP just uses the
public interface of the @code{RTPSession} class and does not redefine
the virtual method @code{onGotSR}, thus what this program knows about
SR reports is the information conveyed in the last sender report from
any source, which can be retrieved via the @code{getMRSenderInfo}
method of the @code{SyncSource} class. On the contrary, the
@code{rtplisten} demo program redefines @code{onGotSR} by means of
inheritance and could do specialized processing of these RTCP
packets. Generally, both data and control packets are not directly
accessible through the most external interface.

@tindex StaticPayloadType
@tindex StaticPayloadFormat
@tindex DynamicPayloadFormat
@tindex RTPSession
@tindex AppDataUnit
@tindex SyncSource
@tindex Participant
@tindex AppDataUnit
All these functions are performed through a few essential classes and
types. The most basic ones are the enumerated type
@code{StaticPayloadType}, and the classes @code{StaticPayloadFormat} and
@code{DynamicPayloadFormat}. The most important ones are the classes
@code{RTPSession}, @code{SyncSource}, @code{Participant} and
@code{AppDataUnit}, that represent @acronym{RTP} sessions,
synchronization sources, participants in an @acronym{RTP} application,
and application data units conveyed in @acronym{RTP} data packets,
respectively.

@cindex demo program
In the next sections, two basic examples are presented. These examples
are intended to provide a concrete idea of what the code of a ccRTP
based application looks like, they are not complete or compilable
programs. You can find some real examples under the demo directory in
the source distribution of ccRTP.

@menu
* Simple Transmitter::           Skeleton of a simple transmitter.
* Simple Receiver::              Skeleton of a simple receiver.
@end menu


@c -----------------------------------------------------------------------
@node Simple Transmitter
@section Simple Transmitter
@cindex Simple Transmitter

The following snippet illustrates the required steps to send an
application data unit over @acronym{RTP}.

@cartouche
@example
RTPSession s(InetHostAddress("127.0.0.1"),8000);  // @r{bind reception socket}

// @r{Initialization}
cout << "Local SSRC identifier: " << s.getLocalSSRC() << endl;
s.addDestination("www.example.com",9000); // @r{set one destination for packets}
s.setPayloadFormat(staticPayloadFormat(sptPCMU));
s.startRunning(); // @r{start running the packet queue scheduler}

// @r{Send data}
s.putData(0,buffer,bufferLen); // @r{buffer holds bufferLen payload octets}
@end example
@end cartouche


@c -----------------------------------------------------------------------
@node Simple Receiver
@section Simple Receiver
@cindex Simple Receiver

The required actions to receive an application data unit over RTP are
listed in the following code snippet.

@cartouche
@example
RTPSession s(InetHostAddress("127.0.0.1"),9000);  // @r{bind reception socket.}

// @r{Initialization.}
cout << "Local SSRC identifier: " << s.getLocalSSRC() << endl;
s.setPayloadFormat(staticPayloadFormat(sptPCMU));
s.startRunning(); // @r{start running the packet queue scheduler.}

// @r{Receive data.}
const AppDataUnit* adu;
adu = s.getData(0); // @r{get data with initial -0- timestamp.}
if ( adu != NULL )
   // @r{do something with adu.}
   // adu->getType() @r{provides the payload type.}
   // adu->getData() @r{provides a const uint8 pointer to a data buffer.}
   // adu->getSize() @r{provides the number of octets in the buffer.}
   // @r{see other methods in the class AppDataUnit, such as} getSource().
@end example
@end cartouche


@c -----------------------------------------------------------------------
@node Using ccRTP
@chapter Using ccRTP
@cindex Using ccRTP

@cindex packet queue
@cindex thread
When using ccRTP, both sending and receiving of data transported over
@acronym{RTP} sessions is done through reception and transmission
queues handled by the @acronym{RTP} stack. In the most common case, a
separate execution thread for each @acronym{RTP} session handles the
queues. This case is the threading model that we will generally assume
throughout this document. Note however that ccRTP supports other
threading models, particularly ccRTP supports the use of a single
execution thread to serve a set of @acronym{RTP} sessions. It is also
possible to not associate any separate thread with any @acronym{RTP}
session, manually calling the main data and control service methods
from whatever other thread.

@cindex reception queue
@cindex incoming queue
The basic idea for packet reception with ccRTP is that the application
does not directly read packets from sockets but gets them from a
reception queue. The stack is responsible for inserting received
packets in the reception queue and handling this queue. In general, a
packet reception and insertion in the reception queue does not occur
at the same time the application gets it from the queue.

@cindex transmission queue
@cindex outgoing queue
Conversely, the basic idea for packet transmission with ccRTP is that
packets are not directly written to sockets but inserted in a
transmission queue handled by the stack. In general, packet insertion
and transmission occur at different times, though it is not necessary.

In order to use ccRTP, you must include the main header
(@file{#include <ccrtp/rtp.h>}. Two additional headers are provided by
ccRTP:

@table @code

@item @file{#include <ccrtp/rtppool.h}
Classes for pools of RTP service threads.

@item @file{#include <ccrtp/rtpext.h>}
Classes for RTP extensions which are not mature yet.

@end table

You must also link in the library, currently @file{ccrtp1}.

As presented in the last examples, before starting to send or receive
data, RTP sessions must be created, the payload format to use must be
set and the stack must be signaled to start running. The following
sections describe the use of ccRTP during the different phases of RTP
sessions and RTP applications in general.

@menu
* RTP Sessions::                 Using ccRTP to establish @acronym{RTP} sessions.
* Payload Types and Formats::    Payload types and formats.
* Participants::                 Participants and sources of synchronization.
* RTP Packets Extensions::       Extensions to @acronym{RTP} data packets handling.
* RTCP Packets Extensions::      Extensions to @acronym{RTCP} packets handling.
* Handling Events::              Table of ccRTP plug-ins to react to events.
@end menu


@c -----------------------------------------------------------------------
@node RTP Sessions
@section RTP Sessions
@cindex RTP Sessions

This section discusses the use of @code{RTPSession} objects. Some
other classes and concepts are also used, these are just briefly
presented here; deeper explanations are provided in next sections.

@menu
* Initiating Sessions::          @acronym{RTP} sessions initialization with ccRTP.
* Sending Data::                 Sending @acronym{RTP} data packets.
* Receiving Data::               Receiving @acronym{RTP} data packets.
* Closing Sessions::             Extensions to @acronym{RTP} data packets handling.
* Types of Sessions::            Choosing a threading and socket model.
@end menu


@c -----------------------------------------------------------------------
@node Initiating Sessions
@subsection Initiating Sessions
@cindex Initiating Sessions

@tindex RTPSession
@cindex multicast
@cindex join
Initiating @acronym{RTP} sessions with ccRTP involves the construction
of an object of the class @code{RTPSession} and calling some optional
initialization methods. @code{RTPSession} constructors take two
mandatory arguments: local network address and local transport port
(where incoming packets are expected). There are two constructors, one
of them takes a host address as first parameter, while the other takes
a multicast address. In the latter case, the application will join to
a multicast group.

@findex RTPSession::startRunning
@findex RTPSession::enableStack
General purpose @acronym{RTP} stacks of ccRTP, such as
@code{RTPSession} objects, must be signaled to start execution. This
is done calling the @code{startRunning()} method. Note there is also a
@code{enableStack()} method, this only activates the stack but does not
start the execution of the stack thread.

After the steps above, the application can receive data, but will not
transmit to any destination. This and other session parameters can be
set as follows:

@itemize

@findex OutgoingDataQueue::addDestination
@item Add destinations: calling the method @code{addDestination}.

@findex RTPQueueBase::setPayloadFormat
@cindex static payload type
@cindex PCMU
@cindex default value
@item Set payload format. Method @code{setPayloadFormat}. By default, the static payload type 0 is assumed (PCMU format at 8Khz).

@cindex RTCP packets
@cindex RTCP compound packets
@cindex SDES item
@cindex CNAME
@cindex default value
@cindex PRIV
@findex RTPPApplication::setSDESItem
@findex RTPApplication::setPRIVPrefix
@findex defaultApplication
@item Set local SDES Items. For common applications, the CNAME item value is automatically guessed as user@@host. Other items have no default value and are not sent in RTCP packets unless a value is specified by the application. For those items that should be sent in @acronym{RTCP} packets along with the mandatory CNAME, its values can be set calling the @code{setSDESItem}  and @code{setPRIVPrefix} methods over the object returned by the @code{defaultApplication} global function.

@findex OutgoingDataQueue::setPadding
@cindex padding
@item Enable padding of data packets. Calling setPadding(uint8) on outgoing data queues enables transparent padding of data packets to a multiple of the padding maximum length specified. By default, padding is off (maximum length of padding is 0).

@item setting addresses: 


@findex QueueRTCPMaanger::setControlBandwidth
@cindex default value
@cindex default bandwidth
@cindex RTCP bandwidth
@item Set session bandwidth calling the @code{setSessionBandwidth} method of the session object. If not called, a default bandwidth of 64Kbps is assumed, and 5% of this bandwidth is used for RTCP. This percentage can be changed through the setControlBandwidth method.

@end itemize


@c -----------------------------------------------------------------------
@node Sending Data
@subsection Sending Data
@cindex Sending Data

@findex OutgoingDataQueue::putData
@cindex RTP timestamp offset
@cindex timestamp offset
Data packets are sent through the method @code{putData}, that takes as
first parameter the RTP timestamp for the data specified as second
parameter. ccRTP handles the random offset for the RTP timestamp
internally, so the timestamp value that corresponds to the session
creation time is 0.

@findex OutgoingDataQueue::setMark
@cindex default value
@cindex marker bit
By default, the marker bit of the sent packets is not set. Its value
for the next packet (the one that will convey the data provided in the
next call to @code{putData}) can be set through the @code{setMark}
method, which takes a boolean as argument.

@findex OutgoingDataQueueBase::setMaxSendSegmentSize
@findex OutgoingDataQueueBase::getDefaultMaxSendSegmentSize
@cindex default value
@cindex segment size
ccRTP also supports fragmenting data blocks into several RTP
packets. The @code{setMaxSendSegmentSize} method can be used to
request that no @acronym{RTP} packet be transmitted with a payload
length greater than the value specified through
@code{setMaxSendSegmentSize}. The default value of this parameter can
be retrieved via @code{getDefaultMaxSendSegmentSize}, which currently
should return 65536. When data blocks greater than the maximum segment
size are provided through @code{putData}, two or more packet will be
inserted in the outgoing packet queue. All these packets but the last
one will have length equal to the maximum segment size, whereas the
last one's size will be lower or equal to the maximum segment size.


@c -----------------------------------------------------------------------
@node Receiving Data
@subsection Receiving Data
@cindex Receiving Data

@findex IncomingDataQueue::getData
Received data is retrieved from the incoming packet queue through the
@code{getData} method, which, given a timestamp and an optional source
of synchronization. This method returns a pointer to an
@code{AppDataUnit} object as opposed to a pointer to a memory
block. In ccRTP application data units are represented through objects
of the @code{AppDataUnit} class, that provides access to the
synchronization source of the data and other related properties.

@cindex duplicate packets
@cindex reordering
The incoming packet queue takes care of functions such as packet
reordering or filtering out duplicate packets.

@findex IncomingDataQueue::isWaiting
You can guess if there are packets in the reception queue calling
@code{isWaiting}. Both @code{getData} and @code{isWaiting} take an
optional parameter which selects a particular synchronization source
of data units. If not specified, data units are returned regardless of
its source.


@c -----------------------------------------------------------------------
@node Closing Sessions
@subsection Closing Sessions
@cindex Closing Sessions

RTP sessions can be closed deleting or destroying @code{RTPSession}
objects. The stack sends a BYE packet to every destination when the
destructor of sessions is called. It is also possible to explicitly send
a BYE packet through the dispatchBYE method, which takes the leaving
reason string as argument. Note that dispatchBYE will honor a number of
rules for sending BYE packets specified in the RTP standard: a BYE
packet is not sent if no RTP/RTCP packet was sent, and BYE floods
avoiding mechanisms are employed.

Note that when a BYE RTCP packet is received from a remote
participant, the virtual @code{onGotGoodbye} will be called.

@c -----------------------------------------------------------------------
@node Types of Sessions
@subsection Types of Sessions
@cindex Types of Sessions

@emph{TODO:} explain how to instantiate templates depending on the
threading model and the number of sockets to use. Also symmetric
channels/sessions. Describe what's a channel and a session.


@c -----------------------------------------------------------------------
@node Payload Types and Formats
@section Payload Types and Formats
@cindex Payload Types
@cindex Payload Formats

@tindex PayloadType
@tindex StaticPayloadType
In the context of @acronym{RTP}, an @acronym{RTP} payload type is a
7-bit numeric identifier that identifies a payload format.  For
payload types, GNU ccRTP defines the integer type
@code{PayloadType}. ccRTP also defines The enumerated type
@code{StaticPayloadType}, as the enumeration of the @acronym{RTP}
Payload Types statically assigned for standard audio and video
formats.

These codes were initially specified in @cite{RFC 1890, ``RTP Profile
for Audio and Video Conferences with Minimal Control'' (AVP profile)},
superseded by @cite{RFC 3550}, and are registered as MIME types in
@cite{RFC 3555}. Codes below 96 may be assigned statically, although
the default bindings for many of them are already reserverd. Codes in
the range 96-127 are assigned dinamically by means outside of the
@acronym{RTP} profile or protocol specification.

@cindex IANA
@cindex RTP parameters
See the ``RTP Parameters'' list at @acronym{IANA}
@url{http://www.iana.org/assignments/rtp-parameters}. Note however
that registering static payload types is now considered a deprecated
practice in favor of dynamic payload type negotiation.

@tindex PayloadFormat

@cindex MIME
@cindex SDP
@cindex Session Description Protocol
@cindex H.245
@cindex clock rate
@cindex timestamp clock rate
@cindex RTP clock rate
The properties of a payload format that, as an @acronym{RTP} stack,
ccRTP takes into account are the payload type (numeric identifier) and
the @acronym{RTP} clock rate. Other properties, such as @acronym{MIME}
type, number of audio channels, ``ptime'' and ``maxptime'' are not
considered. These are only of interest for higher level protocols,
such as @acronym{SDP} and H.245.

GNU ccRTP defines a hierarchy of payload format classes. Its root is
@code{PayloadFormat}, which is a base class for
@code{StaticPayloadFormat} and @code{DynamicPayloadFormat}.

@tindex StaticPayloadFormat
@tindex StaticPayloadType
Static payload format objects are built from a static payload
code. These are defined in the enumerated type
@code{StaticPayloadType}. The following example constructs a
@code{StaticPayloadFormat} object corresponding to the payload type 0
(statically bounded to PCMA in @cite{RFC 3551}):

@findex StaticPayloadFormat::StaticPayloadFormat
@example
StaticPayloadType pt = sptPCMU;
StaticPayloadFormat* spf = new StaticPayloadFormat(pt);
@end example

Of course, we could have said:

@example
StaticPayloadFormat* spf = new StaticPayloadFormat(sptPCMA);
@end example

StaticPayloadFormat objects build like the ones above hold the
necessary parameters so that the @acronym{RTP} stack can handle
incoming and outgoing packets.

@tindex DynamicPayloadFormat
@findex DynamicPayloadFormat::DynamicPayloadFormat
Regarding dynamic payload formats, a call to
@code{DynamicPayloadFormat::DynamicPayloadFormat(100,90000)} like the
following:

@example
DynamicPayloadFormat* dpf = new DynamicPayloadFormat(100,90000);
@end example

Will construct a dynamic payload format object that ties together the
'100' payload type numeric identifier and an @acronym{RTP} clock rate
of 90 Khz. Note that the numeric identifier does not have to be in the
dynamic range. The static payload types are default bindings and MAY
be overriden, thus, DynamicPayloadFormat(0,90000) is a valid construct
provided 0 has been established as the payload type through a previous
negotiation process@footnote{Despite the fact that RFC 3551 defines a
static binding of the 0 code to mu-law PCM at 8Khz.}.

@cindex Session control
Whether and how the payload has been negotiated is outside of the
scope of @acronym{RTP} and ccRTP, so applications must choose between
@code{StaticPayloadFormat} and @code{DynamicPayloadFormat} accordingly
to their multimedia session control mechanisms.


@c -----------------------------------------------------------------------
@node Participants
@section Participants And Sources of Synchronization
@cindex Source of Synchronization
@cindex Participant

@tindex RTPApplication
@tindex Participant
@tindex SyncSource
@tindex RTPSession
In GNU ccRTP, there are classes that represent @acronym{RTP}
applications (@code{RTPApplication}), participants
(@code{Participant}), synchronizacion sources (@code{SyncSource}) and
RTP sessions (@code{RTPSession}). The relations among these entities
are shown in the following diagram:

@image{srcmodel,8cm,,{Relations between applications, participants,
sources and sessions}}

@cindex CNAME
An @acronym{RTP} application establishes a space of CNAME identifiers,
whereas an @acronym{RTP} session establishes a space of SSRC
identifiers.

For each source of synchronization seen in an @acronym{RTP} session, a
@code{SyncSource} object identified by a SSRC numeric identifier is
created. Thus, at the beginning of an @acronym{RTP} session there are
no @code{SyncSource} objects related. Note that, if the local source
sends packets to itself during an @acronym{RTP} session, a
@code{SyncSource} object will be created for it.

The list of sources of synchronization identified in an RTP session
can be retrived through STL-like iterators of type
@code{RTPSession::SyncSourcesIterator}, as shown in the following
example.

@cartouche
@example
// rx is an RTPSession object
RTPSession::SyncSourcesIterator it;
for (it = rx.begin() ; it != rx.end(); it++) @{
   const SyncSource &s = *it;
   cout << s.getID();
   if ( s.isSender() )
      cout << "is an active sender";
   cout << endl;
@}
@end example
@end cartouche

@findex RTPSession::SyncSourcesIterator
@cindex const iterator
@cindex iterator
Note @code{RTPSession::SyncSourcesIterator} is a const iterator.

@findex SyncSource::getParticipant()
@cindex participant
When using RTCP, it is possible to associate several synchronization
source objects to a participant in the multimedia session, which is
represented through the association between @code{Participant} and
@code{SyncSource} objects. The participant object linked to a source
of synchronization can be retrieved through the
@code{SyncSource::getParticipant()} method, as the following examples
shows:

@cartouche
@example
   // s is a source of synchronization object (SyncSource)
   Participant *p = s.getParticipant();
   cerr << p->getSDESItem(SDESItemTypeCNAME) << endl;
@end example
@end cartouche

When RTCP is not being used or the CNAME identifier corresponding to a
synchronization source has not been received yet, the participant
associated with a synchronization source is not known. In these cases,
the method @code{SyncSource::getParticipant()} will return a NULL
pointer. On the contrary, a participant is always related to a
synchronization source at least. It can also be related to more than
one synchronization source (for instance, when a participant in a
videoconference sends two video streams from two different
chameras). Note that, if the local source sends data and control
packets to itself, a @code{Participant} object will be created for it.

Thus, the @code{SyncSource::getParticipant} provides a facility for
inter-media synchronization.

@findex defaultApplication
@findex RTPApplication
@cindex default value
@cindex CNAME
The association of @acronym{RTP} sessions and participants with
@code{RTPApplication} objects makes it possible to implement several
``RTP applications'' in the same application or process, each one
having a separate CNAME space. By default, all @acronym{RTP} sessions
are associated to an @acronym{RTP} application provided by the global
method @code{defaultApplication()}. The local CNAME for the default
application is guessed from the user and machine name, as specified in
@cite{RFC 3550}. 

However, other applications may be created through the constructor
@code{RTPApplication::RTPApplication(const std::string& cname)}. @acronym{RTP} sessions are associated with applications other
than the default via an optional constructor parameter.

@findex RTPApplication::ParticipantsIterator
@cindex const iterator
@cindex iterator
Similarly to the list of synchronization sources, the list of
participants in a session can be retrieved using iterators of type
@code{RTPApplication::ParticipantsIterator}, see the following
example, which shows the list of CNAMEs of the participants in the
default application:

@cartouche
@example
   RTPApplication &app = defaultApplication();
   RTPApplication::ParticipantsIterator ai;
   for ( ai = app.begin(); ai != app.end(); ai++ ) @{
      const Participant &p = *ai;
      cerr << p.getSDESItem(SDESItemTypeCNAME) << endl;
   @}
@end example
@end cartouche

@findex RTPApplication::ParticipantsIterator
@cindex const iterator
@cindex iterator
Note @code{RTPApplication::ParticipantsIterator} is a const iterator.

@emph{TODO: SyncSource states}.


@c -----------------------------------------------------------------------
@node RTP Packets Extensions
@section RTP Packets Extensions
@cindex RTP Packets Extensions

@tindex RTPPacket
@tindex IncomingRTPPkt
@tindex OutgoingRTPPkt
@emph{TODO.} Describe @code{RTPPacket}, @code{IncomingRTPPkt} and
@code{OutgoingRTPPkt} classes. @xref{RTP Packets Arrival}, for a
discussion of event handling virtuals that allow for specialized
processing of data packets.


@c -----------------------------------------------------------------------
@node RTCP Packets Extensions
@section RTCP Packets Extensions
@cindex RTCP Packets Extensions

@xref{RTCP Packets Arrival}, for a discussion of event handling
virtuals that allow for specialized processing of control packets.


@c -----------------------------------------------------------------------
@node Handling Events
@comment  node-name,  next,  previous,  up
@section Handling Events
@cindex Handling Events

There are a number of events that may require special response from
the application. ccRTP defines plug-ins to handle these events.

@menu
* RTP Packets Arrival::           Filtering and extending @acronym{RTP} packets parsing.
* RTCP Packets Arrival::          Filtering and extending @acronym{RTCP} packets parsing.
* Synchronization Source States:: Handling state transitions.
* SSRC Collisions::               Handling SSRC identifier collisions.
* RTP Packets Expiration::        Outgoing and incoming @acronym{RTP} packets expiration.
@end menu


@c -----------------------------------------------------------------------
@node RTP Packets Arrival
@comment  node-name,  next,  previous,  up
@subsection RTP Packets Arrival 
@cindex RTP Packet Arrival

@findex IncomingDataQueue::onRTPPacketRecv
@code{onRTPPacketRecv} is the virtual method that may be redefined in
any subclass of @code{IncomingDataQueue}, particularly in subclasses
of @code{RTPSession}. It takes an @code{IncomingRTPPkt} object as
argument and returns a boolean indicating whether the packet should be
inserted in the reception queue.


@c -----------------------------------------------------------------------
@node RTP Packets Expiration
@comment  node-name,  next,  previous,  up
@subsection RTP Packets Expiration
@cindex RTP Packets Expiration

@findex OutgoingDataQueue::onExpireSend
@findex IncomingDataQueue::onExpireRecv
@code{onExpireSend} and @code{onExpireRecv}

@findex QueueRTCPManager::end2EndDelayed
@code{end2EndDelayed}


@c -----------------------------------------------------------------------
@node RTCP Packets Arrival
@comment  node-name,  next,  previous,  up
@subsection RTCP Packets Arrival 
@cindex RTCP Packet Arrival
Incoming RTCP packets are automatically handled by ccRTP. However,
this does not mean you can't track the reception of RTCP packets.

@itemize

@cindex SR
@cindex RTCP SR
@findex QueueRTCPManager::onGotSR
@item @code{onGotSR}

@cindex RR
@cindex RTCP RR
@findex QueueRTCPManager::onGotRR
@item @code{onGotRR}

@cindex SDES
@cindex RTCP SDES
@findex QueueRTCPManager::onGotSDESChunk
@item @code{onGotSDESChunk}

@cindex APP
@cindex RTCP APP
@findex QueueRTCPManager::onGotAPP
@item @code{onGotAPP}

@cindex SRE Extension
@findex QueueRTCPManager::onGotRRSRExtension
@item @code{onGotRRSRExtension}

@end itemize

Note that this events correspond to RTCP packets, not RTCP compound
packets, and probably the reception of a compound packet will trigger
more than one of these events.


@c -----------------------------------------------------------------------
@node Synchronization Source States
@comment  node-name,  next,  previous,  up
@subsection Synchronization Source States
@cindex Synchronization Source States

@findex IncomingDataQueue::onNewSyncSource
@code{onNewSyncSource}.


@c -----------------------------------------------------------------------
@node SSRC Collisions
@comment  node-name,  next,  previous,  up
@subsection SSRC Collisions 
@cindex SSRC Collision

@cindex collision
@cindex SSRC collision
@findex QueueRTCPManager::onSSRCCollision
@code{onSSRCCollision}.

@c -----------------------------------------------------------------------
@node Specialized Payload Formats
@chapter Specialized Payload Formats
@cindex Specialized Payload Formats

@emph{TODO:} finish 2833bis and CN.

@emph{TODO:} comment H.261 specific RTCP packets: FIR and NACK.


@c -----------------------------------------------------------------------
@node Standards Tracking
@chapter Standards Tracking
@cindex Standards tracking

@cindex IETF
@cindex IETF standards

@emph{TODO: explain what is done/being done/planned}.

@itemize

@item @cite{RTP: A Transport Protocol for Real-Time Applications (RFC 3550, which supersedes RFC 1889)}.

@item @cite{RTP Profile for Audio and Video Conferences with Minimal Control (RFC 3551, which supersedes RFC 1890)}.

@item @cite{MIME Type Registration of RTP Payload Formats (RFC 3555)}.

@item @cite{IANA RTP Parameters}.

@item @cite{RTP Payload Format for H.261 Video Streams (RFC 2032)}. Defines H.261 specific FIR and NACK RTCP packets.


@end itemize

@itemize

Not yet implemented:

@cindex profile
@cindex SRTP
@cindex Secure RTP
@item @cite{The Secure Real-time Transport Protocol}. SRTP provile.

@cindex AVPF
@cindex RTCP-based feedback
@item @cite{Extended RTP Profile for RTCP-based Feedback (RTP/AVPF)}.

@cindex AVPF
@cindex RTCP-based feedback
@item @cite{Extended RTP Profile for RTCP-based Feedback (RTP/AVPF)}.

@cindex SAVPF
@item @cite{Extended Secure RTP Profile for RTCP-based Feedback (RTP/SAVPF)}.

@end itemize


@c -----------------------------------------------------------------------
@node Upgrading
@chapter Upgrading
@cindex Upgrading

This chapter outlines the main steps required to upgrade applications
written for old releases of ccRTP (0.6.x, 0.7.x and 0.9.x series) to
the 1.0 series. It is written mostly as a recipe of replacements for
old constructs.

Replace @code{#include <cc++/rtp.h>} with @code{#include
<ccrtp/rtp.h>}@footnote{Note that unfortunately ccRTP 1.0pre0 used
@code{#include <cc++/rtp/rtp.h}, which is now deprecated.}.

Changes that have to do more with Common C++ 2 than with ccRTP:

@table @code

@item exit(int)
@findex exit
Replace with exit()

@item Thread::Terminate()
@findex Thread::terminate
Replace with Thread::terminate()

@item ccxx_sleep(timeout_t)
@findex ccxx_sleep
@findex Thread::sleep
Replace with sleep(timeout_t).

@item Thread::Run()
Replace with Thread::run()

@end table

Changes required by ccRTP itself:

@table @code
@item RTPSource
@tindex RTPSource
@tindex SyncSource
Now @code{SyncSource}, and is a somewhat different concept. For
instance, calls to RTPSource::getID() must be replaced with calls to
SyncSource::getID(), which in most cases will not imply any change to
this part of the code.

@item RTPQueue::getLocalInfo()->getID()
@findex RTPQueue::getLocalInfo
@findex RTPQueue::getLocalSSRC
Replace with @code{RTPQueueBase::getLocalSSRC()}

@item RTPQueue::getCNAME()
@findex RTPQueue::getCNAME
@findex defaultApplication
@findex RTPApplication::getSDESItem
Replace with @code{defaultApplication().getSDESItem(SDESItemTypeSDES)}.

@item RTPQueue::getPacket()
@findex RTPQueue::getPacket
@findex IncomingDataQueue::getData
@code{getPacket()} has been removed and now there is only a
@code{getData()} method in the @acronym{RTP} queues.

@item RTPQueue::setTimeout()
@findex RTPQueue::setTimeout
@findex OutgoingDataQueue::setSchedulingTimeout
Replace calls to RTPQueue::setTimeout(microtimeout_t) with calls to
OutgoingDataQueue(microtimeout_t), whose purpose and working is
exactly the same.

@item RTPQueue::putPacket()
@findex RTPQueue::putPacket
@findex OutgoingDataQueue::putData
@cindex payload type
@findex RTPQueueBase::setPayloadFormat
@code{putPacket()} has been removed and now there is only a
@code{putData()} method in the @acronym{RTP} queues. Note also that now the
payload type is not specified for each outgoing @acronym{RTP} data block,
instead use RTPQueueBase::setPayloadFormat each time the payload type
changes.

@item PayloadType
@tindex DynamicPayloadType
@tindex StaticPayloadType
The definition of payload types has deeply changed in order to allow
all standard uses of dynamic payload negotiation. Refer to
@ref{Payload Types and Formats}, for an explanation of the new payload
types and formats related classes.

For example, @code{RTP_PAYLOAD_PCMU} must be replaced with something
like @code{StaticPayloadFormat pcmu(sptPCMU)}, where @code{pcmu} is
the name of a static payload object that binds an statically assigned
@code{PayloadType} @footnote{The static payload type 0 corresponds to
the audio format PCMU, see @cite{RFC 3550}.}. to its corresponding
@acronym{RTP} clock rate@footnote{8 khz.}.

@cindex destination
@cindex redundancy
@item RTPSocket::Connect
The call connect has been removed. Now, in order to send packets to a
destination @code{OutgoingDataQueue::addDestination} must be used. It
allows for setting more than one destination. Any destination can
actually be added more than one time with addDestination, which can be
used a simple trick to perform redundant transmission: each packet -both
RTP and RTCP- will be transmitted to the destination as many times as it
has been added to the list of destinations through calling
addDestination.

@item RTPQueue::getCurrentRate
@findex RTPQueue::getCurrentRate
@findex RTPQueueBase::getCurrentRTPClockRate
Replace with @code{RTPQueueBase::getCurrentRTPClockRate()}.

@item RTPSocket::Start
@findex RTPSocket::Start
@findex RTPSession::startRunning
Replace with @code{RTPSession::startRunning}.

@item RTPQueue::gotHello
@findex RTPQueue::gotHello
@findex QueueRTCPManager::onNewSyncSource
Replace with @code{QueueRTCPManager::onNewSyncSource}.

@item RTPQueue::gotGoodbye
@findex RTPQueue::gotGoodbye
@findex QueueRTCPManager::onGotGoodbye
Replace with @code{QueueRTCPManager::onGotGoodbye}.

@end table


@c -----------------------------------------------------------------------
@node ccRTP Internals
@comment  node-name,  next,  previous,  up
@chapter ccRTP Internals
@cindex @acronym{ccRTP} Internals


@menu
* Internals Overview::          ccRTP internals overview.
* Collisions and Loops::        Collision Resolution and Loop Detection.
* Algorithms in the Standard::  Implementation of algorithms in the standard.
@end menu


@c -----------------------------------------------------------------------
@node Internals Overview
@section Internals Overview
@cindex Internals Overview

@emph{TODO: Explain where on how timer reconsideration/reverse recons. is
performed}.

Performance:

@itemize 
@item Zero copy stack.
@item RW/R multithreading.
@item Fast specialized linked list and hash mechanisms.
@end itemize

@c -----------------------------------------------------------------------
@node Collisions and Loops
@section Collisions and Loops
@cindex Collisions and Loops

ccRTP performs loop detection (following 8.2 in @cite{RFC 3550},
though the algorithm in ccRTP differs is structure because of two
reasons:

@itemize

@item ccRTP holds a table of source for which some packet has been received, instead of a table with all the sources in the session (i.e. the local source is not included in the table unless it sends packets to itself).

@item RTP and RTCP packets are handled separately whereas the algorithm in 8.2 treats both.

Note that the first two conditions in 8.2 (creating new source entries
and setting source transport address) are handled in the SSRC
bookkeeping methods rather than mixing them with the real collisions
and loop handling.

Unlike the algorithm given in 8.2, the ccRTP algorithm detects the
very rare case when two sources on the same host use the same SSRC
identifier and the first @acronym{RTP} packet for that identifier is
received from one source and the first RTCP is received from the
other.

@end itemize

@c -----------------------------------------------------------------------
@node Algorithms in the Standard
@section Algorithms in the Standard
@cindex Algoritms in the Standard

The following sections summarizes how the algorithms specified in
appendixes from @cite{RFC 3550} are implemented in ccRTP. A
``mapping'' between routines in the RFC and methods/routines in ccRTP
is provided.

@menu
* A.1::                @acronym{RTP} Data Header Validity Checks.
* A.2::                RTCP Header Validity Checks.
* A.3::                Determining the Number of @acronym{RTP} Packets Expected and Lost.
* A.4::                Generating SDES RTCP Packets.
* A.5::                Parsing RTCP SDES Packets.
* A.6::                Generating a Random 32-bit Identifier.
* A.7::                Computing the RTCP Transmission Interval.
* A.8::                Estimating the Interarrival Jitter.
@end menu


@c -----------------------------------------------------------------------
@node A.1
@subsection A.1
@cindex A.1

@findex IncomingDataQueue::checkSSRCInIncomingRTPPkt
@findex QueueRTCPManager::checkSSRCInRTCPPkt
ccRTP performs @acronym{RTP} data header validity check in two stages:
the first stage, performed at the constructor of @code{IncomingRTPPkt}
(which is extensible with virtual methods) validates the header fields
independent of the source. The second stage, performed at
@code{IncomingDataQueue::checkSSRCInIncomingRTPPkt} and
@code{QueueRTCPManager::checkSSRCInRTCPPkt}, validates those fields
specific to the source of the packet (number sequence, etc).

Additionally, the following table specifies which methods of ccRTP
implement the functions init_seq and update_seq from A.1.

@table @code

@item void init_seq(source*, u_int16) 
void MembershipBookkeeping::SyncSourceLink::initSequence(uint16)

@item int update_seq(source*, u_int16)
bool RTPQueue::recordReception(SyncSourceLink&, const IncomingRTPPkt&)

@end table

@c -----------------------------------------------------------------------
@node A.2
@subsection A.2
@cindex A.2

@cindex header check
@cindex header validity
@cindex RTCP header
@findex RTCPCompoundHandler::checkCompountRTCPHeader
The code in A.2 corresponds to
@code{RTCPCompoundHandler::checkCompountRTCPHeader}.


@c -----------------------------------------------------------------------
@node A.3
@subsection A.3
@cindex A.3

@findex MembershipBookkeeping::SyncSourceLink::computeStats
Code in A.3 corresponds to @code{MembershipBookeeping::computeStats}.


@c -----------------------------------------------------------------------
@node A.4
@subsection A.4
@cindex A.4

@findex QueueRTCPManager::packSDES
Code in A.4 is implemented as part of the method
@code{QueueRTCPManager::packSDES}.


@c -----------------------------------------------------------------------
@node A.5
@subsection A.5
@cindex A.5

@findex QueueRTCPManager::onGotSDES
Code in A.5 is implemented in the method
@code{QueueRTCPManager::onGotSDES}, which calls the virtual method
@code{QueueRTCPManager::onGotSDESChunk} to process each SDES chunk.


@c -----------------------------------------------------------------------
@node A.6
@subsection A.6
@cindex A.6

@cindex Random numbers
@cindex /dev/urandom
@cindex MD5
On POSIX systems, ccRTP uses @file{/dev/urandom} when available. If
there is no such device, it defaults to the MD5 based algorithm given
in appendix A.6.

Code in A.6 corresponds to @code{uint32 MD5BasedRandom32()}, which is
called by @code{uint32 random32()} when no random device is available.


@c -----------------------------------------------------------------------
@node A.7
@subsection A.7
@cindex A.7

Mapping:

@table @code

@item double rtcp_interval(int, int, double, int, double, int) 
virtual timeval QueueRTCPManager::computeRTCPInterval(), and in timeval
(seconds + microseconds) units, instead of seconds.

@item OnExpire(event, int, int, double, int, double, int time_tp, time_tp, int)
QueueRTCPManager::runControlService(microtimeout_t) (this method also
implements part of SendRTCPReport(e))

@item OnReceive(packet, event, int, int, int, double, double, double, double)
void QueueRTCPManager::takeInControlPacket() and
QueueRTCPManager::runControlService(microtimeout_t)

@item Schedule(time, event) and Reschedule(time, event) 
No equivalent.

@findex QueueRTCPManager::dispatchControlPacket
@item SendRTCPReport(event) 
@code{dispatchControlPacket}.

@findex QueueRTCPManager::dispatchBYE
@item SendBYEPacket(event)
@code{QueueRTCPManager::dispatchBYE(const std::string& reason)}.

@item TypeOfEvent(event)
No equivalent.

@item PacketType(p) 
No equivalent.

@findex IncomingDataQueue::takeInDataPacket
@item ReceivedPacketSize() 
@code{size_t IncomingDataQueue::takeInDataPacket()}.

@findex OutgoingDataQueue::dispatchDataPacket
@findex QueueRTCPManager::dispatchControlPacket
@item SentPacketSize() 
@code{size_t OutgoingDataQueue::dispatchDataPacket()} -data, and
@code{size_t QueueRTCPManager::dispatchControlPacket()} -control.

@item NewMember(p)

@item NewSender(p)

@item AddMember() and RemoveMember()

@item AddSender() and RemoveSender()

@end table


@c -----------------------------------------------------------------------
@node A.8
@subsection A.8
@cindex A.8

@cindex jitter
@cindex interarrival jitter
@findex IncomingDataQueue::recordReception
Interarrival jitter is estimated as specified in A.8, in
@code{recordReception}. Jitter is kept as a float.


@c -----------------------------------------------------------------------
@node Related Work
@comment  node-name,  next,  previous,  up
@chapter Related Work
@cindex Related work

@emph{TODO}.  Other free @acronym{RTP} stacks and tools:

@itemize

@item jrtplib

@item oRTP

@item LIVE.COM Streaming Media

@item UCL Common Code Library. Note this library is distributed under a BSD license @emph{with} the obnoxious clausule.
@end itemize


@c -----------------------------------------------------------------------
@node Future Work
@comment  node-name,  next,  previous,  up
@chapter Future Work
@cindex Future, Future Work

@emph{TODO}.


@c %** end of body

@c -----------------------------------------------------------------------
@node Licenses
@appendix Licenses

@menu
* GNU Free Documentation License::              License for this document.
* GNU General Public License::                  ccRTP Base License.
* GNU ccRTP Linking Exception::                 ccRTP linking exception.
@end menu

@include gpl.texi

@include fdl.texi


@c -----------------------------------------------------------------------
@node GNU ccRTP Linking Exception
@appendixsec GNU ccRTP Linking Exception
@cindex GNU ccRTP Linking Exception

As a special exception to the GNU General Public License, permission
is granted for additional uses of the text contained in its release of
ccRTP.

The exception is that, if you link the ccRTP library with other files
to produce an executable, this does not by itself cause the resulting
executable to be covered by the GNU General Public License.  Your use
of that executable is in no way restricted on account of linking the
ccRTP library code into it.

This exception does not however invalidate any other reasons why the
executable file might be covered by the GNU General Public License.

This exception applies only to the code released under the name ccRTP.
If you copy code from other releases into a copy of ccRTP, as the
General Public License permits, the exception does not apply to the
code that you add in this way.  To avoid misleading anyone as to the
status of such modified files, you must delete this exception notice
from them.

If you write modifications of your own for ccRTP, it is your choice
whether to permit this exception to apply to your modifications.  If
you do not wish that, delete this exception notice.


 

@c -----------------------------------------------------------------------

@c %** start of end
@node Class and Data Type Index
@unnumbered Class and Data Type Index

@printindex tp

@node Method and Function Index
@unnumbered Method and Function Index

@printindex fn

@node Concept Index
@unnumbered Concept Index

@printindex cp

@bye
@c %** end of end