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

#include <ioqueue.h>

Inheritance diagram for RTPDataQueue:

Collaboration diagram for RTPDataQueue:

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. More...

void	enableStack ()
	Enable packet queue processing in the stack. More...

void	disableStack ()
	Disable packet queue processing in the stack. More...

bool	isActive () const
	Get active connection state flag. More...

uint32	getCurrentTimestamp () const
	Get the timestamp that should be given for a packet whose payload sampling instant corresponds to the current system time. More...

void	setSessionBandwidth (uint32 bw)
	Specify the bandwidth of the current session. More...

uint32	getDefaultSessionBandwidth () const

uint32	getSessionBandwidth () const

void	setTimeclock ()
	Set the packet timeclock for synchronizing timestamps. More...

timeout_t	getTimeclock () const
	Get the packet timeclock for synchronizing timestamps. More...

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. More...

bool	isWaiting (const SyncSource *src=NULL) const
	Determine if packets are waiting in the reception queue. More...

uint32	getFirstTimestamp (const SyncSource *src=NULL) const
	Get timestamp of first packet waiting in the queue. More...

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. More...

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. More...

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. More...

uint16	getDefaultMaxPacketDropout () const

uint16	getMaxPacketDropout () const

void	setInQueueCryptoContext (CryptoContext *cc)
	Set input queue CryptoContext. More...

void	removeInQueueCryptoContext (CryptoContext *cc)
	Remove input queue CryptoContext. More...

CryptoContext *	getInQueueCryptoContext (uint32 ssrc)
	Get an input queue CryptoContext identified by SSRC. More...

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. More...

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). More...

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. More...

bool	removeContributor (uint32 csrc)
	Remove CSRC from the list of contributors. More...

bool	isSending () const
	Determine if outgoing packets are waiting to send. More...

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. More...

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. More...

void	setPadding (uint8 paddinglen)
	Set padding. More...

void	setMark (bool mark)
	Set marker bit for the packet in which the next data provided will be send. More...

bool	getMark () const
	Get whether the mark bit will be set in the next packet. More...

size_t	setPartial (uint32 timestamp, unsigned char *data, size_t offset, size_t max)
	Set partial data for an already queued packet. More...

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. More...

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. More...

microtimeout_t	getExpireTimeout () const

uint32	getSendPacketCount () const
	Get the total number of packets sent so far. More...

uint32	getSendOctetCount () const
	Get the total number of octets (payload only) sent so far. More...

uint16	getSequenceNumber () const
	Get the sequence number of the next outgoing packet. More...

void	setOutQueueCryptoContext (CryptoContext *cc)
	Set output queue CryptoContext. More...

void	removeOutQueueCryptoContext (CryptoContext *cc)
	Remove output queue CryptoContext. More...

CryptoContext *	getOutQueueCryptoContext (uint32 ssrc)
	Get an output queue CryptoContext identified by SSRC. More...

Public Member Functions inherited from OutgoingDataQueueBase
size_t	getDefaultMaxSendSegmentSize ()

void	setMaxSendSegmentSize (size_t size)
	Set maximum payload segment size before fragmenting sends. More...

size_t	getMaxSendSegmentSize ()

Protected Member Functions
	RTPDataQueue (uint32 size=defaultMembersHashSize)
	Constructor. More...

	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. More...

virtual	~RTPDataQueue ()
	The queue destructor flushes the queue and stops all services. More...

virtual void	timerTick ()
	A plugin point for timer tick driven events. More...

void	renewLocalSSRC ()

void	endQueue ()
	This method ends the queue. More...

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. More...

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. More...

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. More...

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. More...

void	renewLocalSSRC ()

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. More...

bool	recordReception (SyncSourceLink &srcLink, const IncomingRTPPkt &pkt, const timeval recvtime)
	Log reception of a new RTP packet from this source. More...

void	recordExtraction (const IncomingRTPPkt &pkt)
	Log extraction of a packet from this source from the scheduled reception queue. More...

void	purgeIncomingQueue ()

virtual void	onNewSyncSource (const SyncSource &)
	Virtual called when a new synchronization source has joined the session. More...

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. More...

virtual void	onExpireRecv (IncomingRTPPkt &)
	A hook to filter packets in the receive queue that are being expired. More...

virtual bool	onSRTPPacketError (IncomingRTPPkt &pkt, int32 errorCode)
	A hook that gets called if the decoding of an incoming SRTP was erroneous. More...

virtual bool	end2EndDelayed (IncomingRTPPktLink &)

bool	insertRecvPacket (IncomingRTPPktLink *packetLink)
	Insert a just received packet in the queue (both general and source specific queues). More...

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. More...

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. More...

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. More...

virtual	~MembershipBookkeeping ()
	Purges all RTPSource structures created during the session, as well as the hash table and the list of sources. More...

SyncSourceLink *	getLink (const SyncSource &source) const

bool	isMine (const SyncSource &source) const
	Get whether a synchronization source is recorded in this membership controller. More...

bool	isRegistered (uint32 ssrc)
	Returns whether there is already a synchronizacion source with "ssrc" SSRC identifier. More...

SyncSourceLink *	getSourceBySSRC (uint32 ssrc, bool &created)
	Get the description of a source by its `ssrc` identifier. More...

bool	BYESource (uint32 ssrc)
	Mark the source identified by `ssrc` as having sent a BYE packet. More...

bool	removeSource (uint32 ssrc)
	Remove the description of the source identified by `ssrc` More...

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. More...

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. More...

microtimeout_t	getSchedulingTimeout ()
	This computes the timeout period for scheduling transmission of the next packet at the "head" of the send buffer. More...

size_t	dispatchDataPacket ()
	This function is used by the service thread to process the next outgoing packet pending in the sending queue. More...

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). More...

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. More...

bool	removeDestinationFromList (const InetAddress &ia, tpport_t dataPort, tpport_t controlPort)
	Locks the object before modifying it. More...

	DestinationListHandler ()

	~DestinationListHandler ()

bool	isSingleDestination () const
	Get whether there is only a destination in the list. More...

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.

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 ( )

inlineprotectedvirtual

The queue destructor flushes the queue and stops all services.

Member Function Documentation

void RTPDataQueue::disableStack ( )

inline

Disable packet queue processing in the stack.

void RTPDataQueue::enableStack ( )

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

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".

virtual bool RTPDataQueue::isPendingData ( microtimeout_t timeout )

protectedpure 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.

void RTPDataQueue::renewLocalSSRC ( )

inlineprotectedvirtual

Reimplemented from RTPQueueBase.

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 ( )

inlineprotectedvirtual

A plugin point for timer tick driven events.

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

ioqueue.h

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation