RTPDataQueue Class Referenceabstract
Generic RTP input/output queues.

A packet queue handler for building different kinds of RTP protocol systems. More...

`#include <ioqueue.h>`

Inheritance diagram for RTPDataQueue:
[legend]
Collaboration diagram for RTPDataQueue:
[legend]

## Public Types

enum | Tos { tosBestEffort , tosEnhanced }
| rtp.h cc++/rtp.h More...

## Public Member Functions

void | setTypeOfService (Tos tos)
| Specify the kind of service the application expects to use.
void | enableStack ()
| Enable packet queue processing in the stack.
void | disableStack ()
| Disable packet queue processing in the stack.
bool | isActive () const
| Get active connection state flag.
uint32 | getCurrentTimestamp () const
| Get the timestamp that should be given for a packet whose payload sampling instant corresponds to the current system time.
void | setSessionBandwidth (uint32 bw)
| Specify the bandwidth of the current session.
uint32 | getDefaultSessionBandwidth () const
uint32 | getSessionBandwidth () const
void | setTimeclock ()
| Set the packet timeclock for synchronizing timestamps.
timeout_t | getTimeclock () const
| Get the packet timeclock for synchronizing timestamps.
Public Member Functions inherited from IncomingDataQueue
SyncSourcesIterator | begin ()
SyncSourcesIterator | end ()
const AppDataUnit * | getData (uint32 stamp, const SyncSource *src=NULL)
| Retreive data from a specific timestamped packet if such a packet is currently available in the receive buffer.
bool | isWaiting (const SyncSource *src=NULL) const
| Determine if packets are waiting in the reception queue.
uint32 | getFirstTimestamp (const SyncSource *src=NULL) const
| Get timestamp of first packet waiting in the queue.
void | setMinValidPacketSequence (uint8 packets)
| When receiving packets from a new source, it may be convenient to reject a first few packets before we are really sure the source is valid.
uint8 | getDefaultMinValidPacketSequence () const
uint8 | getMinValidPacketSequence () const
| Get the minimun number of consecutive packets that must be received from a source before accepting its data packets.
void | setMaxPacketMisorder (uint16 packets)
uint16 | getDefaultMaxPacketMisorder () const
uint16 | getMaxPacketMisorder () const
void | setMaxPacketDropout (uint16 packets)
| It also prevents packets sent after a restart of the source being immediately accepted.
uint16 | getDefaultMaxPacketDropout () const
uint16 | getMaxPacketDropout () const
void | setInQueueCryptoContext (CryptoContext *cc)
| Set input queue CryptoContext.
void | removeInQueueCryptoContext (CryptoContext *cc)
| Remove input queue CryptoContext.
CryptoContext * | getInQueueCryptoContext (uint32 ssrc)
| Get an input queue CryptoContext identified by SSRC.
Public Member Functions inherited from IncomingDataQueueBase
size_t | getDefaultMaxRecvPacketSize () const
size_t | getMaxRecvPacketSize () const
void | setMaxRecvPacketSize (size_t maxsize)
Public Member Functions inherited from RTPQueueBase
bool | setPayloadFormat (const PayloadFormat &pf)
| Set the payload format in use, for timing and payload type identification purposes.
uint32 | getLocalSSRC () const
uint32 | getCurrentRTPClockRate () const
| Get the clock rate in RTP clock units (for instance, 8000 units per second for PCMU, or 90000 units per second for MP2T).
PayloadType | getCurrentPayloadType () const
timeval | getInitialTime () const
Public Member Functions inherited from OutgoingDataQueue
bool | addDestination (const InetHostAddress &ia, tpport_t dataPort=DefaultRTPDataPort, tpport_t controlPort=0)
bool | addDestination (const InetMcastAddress &ia, tpport_t dataPort=DefaultRTPDataPort, tpport_t controlPort=0)
bool | forgetDestination (const InetHostAddress &ia, tpport_t dataPort=DefaultRTPDataPort, tpport_t controlPort=0)
bool | forgetDestination (const InetMcastAddress &ia, tpport_t dataPort=DefaultRTPDataPort, tpport_t controlPort=0)
void | addContributor (uint32 csrc)
| Add csrc as the CSRC identifier of a new contributor.
bool | removeContributor (uint32 csrc)
| Remove CSRC from the list of contributors.
bool | isSending () const
| Determine if outgoing packets are waiting to send.
void | putData (uint32 stamp, const unsigned char *data=NULL, size_t len=0)
| This is used to create a data packet in the send queue.
void | sendImmediate (uint32 stamp, const unsigned char *data=NULL, size_t len=0)
| This is used to create a data packet and send it immediately.
void | setPadding (uint8 paddinglen)
| Set padding.
void | setMark (bool mark)
| Set marker bit for the packet in which the next data provided will be send.
bool | getMark () const
| Get whether the mark bit will be set in the next packet.
size_t | setPartial (uint32 timestamp, unsigned char *data, size_t offset, size_t max)
| Set partial data for an already queued packet.
microtimeout_t | getDefaultSchedulingTimeout () const
void | setSchedulingTimeout (microtimeout_t to)
| Set the default scheduling timeout to use when no data packets are waiting to be sent.
microtimeout_t | getDefaultExpireTimeout () const
void | setExpireTimeout (microtimeout_t to)
| Set the "expired" timer for expiring packets pending in the send queue which have gone unsent and are already "too late" to be sent now.
microtimeout_t | getExpireTimeout () const
uint32 | getSendPacketCount () const
| Get the total number of packets sent so far.
uint32 | getSendOctetCount () const
| Get the total number of octets (payload only) sent so far.
uint16 | getSequenceNumber () const
| Get the sequence number of the next outgoing packet.
void | setOutQueueCryptoContext (CryptoContext *cc)
| Set output queue CryptoContext.
void | removeOutQueueCryptoContext (CryptoContext *cc)
| Remove output queue CryptoContext.
CryptoContext * | getOutQueueCryptoContext (uint32 ssrc)
| Get an output queue CryptoContext identified by SSRC.
Public Member Functions inherited from OutgoingDataQueueBase
size_t | getDefaultMaxSendSegmentSize ()
void | setMaxSendSegmentSize (size_t size)
| Set maximum payload segment size before fragmenting sends.
size_t | getMaxSendSegmentSize ()

## Protected Member Functions

| RTPDataQueue (uint32 size=defaultMembersHashSize)
| Constructor.
| RTPDataQueue (uint32 *ssrc, uint32 size=defaultMembersHashSize)
| Using this constructor you can start a session with the given ssrc, instead of the usual randomly generated one.
virtual | ~RTPDataQueue ()
| The queue destructor flushes the queue and stops all services.
virtual void | timerTick ()
| A plugin point for timer tick driven events.
void | renewLocalSSRC ()
void | endQueue ()
| This method ends the queue.
virtual bool | isPendingData (microtimeout_t timeout)=0
| This function is used to check for and schedule against arriving packets based on the derived connection type.
Protected Member Functions inherited from IncomingDataQueue
| IncomingDataQueue (uint32 size)
virtual | ~IncomingDataQueue ()
bool | checkSSRCInIncomingRTPPkt (SyncSourceLink &sourceLink, bool is_new, InetAddress &na, tpport_t tp)
| Apply collision and loop detection and correction algorithm when receiving RTP data packets.
void | setSourceExpirationPeriod (uint8 intervals)
| Set the number of RTCP intervals that the stack will wait to change the state of a source from stateActive to stateInactive, or to delete the source after being in stateInactive.
virtual size_t | takeInDataPacket ()
| This function is used by the service thread to process the next incoming packet and place it in the receive list.
IncomingDataQueue::IncomingRTPPktLink * | getWaiting (uint32 timestamp, const SyncSource *src=NULL)
| This is used to fetch a packet in the receive queue and to expire packets older than the current timestamp.
bool | recordReception (SyncSourceLink &srcLink, const IncomingRTPPkt &pkt, const timeval recvtime)
| Log reception of a new RTP packet from this source.
void | recordExtraction (const IncomingRTPPkt &pkt)
| Log extraction of a packet from this source from the scheduled reception queue.
void | purgeIncomingQueue ()
virtual void | onNewSyncSource (const SyncSource &)
| Virtual called when a new synchronization source has joined the session.
virtual bool | onRTPPacketRecv (IncomingRTPPkt &)
| A virtual function to support parsing of arriving packets to determine if they should be kept in the queue and to dispatch events.
virtual void | onExpireRecv (IncomingRTPPkt &)
| A hook to filter packets in the receive queue that are being expired.
virtual bool | onSRTPPacketError (IncomingRTPPkt &pkt, int32 errorCode)
| A hook that gets called if the decoding of an incoming SRTP was erroneous.
virtual bool | end2EndDelayed (IncomingRTPPktLink &)
bool | insertRecvPacket (IncomingRTPPktLink *packetLink)
| Insert a just received packet in the queue (both general and source specific queues).
virtual size_t | recvData (unsigned char *buffer, size_t length, InetHostAddress &host, tpport_t &port)=0
| This function performs the physical I/O for reading a packet from the source.
virtual size_t | getNextDataPacketSize () const =0
Protected Member Functions inherited from IncomingDataQueueBase
| IncomingDataQueueBase ()
virtual | ~IncomingDataQueueBase ()
Protected Member Functions inherited from RTPQueueBase
| RTPQueueBase (uint32 *ssrc=NULL)
void | setLocalSSRC (uint32 ssrc)
uint32 | getLocalSSRCNetwork () const
virtual | ~RTPQueueBase ()
virtual size_t | dispatchBYE (const std::string &)
| A plugin point for posting of BYE messages.
Protected Member Functions inherited from MembershipBookkeeping
| MembershipBookkeeping (uint32 initialSize=defaultMembersHashSize)
| The initial size is a hint to allocate the resources needed in order to keep the members' identifiers and associated information.
virtual | ~MembershipBookkeeping ()
| Purges all RTPSource structures created during the session, as well as the hash table and the list of sources.
SyncSourceLink * | getLink (const SyncSource &source) const
bool | isMine (const SyncSource &source) const
| Get whether a synchronization source is recorded in this membership controller.
bool | isRegistered (uint32 ssrc)
| Returns whether there is already a synchronizacion source with "ssrc" SSRC identifier.
SyncSourceLink * | getSourceBySSRC (uint32 ssrc, bool &created)
| Get the description of a source by its `ssrc` identifier.
bool | BYESource (uint32 ssrc)
| Mark the source identified by `ssrc` as having sent a BYE packet.
bool | removeSource (uint32 ssrc)
| Remove the description of the source identified by `ssrc`.
SyncSourceLink * | getFirst ()
SyncSourceLink * | getLast ()
uint32 | getMembersCount ()
void | setMembersCount (uint32 n)
uint32 | getSendersCount ()
size_t | getDefaultMembersHashSize ()
Protected Member Functions inherited from SyncSourceHandler
| SyncSourceHandler ()
virtual | ~SyncSourceHandler ()
void * | getLink (const SyncSource &source) const
| This requires SyncSource - SyncSourceHandler friendship.
void | setLink (SyncSource &source, void *link)
void | setParticipant (SyncSource &source, Participant &p)
void | setState (SyncSource &source, SyncSource::State ns)
void | setSender (SyncSource &source, bool active)
void | setDataTransportPort (SyncSource &source, tpport_t p)
void | setControlTransportPort (SyncSource &source, tpport_t p)
void | setNetworkAddress (SyncSource &source, InetAddress addr)
Protected Member Functions inherited from ParticipantHandler
| ParticipantHandler ()
virtual | ~ParticipantHandler ()
void | setSDESItem (Participant *part, SDESItemType item, const std::string &val)
void | setPRIVPrefix (Participant *part, const std::string val)
Protected Member Functions inherited from ApplicationHandler
| ApplicationHandler ()
virtual | ~ApplicationHandler ()
void | addParticipant (RTPApplication &app, Participant &part)
void | removeParticipant (RTPApplication &app, RTPApplication::ParticipantLink *pl)
Protected Member Functions inherited from ConflictHandler
| ConflictHandler ()
virtual | ~ConflictHandler ()
ConflictingTransportAddress * | searchDataConflict (InetAddress na, tpport_t dtp)
ConflictingTransportAddress * | searchControlConflict (InetAddress na, tpport_t ctp)
void | updateConflict (ConflictingTransportAddress &ca)
void | addConflict (const InetAddress &na, tpport_t dtp, tpport_t ctp)
Protected Member Functions inherited from OutgoingDataQueue
| OutgoingDataQueue ()
virtual | ~OutgoingDataQueue ()
void | dispatchImmediate (OutgoingRTPPkt *packet)
| This is used to write the RTP data packet to one or more destinations.
microtimeout_t | getSchedulingTimeout ()
| This computes the timeout period for scheduling transmission of the next packet at the "head" of the send buffer.
size_t | dispatchDataPacket ()
| This function is used by the service thread to process the next outgoing packet pending in the sending queue.
void | setNextSeqNum (uint32 seqNum)
| For thoses cases in which the application requires a method to set the sequence number for the outgoing stream (such as for implementing the RTSP PLAY command).
uint32 | getCurrentSeqNum (void)
void | setInitialTimestamp (uint32 ts)
uint32 | getInitialTimestamp ()
void | purgeOutgoingQueue ()
virtual void | setControlPeer (const InetAddress &host, tpport_t port)
Protected Member Functions inherited from OutgoingDataQueueBase
| OutgoingDataQueueBase ()
virtual | ~OutgoingDataQueueBase ()
Protected Member Functions inherited from DestinationListHandler
void | writeLockDestinationList () const
bool | addDestinationToList (const InetAddress &ia, tpport_t data, tpport_t control)
| Locks the object before modifying it.
bool | removeDestinationFromList (const InetAddress &ia, tpport_t dataPort, tpport_t controlPort)
| Locks the object before modifying it.
| DestinationListHandler ()
| ~DestinationListHandler ()
bool | isSingleDestination () const
| Get whether there is only a destination in the list.
TransportAddress * | getFirstDestination () const
void | lockDestinationList () const
void | unlockDestinationList () const

