Provided by: libccrtp-doc_2.0.9-2.5build1_all 
NAME
RTPDataQueue - A packet queue handler for building different kinds of RTP protocol
systems.
SYNOPSIS
#include <ioqueue.h>
Inherits IncomingDataQueue, and OutgoingDataQueue.
Inherited by QueueRTCPManager, and RTPDuplex.
Public Types
enum Tos { tosBestEffort, tosEnhanced }
rtp.h cc++/rtp.h
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@ostel.com
RTP data queue handler.
Member Enumeration Documentation
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::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::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
virtual RTPDataQueue::~RTPDataQueue () [inline], [protected], [virtual]
The queue destructor flushes the queue and stops all services.
Member Function Documentation
void RTPDataQueue::disableStack (void) [inline]
Disable packet queue processing in the stack.
void RTPDataQueue::enableStack (void) [inline]
Enable packet queue processing in the stack. This method will not any thread of execution.
void RTPDataQueue::endQueue () [protected]
This method ends the queue.
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.
uint32 RTPDataQueue::getDefaultSessionBandwidth () const [inline]
uint32 RTPDataQueue::getSessionBandwidth () const [inline]
timeout_t RTPDataQueue::getTimeclock () const [inline]
Get the packet timeclock for synchronizing timestamps.
Returns
runtime in milliseconds since last set.
bool RTPDataQueue::isActive () const [inline]
Get active connection state flag.
Returns
true if connection 'active'.
Examples
audiorx.cpp, audiotx.cpp, and rtphello.cpp.
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, TRTPSessionBase< RTPDataChannel, RTCPChannel, ServiceQueue >,
TRTPSessionBase< DualRTPUDPIPv4Channel, DualRTPUDPIPv4Channel, AVPQueue >, and
SingleThreadRTPSession< RTPDataChannel, RTCPChannel, ServiceQueue >.
void RTPDataQueue::renewLocalSSRC () [inline], [protected], [virtual]
Reimplemented from IncomingDataQueue.
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()
void RTPDataQueue::setTimeclock () [inline]
Set the packet timeclock for synchronizing timestamps.
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.
virtual void RTPDataQueue::timerTick (void) [inline], [protected], [virtual]
A plugin point for timer tick driven events.
Reimplemented in SingleThreadRTPSession< RTPDataChannel, RTCPChannel, ServiceQueue >.
Author
Generated automatically by Doxygen for ccRTP from the source code.
ccRTP RTPDataQueue(3)