This is ccrtp.info, produced by makeinfo version 4.8 from ccrtp.texi. INFO-DIR-SECTION Development START-INFO-DIR-ENTRY * GNU ccRTP: (ccrtp). GNU ccRTP Real-Time Transport Protocol Framework. END-INFO-DIR-ENTRY GNU ccRTP is a C++ class framework for the development of Real Time Transport Protocol (RTP) based applications. It is based on GNU Common C++. Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006 Federico Montesino Pouzols . Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".  File: ccrtp.info, Node: Top, Next: Introduction, Up: (dir) GNU ccRTP Manual **************** This manual describes GNU ccRTP, a C++ class framework for the development of Real Time Transport Protocol (RTP) based applications. This is the edition 1.3 of this manual and documents GNU ccRTP version 1.3. * Menu: * Introduction:: What RTP and ccRTP are. * Distribution:: How to get 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:: IETF Standards conformance. * Upgrading:: Upgrading applications based on old releases. * ccRTP Internals:: How GNU ccRTP is done. * Related Work:: Other RTP related libraries and tools. * Future Work:: Future of 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.  File: ccrtp.info, Node: Introduction, Next: Distribution, Prev: Top, Up: Top 1 Introduction ************** ccRTP is a C++ framework for developing applications based on the Real Time Transport Protocol (RTP henceforth). 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 (IETF). ccRTP aims to be an efficient and flexible framework valid for almost any kind of application that uses 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 RTP. ccRTP conforms to the latest RTP specifications (*note Standards Tracking::). ccRTP is based on the 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(1), which makes it possible to provide a complete solution for the use of RTP. However, although ccRTP provides facilities and abstractions useful for the RTP specific components of applications that use 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. RTP has been defined as an application level protocol framework rather than a typical Internet transport protocol such as TCP and UDP. Thus, RTP is hardly ever implemented as a layer separated from the application. Consequently, RTP applications often must customize the adaptable RTP packet layout and processing rules, timing constraints, session membership rules as well as other RTP and RTCP mechanisms. ccRTP aims to provide a framework for the RTP framework, rather than being just an RTP packet manipulation library. As a clarification of the scope of the ccRTP library and the RTP protocol, we note that ccRTP exclusively deals with the transport of data over the 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 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: SIP, 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 *Note 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 *Note 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. ---------- Footnotes ---------- (1) As well as other more specialized services, such as MD5 computation.  File: ccrtp.info, Node: Distribution, Next: ccRTP Overview, Prev: Introduction, Up: Top 2 Distribution ************** GNU ccRTP is free software (see `http://www.gnu.org/philosophy/philosophy.html'. It is licensed under the terms of the GNU General Public License, *Note GNU General Public License::, plus a linking exception, *Note 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 `http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/license.html'. This manual is licensed under the terms of the GNU Free Documentation License, *Note GNU Free Documentation License::. There are several ways to get GNU ccRTP, refer to `http://www.gnu.org' and `http://www.gnu.org/software/ccrtp/'. The development of ccRTP is hosted at Savannah `http://sv.gnu.org/projects/ccrtp/'.  File: ccrtp.info, Node: ccRTP Overview, Next: Using ccRTP, Prev: Distribution, Up: Top 3 ccRTP Overview **************** At its highest level, ccRTP provides classes for the real-time transport of data through RTP sessions, as well as the control functions of RTCP. The main concept in the ccRTP implementation of RTP sessions is the use of packet queues to handle transmission and reception of 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 RTP and RTCP. Here is a brief list of some features of ccRTP: * Highly extensible to specialized stacks. * Supports unicast, multi-unicast and multicast. Handles multiple sources (including synchronization sources and contributing sources) and destinations. Also supports symmetric RTP. * Automatic RTCP functions handling, such as association of synchronization sources from the same participant or NTP-RTP timestamp mapping. * Genericity as for underlying network and transport protocols through templates. * It is threadsafe and supports almost any threading model. * Generic and extensible RTP and RTCP header validity checks. * Handles source states and information as well as statistics recording. * Automatically handles SSRC collisions and performs loop detection. * Implements timer reconsideration and reverse reconsideration. * Provides good random numbers, based on `/dev/urandom' or, alternatively, on MD5. There are several levels of interface (public interface, public or protected inheritance, etc) in ccRTP. For instance, the `rtphello' demo program distributed with ccRTP just uses the public interface of the `RTPSession' class and does not redefine the virtual method `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 `getMRSenderInfo' method of the `SyncSource' class. On the contrary, the `rtplisten' demo program redefines `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. All these functions are performed through a few essential classes and types. The most basic ones are the enumerated type `StaticPayloadType', and the classes `StaticPayloadFormat' and `DynamicPayloadFormat'. The most important ones are the classes `RTPSession', `SyncSource', `Participant' and `AppDataUnit', that represent RTP sessions, synchronization sources, participants in an RTP application, and application data units conveyed in RTP data packets, respectively. 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.  File: ccrtp.info, Node: Simple Transmitter, Next: Simple Receiver, Up: ccRTP Overview 3.1 Simple Transmitter ====================== The following snippet illustrates the required steps to send an application data unit over RTP. RTPSession s(InetHostAddress("127.0.0.1"),8000); // bind reception socket // Initialization cout << "Local SSRC identifier: " << s.getLocalSSRC() << endl; s.addDestination("www.example.com",9000); // set one destination for packets s.setPayloadFormat(staticPayloadFormat(sptPCMU)); s.startRunning(); // start running the packet queue scheduler // Send data s.putData(0,buffer,bufferLen); // buffer holds bufferLen payload octets  File: ccrtp.info, Node: Simple Receiver, Prev: Simple Transmitter, Up: ccRTP Overview 3.2 Simple Receiver =================== The required actions to receive an application data unit over RTP are listed in the following code snippet. RTPSession s(InetHostAddress("127.0.0.1"),9000); // bind reception socket. // Initialization. cout << "Local SSRC identifier: " << s.getLocalSSRC() << endl; s.setPayloadFormat(staticPayloadFormat(sptPCMU)); s.startRunning(); // start running the packet queue scheduler. // Receive data. const AppDataUnit* adu; adu = s.getData(0); // get data with initial -0- timestamp. if ( adu != NULL ) // do something with adu. // adu->getType() provides the payload type. // adu->getData() provides a const uint8 pointer to a data buffer. // adu->getSize() provides the number of octets in the buffer. // see other methods in the class AppDataUnit, such as getSource().  File: ccrtp.info, Node: Using ccRTP, Next: Specialized Payload Formats, Prev: ccRTP Overview, Up: Top 4 Using ccRTP ************* When using ccRTP, both sending and receiving of data transported over RTP sessions is done through reception and transmission queues handled by the RTP stack. In the most common case, a separate execution thread for each 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 RTP sessions. It is also possible to not associate any separate thread with any RTP session, manually calling the main data and control service methods from whatever other thread. 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. 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 (`#include '. Two additional headers are provided by ccRTP: ``#include '' Classes for RTP extensions which are not mature yet. You must also link in the library, currently `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 RTP sessions. * Payload Types and Formats:: Payload types and formats. * Participants:: Participants and sources of synchronization. * RTP Packets Extensions:: Extensions to RTP data packets handling. * RTCP Packets Extensions:: Extensions to RTCP packets handling. * Handling Events:: Table of ccRTP plug-ins to react to events.  File: ccrtp.info, Node: RTP Sessions, Next: Payload Types and Formats, Up: Using ccRTP 4.1 RTP Sessions ================ This section discusses the use of `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:: RTP sessions initialization with ccRTP. * Sending Data:: Sending RTP data packets. * Receiving Data:: Receiving RTP data packets. * Closing Sessions:: Extensions to RTP data packets handling. * Types of Sessions:: Choosing a threading and socket model.  File: ccrtp.info, Node: Initiating Sessions, Next: Sending Data, Up: RTP Sessions 4.1.1 Initiating Sessions ------------------------- Initiating RTP sessions with ccRTP involves the construction of an object of the class `RTPSession' and calling some optional initialization methods. `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. General purpose RTP stacks of ccRTP, such as `RTPSession' objects, must be signaled to start execution. This is done calling the `startRunning()' method. Note there is also a `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: * Add destinations: calling the method `addDestination'. * Set payload format. Method `setPayloadFormat'. By default, the static payload type 0 is assumed (PCMU format at 8Khz). * 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 RTCP packets along with the mandatory CNAME, its values can be set calling the `setSDESItem' and `setPRIVPrefix' methods over the object returned by the `defaultApplication' global function. * 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). * setting addresses: * Set session bandwidth calling the `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.  File: ccrtp.info, Node: Sending Data, Next: Receiving Data, Prev: Initiating Sessions, Up: RTP Sessions 4.1.2 Sending Data ------------------ Data packets are sent through the method `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. 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 `putData') can be set through the `setMark' method, which takes a boolean as argument. ccRTP also supports fragmenting data blocks into several RTP packets. The `setMaxSendSegmentSize' method can be used to request that no RTP packet be transmitted with a payload length greater than the value specified through `setMaxSendSegmentSize'. The default value of this parameter can be retrieved via `getDefaultMaxSendSegmentSize', which currently should return 65536. When data blocks greater than the maximum segment size are provided through `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.  File: ccrtp.info, Node: Receiving Data, Next: Closing Sessions, Prev: Sending Data, Up: RTP Sessions 4.1.3 Receiving Data -------------------- Received data is retrieved from the incoming packet queue through the `getData' method, which, given a timestamp and an optional source of synchronization. This method returns a pointer to an `AppDataUnit' object as opposed to a pointer to a memory block. In ccRTP application data units are represented through objects of the `AppDataUnit' class, that provides access to the synchronization source of the data and other related properties. The incoming packet queue takes care of functions such as packet reordering or filtering out duplicate packets. You can guess if there are packets in the reception queue calling `isWaiting'. Both `getData' and `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.  File: ccrtp.info, Node: Closing Sessions, Next: Types of Sessions, Prev: Receiving Data, Up: RTP Sessions 4.1.4 Closing Sessions ---------------------- RTP sessions can be closed deleting or destroying `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 `onGotGoodbye' will be called.  File: ccrtp.info, Node: Types of Sessions, Prev: Closing Sessions, Up: RTP Sessions 4.1.5 Types of Sessions ----------------------- _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.  File: ccrtp.info, Node: Payload Types and Formats, Next: Participants, Prev: RTP Sessions, Up: Using ccRTP 4.2 Payload Types and Formats ============================= In the context of RTP, an RTP payload type is a 7-bit numeric identifier that identifies a payload format. For payload types, GNU ccRTP defines the integer type `PayloadType'. ccRTP also defines The enumerated type `StaticPayloadType', as the enumeration of the RTP Payload Types statically assigned for standard audio and video formats. These codes were initially specified in `RFC 1890, "RTP Profile for Audio and Video Conferences with Minimal Control" (AVP profile)', superseded by `RFC 3550', and are registered as MIME types in `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 RTP profile or protocol specification. See the "RTP Parameters" list at IANA `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. The properties of a payload format that, as an RTP stack, ccRTP takes into account are the payload type (numeric identifier) and the RTP clock rate. Other properties, such as MIME type, number of audio channels, "ptime" and "maxptime" are not considered. These are only of interest for higher level protocols, such as SDP and H.245. GNU ccRTP defines a hierarchy of payload format classes. Its root is `PayloadFormat', which is a base class for `StaticPayloadFormat' and `DynamicPayloadFormat'. Static payload format objects are built from a static payload code. These are defined in the enumerated type `StaticPayloadType'. The following example constructs a `StaticPayloadFormat' object corresponding to the payload type 0 (statically bounded to PCMA in `RFC 3551'): StaticPayloadType pt = sptPCMU; StaticPayloadFormat* spf = new StaticPayloadFormat(pt); Of course, we could have said: StaticPayloadFormat* spf = new StaticPayloadFormat(sptPCMA); StaticPayloadFormat objects build like the ones above hold the necessary parameters so that the RTP stack can handle incoming and outgoing packets. Regarding dynamic payload formats, a call to `DynamicPayloadFormat::DynamicPayloadFormat(100,90000)' like the following: DynamicPayloadFormat* dpf = new DynamicPayloadFormat(100,90000); Will construct a dynamic payload format object that ties together the '100' payload type numeric identifier and an 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(1). Whether and how the payload has been negotiated is outside of the scope of RTP and ccRTP, so applications must choose between `StaticPayloadFormat' and `DynamicPayloadFormat' accordingly to their multimedia session control mechanisms. ---------- Footnotes ---------- (1) Despite the fact that RFC 3551 defines a static binding of the 0 code to mu-law PCM at 8Khz.  File: ccrtp.info, Node: Participants, Next: RTP Packets Extensions, Prev: Payload Types and Formats, Up: Using ccRTP 4.3 Participants And Sources of Synchronization =============================================== In GNU ccRTP, there are classes that represent RTP applications (`RTPApplication'), participants (`Participant'), synchronizacion sources (`SyncSource') and RTP sessions (`RTPSession'). The relations among these entities are shown in the following diagram: --------------- --------------------| Participant |-------------------- | 0:n --------------- 0:1 | | 1 1:n | ------------------ ---------------- | RTPApplication | | SyncSource | ------------------ ---------------- | 1 0:n | | --------------- | --------------------| RTPSession |-------------------- 0:n --------------- 1 An RTP application establishes a space of CNAME identifiers, whereas an RTP session establishes a space of SSRC identifiers. For each source of synchronization seen in an RTP session, a `SyncSource' object identified by a SSRC numeric identifier is created. Thus, at the beginning of an RTP session there are no `SyncSource' objects related. Note that, if the local source sends packets to itself during an RTP session, a `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 `RTPSession::SyncSourcesIterator', as shown in the following 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; } Note `RTPSession::SyncSourcesIterator' is a const iterator. 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 `Participant' and `SyncSource' objects. The participant object linked to a source of synchronization can be retrieved through the `SyncSource::getParticipant()' method, as the following examples shows: // s is a source of synchronization object (SyncSource) Participant *p = s.getParticipant(); cerr << p->getSDESItem(SDESItemTypeCNAME) << endl; 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 `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 `Participant' object will be created for it. Thus, the `SyncSource::getParticipant' provides a facility for inter-media synchronization. The association of RTP sessions and participants with `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 RTP sessions are associated to an RTP application provided by the global method `defaultApplication()'. The local CNAME for the default application is guessed from the user and machine name, as specified in `RFC 3550'. However, other applications may be created through the constructor `RTPApplication::RTPApplication(const std::string& cname)'. RTP sessions are associated with applications other than the default via an optional constructor parameter. Similarly to the list of synchronization sources, the list of participants in a session can be retrieved using iterators of type `RTPApplication::ParticipantsIterator', see the following example, which shows the list of CNAMEs of the participants in the default application: RTPApplication &app = defaultApplication(); RTPApplication::ParticipantsIterator ai; for ( ai = app.begin(); ai != app.end(); ai++ ) { const Participant &p = *ai; cerr << p.getSDESItem(SDESItemTypeCNAME) << endl; } Note `RTPApplication::ParticipantsIterator' is a const iterator. _TODO: SyncSource states_.  File: ccrtp.info, Node: RTP Packets Extensions, Next: RTCP Packets Extensions, Prev: Participants, Up: Using ccRTP 4.4 RTP Packets Extensions ========================== _TODO._ Describe `RTPPacket', `IncomingRTPPkt' and `OutgoingRTPPkt' classes. *Note RTP Packets Arrival::, for a discussion of event handling virtuals that allow for specialized processing of data packets.  File: ccrtp.info, Node: RTCP Packets Extensions, Next: Handling Events, Prev: RTP Packets Extensions, Up: Using ccRTP 4.5 RTCP Packets Extensions =========================== *Note RTCP Packets Arrival::, for a discussion of event handling virtuals that allow for specialized processing of control packets.  File: ccrtp.info, Node: Handling Events, Prev: RTCP Packets Extensions, Up: Using ccRTP 4.6 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 RTP packets parsing. * RTCP Packets Arrival:: Filtering and extending RTCP packets parsing. * Synchronization Source States:: Handling state transitions. * SSRC Collisions:: Handling SSRC identifier collisions. * RTP Packets Expiration:: Outgoing and incoming RTP packets expiration.  File: ccrtp.info, Node: RTP Packets Arrival, Next: RTCP Packets Arrival, Up: Handling Events 4.6.1 RTP Packets Arrival ------------------------- `onRTPPacketRecv' is the virtual method that may be redefined in any subclass of `IncomingDataQueue', particularly in subclasses of `RTPSession'. It takes an `IncomingRTPPkt' object as argument and returns a boolean indicating whether the packet should be inserted in the reception queue.  File: ccrtp.info, Node: RTP Packets Expiration, Prev: SSRC Collisions, Up: Handling Events 4.6.2 RTP Packets Expiration ---------------------------- `onExpireSend' and `onExpireRecv' `end2EndDelayed'  File: ccrtp.info, Node: RTCP Packets Arrival, Next: Synchronization Source States, Prev: RTP Packets Arrival, Up: Handling Events 4.6.3 RTCP Packets Arrival -------------------------- Incoming RTCP packets are automatically handled by ccRTP. However, this does not mean you can't track the reception of RTCP packets. * `onGotSR' * `onGotRR' * `onGotSDESChunk' * `onGotAPP' * `onGotRRSRExtension' 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.  File: ccrtp.info, Node: Synchronization Source States, Next: SSRC Collisions, Prev: RTCP Packets Arrival, Up: Handling Events 4.6.4 Synchronization Source States ----------------------------------- `onNewSyncSource'.  File: ccrtp.info, Node: SSRC Collisions, Next: RTP Packets Expiration, Prev: Synchronization Source States, Up: Handling Events 4.6.5 SSRC Collisions --------------------- `onSSRCCollision'.  File: ccrtp.info, Node: Specialized Payload Formats, Next: Standards Tracking, Prev: Using ccRTP, Up: Top 5 Specialized Payload Formats ***************************** _TODO:_ finish 2833bis and CN. _TODO:_ comment H.261 specific RTCP packets: FIR and NACK.  File: ccrtp.info, Node: Standards Tracking, Next: Upgrading, Prev: Specialized Payload Formats, Up: Top 6 Standards Tracking ******************** _TODO: explain what is done/being done/planned_. * `RTP: A Transport Protocol for Real-Time Applications (RFC 3550, which supersedes RFC 1889)'. * `RTP Profile for Audio and Video Conferences with Minimal Control (RFC 3551, which supersedes RFC 1890)'. * `MIME Type Registration of RTP Payload Formats (RFC 3555)'. * `IANA RTP Parameters'. * `RTP Payload Format for H.261 Video Streams (RFC 2032)'. Defines H.261 specific FIR and NACK RTCP packets. Not yet implemented: * `The Secure Real-time Transport Protocol'. SRTP provile. * `Extended RTP Profile for RTCP-based Feedback (RTP/AVPF)'. * `Extended RTP Profile for RTCP-based Feedback (RTP/AVPF)'. * `Extended Secure RTP Profile for RTCP-based Feedback (RTP/SAVPF)'.  File: ccrtp.info, Node: Upgrading, Next: ccRTP Internals, Prev: Standards Tracking, Up: Top 7 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 `#include ' with `#include '(1). Changes that have to do more with Common C++ 2 than with ccRTP: `exit(int)' Replace with exit() `Thread::Terminate()' Replace with Thread::terminate() `ccxx_sleep(timeout_t)' Replace with sleep(timeout_t). `Thread::Run()' Replace with Thread::run() Changes required by ccRTP itself: `RTPSource' Now `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. `RTPQueue::getLocalInfo()->getID()' Replace with `RTPQueueBase::getLocalSSRC()' `RTPQueue::getCNAME()' Replace with `defaultApplication().getSDESItem(SDESItemTypeSDES)'. `RTPQueue::getPacket()' `getPacket()' has been removed and now there is only a `getData()' method in the RTP queues. `RTPQueue::setTimeout()' Replace calls to RTPQueue::setTimeout(microtimeout_t) with calls to OutgoingDataQueue(microtimeout_t), whose purpose and working is exactly the same. `RTPQueue::putPacket()' `putPacket()' has been removed and now there is only a `putData()' method in the RTP queues. Note also that now the payload type is not specified for each outgoing RTP data block, instead use RTPQueueBase::setPayloadFormat each time the payload type changes. `PayloadType' The definition of payload types has deeply changed in order to allow all standard uses of dynamic payload negotiation. Refer to *Note Payload Types and Formats::, for an explanation of the new payload types and formats related classes. For example, `RTP_PAYLOAD_PCMU' must be replaced with something like `StaticPayloadFormat pcmu(sptPCMU)', where `pcmu' is the name of a static payload object that binds an statically assigned `PayloadType' (2). to its corresponding RTP clock rate(3). `RTPSocket::Connect' The call connect has been removed. Now, in order to send packets to a destination `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. `RTPQueue::getCurrentRate' Replace with `RTPQueueBase::getCurrentRTPClockRate()'. `RTPSocket::Start' Replace with `RTPSession::startRunning'. `RTPQueue::gotHello' Replace with `QueueRTCPManager::onNewSyncSource'. `RTPQueue::gotGoodbye' Replace with `QueueRTCPManager::onGotGoodbye'. ---------- Footnotes ---------- (1) Note that unfortunately ccRTP 1.0pre0 used `#include : Payload Types and Formats. (line 52) * DynamicPayloadFormat: ccRTP Overview. (line 59) * DynamicPayloadType: Upgrading. (line 58) * IncomingRTPPkt: RTP Packets Extensions. (line 6) * OutgoingRTPPkt: RTP Packets Extensions. (line 6) * Participant <1>: Participants. (line 6) * Participant: ccRTP Overview. (line 59) * PayloadFormat: Payload Types and Formats. (line 25) * PayloadType: Payload Types and Formats. (line 6) * RTPApplication: Participants. (line 6) * RTPPacket: RTP Packets Extensions. (line 6) * RTPSession <1>: Participants. (line 6) * RTPSession <2>: Initiating Sessions. (line 6) * RTPSession: ccRTP Overview. (line 47) * RTPSource: Upgrading. (line 31) * StaticPayloadFormat <1>: Payload Types and Formats. (line 35) * StaticPayloadFormat: ccRTP Overview. (line 59) * StaticPayloadType <1>: Upgrading. (line 58) * StaticPayloadType <2>: Payload Types and Formats. (line 6) * StaticPayloadType: ccRTP Overview. (line 59) * SyncSource <1>: Upgrading. (line 31) * SyncSource <2>: Participants. (line 6) * SyncSource: ccRTP Overview. (line 59)  File: ccrtp.info, Node: Method and Function Index, Next: Concept Index, Prev: Class and Data Type Index, Up: Top Method and Function Index ************************* [index] * Menu: * ccxx_sleep: Upgrading. (line 22) * defaultApplication <1>: Upgrading. (line 40) * defaultApplication <2>: Participants. (line 73) * defaultApplication: Initiating Sessions. (line 30) * DynamicPayloadFormat::DynamicPayloadFormat: Payload Types and Formats. (line 52) * exit: Upgrading. (line 16) * getMRSenderInfo: ccRTP Overview. (line 47) * IncomingDataQueue::checkSSRCInIncomingRTPPkt: A.1. (line 6) * IncomingDataQueue::getData <1>: Upgrading. (line 43) * IncomingDataQueue::getData: Receiving Data. (line 6) * IncomingDataQueue::isWaiting: Receiving Data. (line 17) * IncomingDataQueue::onExpireRecv: RTP Packets Expiration. (line 6) * IncomingDataQueue::onNewSyncSource: Synchronization Source States. (line 6) * IncomingDataQueue::onRTPPacketRecv: RTP Packets Arrival. (line 6) * IncomingDataQueue::recordReception: A.8. (line 6) * IncomingDataQueue::takeInDataPacket: A.7. (line 35) * MembershipBookkeeping::SyncSourceLink::computeStats: A.3. (line 6) * onGotSR: ccRTP Overview. (line 47) * OutgoingDataQueue::addDestination: Initiating Sessions. (line 25) * OutgoingDataQueue::dispatchDataPacket: A.7. (line 38) * OutgoingDataQueue::onExpireSend: RTP Packets Expiration. (line 6) * OutgoingDataQueue::putData <1>: Upgrading. (line 52) * OutgoingDataQueue::putData: Sending Data. (line 6) * OutgoingDataQueue::setMark: Sending Data. (line 11) * OutgoingDataQueue::setPadding: Initiating Sessions. (line 38) * OutgoingDataQueue::setSchedulingTimeout: Upgrading. (line 47) * OutgoingDataQueueBase::getDefaultMaxSendSegmentSize: Sending Data. (line 16) * OutgoingDataQueueBase::setMaxSendSegmentSize: Sending Data. (line 16) * QueueRTCPMaanger::setControlBandwidth: Initiating Sessions. (line 45) * QueueRTCPManager::checkSSRCInRTCPPkt: A.1. (line 6) * QueueRTCPManager::dispatchBYE: A.7. (line 26) * QueueRTCPManager::dispatchControlPacket: A.7. (line 23) * QueueRTCPManager::end2EndDelayed: RTP Packets Expiration. (line 8) * QueueRTCPManager::onGotAPP: RTCP Packets Arrival. (line 15) * QueueRTCPManager::onGotGoodbye: Upgrading. (line 88) * QueueRTCPManager::onGotRR: RTCP Packets Arrival. (line 11) * QueueRTCPManager::onGotRRSRExtension: RTCP Packets Arrival. (line 17) * QueueRTCPManager::onGotSDES: A.5. (line 6) * QueueRTCPManager::onGotSDESChunk: RTCP Packets Arrival. (line 13) * QueueRTCPManager::onGotSR: RTCP Packets Arrival. (line 9) * QueueRTCPManager::onNewSyncSource: Upgrading. (line 85) * QueueRTCPManager::onSSRCCollision: SSRC Collisions. (line 6) * QueueRTCPManager::packSDES: A.4. (line 6) * RTCPCompoundHandler::checkCompountRTCPHeader: A.2. (line 6) * RTPApplication: Participants. (line 73) * RTPApplication::getSDESItem: Upgrading. (line 40) * RTPApplication::ParticipantsIterator: Participants. (line 86) * RTPApplication::setPRIVPrefix: Initiating Sessions. (line 30) * RTPPApplication::setSDESItem: Initiating Sessions. (line 30) * RTPQueue::getCNAME: Upgrading. (line 40) * RTPQueue::getCurrentRate: Upgrading. (line 79) * RTPQueue::getLocalInfo: Upgrading. (line 37) * RTPQueue::getLocalSSRC: Upgrading. (line 37) * RTPQueue::getPacket: Upgrading. (line 43) * RTPQueue::gotGoodbye: Upgrading. (line 88) * RTPQueue::gotHello: Upgrading. (line 85) * RTPQueue::putPacket: Upgrading. (line 52) * RTPQueue::setTimeout: Upgrading. (line 47) * RTPQueueBase::getCurrentRTPClockRate: Upgrading. (line 79) * RTPQueueBase::setPayloadFormat <1>: Upgrading. (line 52) * RTPQueueBase::setPayloadFormat: Initiating Sessions. (line 27) * RTPSession::enableStack: Initiating Sessions. (line 15) * RTPSession::startRunning <1>: Upgrading. (line 82) * RTPSession::startRunning: Initiating Sessions. (line 15) * RTPSession::SyncSourcesIterator: Participants. (line 46) * RTPSocket::Start: Upgrading. (line 82) * StaticPayloadFormat::StaticPayloadFormat: Payload Types and Formats. (line 41) * SyncSource::getParticipant(): Participants. (line 48) * Thread::sleep: Upgrading. (line 22) * Thread::terminate: Upgrading. (line 19)  File: ccrtp.info, Node: Concept Index, Prev: Method and Function Index, Up: Top Concept Index ************* [index] * Menu: * /dev/urandom <1>: A.6. (line 6) * /dev/urandom: ccRTP Overview. (line 43) * A.1: A.1. (line 6) * A.2: A.2. (line 6) * A.3: A.3. (line 6) * A.4: A.4. (line 6) * A.5: A.5. (line 6) * A.6: A.6. (line 6) * A.7: A.7. (line 6) * A.8: A.8. (line 6) * Algoritms in the Standard: Algorithms in the Standard. (line 6) * APP: RTCP Packets Arrival. (line 15) * Audio/Video Working Group: Introduction. (line 6) * AVPF: Standards Tracking. (line 26) * C++: Introduction. (line 6) * ccRTP Internals: ccRTP Internals. (line 6) * ccRTP Overview: ccRTP Overview. (line 6) * class framework: Introduction. (line 6) * clock rate: Payload Types and Formats. (line 25) * Closing Sessions: Closing Sessions. (line 6) * CNAME <1>: Participants. (line 23) * CNAME: Initiating Sessions. (line 30) * collision: SSRC Collisions. (line 6) * Collisions and Loops: Collisions and Loops. (line 6) * Common C++: Introduction. (line 6) * const iterator: Participants. (line 46) * default bandwidth: Initiating Sessions. (line 45) * default value <1>: Participants. (line 73) * default value <2>: Sending Data. (line 11) * default value: Initiating Sessions. (line 27) * demo program: ccRTP Overview. (line 47) * destination: Upgrading. (line 68) * distribution: Distribution. (line 6) * duplicate packets: Receiving Data. (line 14) * FDL, GNU Free Documentation License: GNU Free Documentation License. (line 6) * free software: Distribution. (line 6) * Future, Future Work: Future Work. (line 6) * GNU ccRTP Linking Exception: GNU ccRTP Linking Exception. (line 6) * GNU FDL: Distribution. (line 6) * GNU GPL: Distribution. (line 6) * H.245: Payload Types and Formats. (line 25) * H.323: Introduction. (line 38) * Handling Events: Handling Events. (line 6) * header check <1>: A.2. (line 6) * header check: ccRTP Overview. (line 34) * header validity <1>: A.2. (line 6) * header validity: ccRTP Overview. (line 34) * IANA: Payload Types and Formats. (line 20) * IETF <1>: Standards Tracking. (line 6) * IETF: Introduction. (line 6) * IETF standards: Standards Tracking. (line 6) * incoming queue: Using ccRTP. (line 17) * Initiating Sessions: Initiating Sessions. (line 6) * interarrival jitter: A.8. (line 6) * Internals Overview: Internals Overview. (line 6) * Internet Ingeneering Task Force: Introduction. (line 6) * Introduction: Introduction. (line 6) * iterator: Participants. (line 46) * jitter: A.8. (line 6) * join: Initiating Sessions. (line 6) * linking exception: Distribution. (line 6) * loop detection: ccRTP Overview. (line 39) * marker bit: Sending Data. (line 11) * MD5 <1>: A.6. (line 6) * MD5 <2>: ccRTP Overview. (line 43) * MD5: Introduction. (line 19) * MIME: Payload Types and Formats. (line 25) * multicast: Initiating Sessions. (line 6) * outgoing queue: Using ccRTP. (line 24) * packet queue <1>: Using ccRTP. (line 6) * packet queue: ccRTP Overview. (line 10) * padding: Initiating Sessions. (line 38) * participant: Participants. (line 48) * Participant: Participants. (line 6) * Payload Formats: Payload Types and Formats. (line 6) * payload type: Upgrading. (line 52) * Payload Types: Payload Types and Formats. (line 6) * PCMU: Initiating Sessions. (line 27) * philosophy: Distribution. (line 6) * PRIV: Initiating Sessions. (line 30) * profile: Standards Tracking. (line 24) * Random numbers <1>: A.6. (line 6) * Random numbers: ccRTP Overview. (line 43) * Receiving Data: Receiving Data. (line 6) * reception queue: Using ccRTP. (line 17) * reconsideration: ccRTP Overview. (line 41) * redundancy: Upgrading. (line 68) * Related work: Related Work. (line 6) * reordering: Receiving Data. (line 14) * reverse reconsideration: ccRTP Overview. (line 41) * RR: RTCP Packets Arrival. (line 11) * RTCP APP: RTCP Packets Arrival. (line 15) * RTCP bandwidth: Initiating Sessions. (line 45) * RTCP compound packets: Initiating Sessions. (line 30) * RTCP header: A.2. (line 6) * RTCP Packet Arrival: RTCP Packets Arrival. (line 6) * RTCP packets: Initiating Sessions. (line 30) * RTCP Packets Extensions: RTCP Packets Extensions. (line 6) * RTCP RR: RTCP Packets Arrival. (line 11) * RTCP SDES: RTCP Packets Arrival. (line 13) * RTCP SR <1>: RTCP Packets Arrival. (line 9) * RTCP SR: ccRTP Overview. (line 47) * RTCP-based feedback: Standards Tracking. (line 26) * RTP clock rate: Payload Types and Formats. (line 25) * RTP Packet Arrival: RTP Packets Arrival. (line 6) * RTP Packets Expiration: RTP Packets Expiration. (line 6) * RTP Packets Extensions: RTP Packets Extensions. (line 6) * RTP parameters: Payload Types and Formats. (line 20) * RTP Sessions: RTP Sessions. (line 6) * RTP timestamp offset: Sending Data. (line 6) * rtphello: ccRTP Overview. (line 47) * rtplisten: ccRTP Overview. (line 47) * RTSP: Introduction. (line 38) * SAVPF: Standards Tracking. (line 30) * SDES: RTCP Packets Arrival. (line 13) * SDES item: Initiating Sessions. (line 30) * SDP: Payload Types and Formats. (line 25) * Secure RTP: Standards Tracking. (line 24) * segment size: Sending Data. (line 16) * Sending Data: Sending Data. (line 6) * Session control: Payload Types and Formats. (line 66) * Session Description Protocol: Payload Types and Formats. (line 25) * signalization: Introduction. (line 38) * Simple Receiver: Simple Receiver. (line 6) * Simple Transmitter: Simple Transmitter. (line 6) * SIP: Introduction. (line 38) * sockets: Introduction. (line 19) * Source of Synchronization: Participants. (line 6) * Specialized Payload Formats: Specialized Payload Formats. (line 6) * SR <1>: RTCP Packets Arrival. (line 9) * SR: ccRTP Overview. (line 47) * SRE Extension: RTCP Packets Arrival. (line 17) * SRTP: Standards Tracking. (line 24) * SSRC collision: SSRC Collisions. (line 6) * SSRC Collision: SSRC Collisions. (line 6) * SSRC collision: ccRTP Overview. (line 39) * Standards tracking: Standards Tracking. (line 6) * static payload type: Initiating Sessions. (line 27) * synchronization: Introduction. (line 19) * Synchronization Source States: Synchronization Source States. (line 6) * system services: Introduction. (line 19) * thread: Using ccRTP. (line 6) * threading: Introduction. (line 19) * timer reconsideration: ccRTP Overview. (line 41) * timestamp clock rate: Payload Types and Formats. (line 25) * timestamp offset: Sending Data. (line 6) * transmission queue: Using ccRTP. (line 24) * Types of Sessions: Types of Sessions. (line 6) * Upgrading: Upgrading. (line 6) * Using ccRTP: Using ccRTP. (line 6)  Tag Table: Node: Top839 Node: Introduction2057 Ref: Introduction-Footnote-15454 Node: Distribution5531 Node: ccRTP Overview6806 Node: Simple Transmitter10142 Node: Simple Receiver10851 Node: Using ccRTP11841 Node: RTP Sessions14444 Node: Initiating Sessions15115 Node: Sending Data17435 Node: Receiving Data18815 Node: Closing Sessions19798 Node: Types of Sessions20590 Node: Payload Types and Formats20917 Ref: Payload Types and Formats-Footnote-124145 Node: Participants24246 Node: RTP Packets Extensions29069 Node: RTCP Packets Extensions29452 Node: Handling Events29767 Node: RTP Packets Arrival30417 Node: RTP Packets Expiration30859 Node: RTCP Packets Arrival31071 Node: Synchronization Source States31670 Node: SSRC Collisions31896 Node: Specialized Payload Formats32096 Node: Standards Tracking32365 Node: Upgrading33299 Ref: Upgrading-Footnote-136535 Ref: Upgrading-Footnote-236639 Ref: Upgrading-Footnote-336727 Node: ccRTP Internals36742 Node: Internals Overview37091 Node: Collisions and Loops37441 Node: Algorithms in the Standard38627 Node: A.139486 Node: A.240368 Node: A.340558 Node: A.440734 Node: A.540924 Node: A.641201 Node: A.741597 Node: A.842916 Node: Related Work43118 Node: Future Work43463 Node: Licenses43591 Node: GNU General Public License43959 Node: GNU Free Documentation License63224 Node: GNU ccRTP Linking Exception85651 Node: Class and Data Type Index86974 Node: Method and Function Index89451 Node: Concept Index95236  End Tag Table