## Additional Inherited Members

Static Public Member Functions inherited from IncomingDataQueue
static size_t | getDefaultMembersSize ()
Protected Attributes inherited from IncomingDataQueue
ThreadLock | recvLock
IncomingRTPPktLink * | recvFirst
IncomingRTPPktLink * | recvLast
uint8 | minValidPacketSequence
uint16 | maxPacketMisorder
uint16 | maxPacketDropout
uint8 | sourceExpirationPeriod
Mutex | cryptoMutex
std::list< CryptoContext * > | cryptoContexts
Protected Attributes inherited from ConflictHandler
ConflictingTransportAddress * | firstConflict
ConflictingTransportAddress * | lastConflict
Protected Attributes inherited from OutgoingDataQueue
Mutex | cryptoMutex
std::list< CryptoContext * > | cryptoContexts
Protected Attributes inherited from DestinationListHandler
std::list< TransportAddress * > | destList
Static Protected Attributes inherited from IncomingDataQueue
static const uint8 | defaultMinValidPacketSequence
static const uint16 | defaultMaxPacketMisorder
static const uint16 | defaultMaxPacketDropout
static const size_t | defaultMembersSize
Static Protected Attributes inherited from MembershipBookkeeping
static const size_t | defaultMembersHashSize
static const uint32 | SEQNUMMOD

## Detailed Description

A packet queue handler for building different kinds of RTP protocol systems.

The queue manages both incoming and outgoing RTP packets, as well as synchronization and transmission/reception timers. By making the queue handler a seperate base class it becomes possible to define RTP classes for RTP profiles and sessions of different types.

Outgoing packets are sent via the OutgoingDataQueue::putData method.

Incoming packets can be retrieved via IncomingDataQueue::getData method.

Author
  David Sugar dyfet.nosp@m.@ost.nosp@m.el.co.nosp@m.m

RTP data queue handler.

## Member Enumeration Documentation

## Tos

enum RTPDataQueue::Tos

rtp.h cc++/rtp.h

Type of network service the application uses.

If the application uses enhanced network service, for instance Integrated Services or Differentiated Services, it has not to ensure fair competition with TCP, provided that the requested service is actually being delivered. Whenever the application uses best-effort service or the requested enhanced service is not actually being delivered, it has to ensure fair competition with TCP. By default, best-effot is assumed.

Note
  Although not required, RTP packets are always sent on top of UDP segments. No other underlying transport protocol is supported at present.

Enumerator
tosBestEffort | Best-effort network service.
tosEnhanced | Enhanced network service.

## Constructor & Destructor Documentation

## RTPDataQueue() [1/2]

RTPDataQueue::RTPDataQueue | ( | uint32 | size = defaultMembersHashSize | ) |

protected

Constructor.

This will generate a random application SSRC identifier.

Parameters

  size | an estimation of the number of participants in the session

## RTPDataQueue() [2/2]

RTPDataQueue::RTPDataQueue | ( | uint32 * | ssrc,
|  | uint32 | size = defaultMembersHashSize )

protected

Using this constructor you can start a session with the given ssrc, instead of the usual randomly generated one.

This is necessary when you need to initiate several sessions having the same SSRC identifier, for instance, to implement layered encoding, in which case each layer is managed through a different session but all sessions share the same SSRC identifier.

Warning
  This doesn't seem to be a good solution

Parameters

  ssrc | Synchronization SouRCe identifier for this session
  size | an estimation of the number of participants in the session

## ~RTPDataQueue()

virtual RTPDataQueue::~RTPDataQueue | ( |  | ) |

inline protected virtual

The queue destructor flushes the queue and stops all services.

## Member Function Documentation

## disableStack()

void RTPDataQueue::disableStack | ( | void |  | ) |

inline

Disable packet queue processing in the stack.

## enableStack()

void RTPDataQueue::enableStack | ( | void |  | ) |

inline

Enable packet queue processing in the stack.

This method will not any thread of execution.

## endQueue()

void RTPDataQueue::endQueue | ( |  | ) |

protected

This method ends the queue.

## getCurrentTimestamp()

uint32 RTPDataQueue::getCurrentTimestamp | ( |  | ) | const

Get the timestamp that should be given for a packet whose payload sampling instant corresponds to the current system time.

The timestamp applications should provide for each packet represents the sampling instant of its payload and should not be a reading of the system clock. Nevertheless, the internal operation of the RTP stack relies on the accuracy of the provided timestamp, since several computations assume that there is a certain degree of correspondence between the timestamp and the system clock.

It is recommended that applications use this method in order to periodically adjust the RTP timestamp.

In particular, it is advisable getting the timestamp corresponding to the first sampling instant or any instant after a period of inactivity through a call to this method.

Applications should use the nominal sampling or any other value provided by the coder in order to compute the next timestamps with minimum computational requirement.

For instance, an application using an RTP profile that specifies a fixed sampling rate of 8 Khz with eight bits per sample, continuously transmitting audio blocks 80 octets long, would transmit 100 packets every second. Every packet would carry a timestamp 80 units greater than the previous one. So, the first timestamp would be obtained from this method, whereas the following ones would be computed adding 80 every time. Also the timestamp should be increased for every block whether it is put in the queue or dropped.

The aforementioned increment can be obtained from the RTPDataQueue::getTimestampIncrement() method rather than computing it by hand in the application.

Note
  Frame based applications must follow a specific timestamping method, probably specified in a profile.
  You should take into account that by default ccRTP assumes that the application begins sampling at the queue creation time. Moreover, the first sampling instant is assigned a "user visible" timestamp of 0, although the RTP stack will then add internally a ramdom offset unknown to the application. That is to say, the application may count samples from 0 in order to get the timestamp for the next packet, provided that the first sampling instant is the same as the queue creation time. Nevertheless, this simpler way of starting will not be as accurate as it would be if the application got at least the first timestamp through getCurrentTimestamp. We provide this option since ccRTP interface is evolving, but we admit that it is ugly, we could remove this option or even replace uint32 timestamps with a restrictively regulated object; suggestions are gladly welcomed

Examples
  rtphello.cpp.

## getDefaultSessionBandwidth()

uint32 RTPDataQueue::getDefaultSessionBandwidth | ( |  | ) | const

inline

## getSessionBandwidth()

uint32 RTPDataQueue::getSessionBandwidth | ( |  | ) | const

inline

## getTimeclock()

timeout_t RTPDataQueue::getTimeclock | ( |  | ) | const

inline

Get the packet timeclock for synchronizing timestamps.

Returns
  runtime in milliseconds since last set.

## isActive()

bool RTPDataQueue::isActive | ( |  | ) | const

inline

Get active connection state flag.

Returns
  true if connection "active".

Examples
  audiorx.cpp, audiotx.cpp, and rtphello.cpp.

## isPendingData()

virtual bool RTPDataQueue::isPendingData | ( | microtimeout_t | timeout | ) |

protected pure virtual

This function is used to check for and schedule against arriving packets based on the derived connection type.

Returns
  true if packet waiting for processing.

Parameters

  number | of microseconds to wait.

Implemented in RTPDuplex, SingleThreadRTPSession< RTPDataChannel, RTCPChannel, ServiceQueue >, SingleThreadRTPSession< SymmetricRTPChannel, SymmetricRTPChannel >, TRTPSessionBase< RTPDataChannel, RTCPChannel, ServiceQueue >, and TRTPSessionBase< DualRTPUDPIPv4Channel, DualRTPUDPIPv4Channel, AVPQueue >.

## renewLocalSSRC()

void RTPDataQueue::renewLocalSSRC | ( |  | ) |

inline protected virtual

Reimplemented from IncomingDataQueue.

## setSessionBandwidth()

void RTPDataQueue::setSessionBandwidth | ( | uint32 | bw | ) |

inline

Specify the bandwidth of the current session.

Parameters

  bw | bandwidth of the current session, in bits/s.

See also
  AVPQueue::setControlBandwidth()

## setTimeclock()

void RTPDataQueue::setTimeclock | ( |  | ) |

inline

Set the packet timeclock for synchronizing timestamps.

## setTypeOfService()

void RTPDataQueue::setTypeOfService | ( | Tos | tos | ) |

inline

Specify the kind of service the application expects to use.

Parameters

  tos | type of service the application expects to use

Note
  If enhanced service is specified but packet loss is high (the requested service does not appear to actually be delivered) ccRTP defaults to best-effort suitable behaviour: guarantee fair competition with TCP.

## timerTick()

virtual void RTPDataQueue::timerTick | ( | void |  | ) |

inline protected virtual

A plugin point for timer tick driven events.

Reimplemented in SingleThreadRTPSession< RTPDataChannel, RTCPChannel, ServiceQueue >, and SingleThreadRTPSession< SymmetricRTPChannel, SymmetricRTPChannel >.

The documentation for this class was generated from the following file:

- ioqueue.h