Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages   Examples  

RTPQueue Class Reference

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

#include <cc++/rtp.h>

Inheritance diagram for RTPQueue::

Thread MembershipControl Members QueueRTCPManager RTPDuplex List of all members.

Public Methods

void Start (void)
 Make Start public. More...

const RTPSourcegetLocalInfo () const
 Get the application description. More...

bool isWaiting (const RTPSource &src=dummysource) const
 Determine if packets are waiting in the reception queue. More...

bool isCookedWaiting (void) const
 Determine if cooked packets are waiting in the reception queue. More...

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

void putPacket (uint32 stamp, rtp_payload_t payload, const unsigned char *data=NULL, size_t len=0, bool mark=false)
 This is used to create a data packet in the send queue. More...

const RTPDatagetCookedPacket (const RTPSource &src=dummysource)
 Attempt to get a cooked packet. More...

uint32 getFirstTimestamp (const RTPSource &src=dummysource)
 Get timestamp of first packet waiting in the queue. More...

uint16 getFirstSequence (const RTPSource &src=dummysource)
 Get the sequence id of the first packet waiting. More...

const RTPDatagetPacket (uint32 stamp, const RTPSource &src=dummysource)
 Retreive data from a specific timestamped packet if such a packet is currently available in the receive buffer. More...

size_t getPacket (uint32 stamp, unsigned char *data, size_t max, const RTPSource &src=dummysource)
 Retreive data from a specific timestamped packet if such a packet is currently available in the receive buffer. More...

rtp_payload_t getPayloadType (uint32 timestamp, const RTPSource &src=dummysource)
 Get the payload type of a specific packet by timestamp. More...

uint32 getCurrentTimestamp (rtp_payload_t pt) const
 Get the timestamp for a packet whose payload sampling instant corresponds to the current system time. More...

uint32 getTimestampIncrement (size_t packet_size) const
 If your application uses a fixed sampling rate and a fixed payload format, given the size of the next packet to be sent, this method provides the timestamp increment for the next packet. More...

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

uint32 getRate (rtp_payload_t pt=RTP_PAYLOAD_EMPTY) const
 Get the transmission rate for a payload type. More...

rtp_payload_t getPayloadType (const RTPSource &src) const
 Get the payload type of the first available packet. More...

const RTPSourcegetSource (uint32 ssrc) const
 Get the representation of a session participant by its Synchronization SouRCe identifier. More...

void setTypeOfService (type_of_service_t tos)
 Specify the kind of service the application expects to use. More...

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

size_t getPartial (uint32 timestamp, unsigned char *data, size_t offset, size_t max)
 Get partial data from a packet. More...

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

void setTimeout (microtimeout_t t)
 Set the default scheduling timeout to use when no data packets are waiting to be sent. More...

void setExpired (microtimeout_t t)
 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...

void setGlobalKitchenDuration (microtimeout_t t)
 Specify how much time the incoming packets will be buffered for each and every source. More...

void setGlobalKitchenSize (uint32 s)
microtimeout_t getGlobalKitchenDuration () const
 Get the current global kitchen size. More...

void setEndToEndDelay (microtimeout_t t)
 This method sets the maximun end to end delay allowed. More...

void setSegmentSize (size_t size)
 Set maximum packet segment size before fragmenting sends. More...

bool isComplete ()
 Is last packet processed "complete" or are sequences missing? More...

bool isMarked (void)
 Is last packet processed "marked" (used to signal end on multi-sequence sends). More...

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

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

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

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


Protected Methods

 RTPQueue (int pri, uint32 size=7)
 Constructor. More...

 RTPQueue (uint32 ssrc, int pri, uint32 size=7)
 Using this constructor you can start a session with the given ssrc, instead of the usual randomly generated one. More...

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

virtual void RTCPService (microtimeout_t &wait)
 A plugin point for a scheduler of RTCP packets. More...

virtual void Bye (const char *const reason)
 A plugin point for posting of BYE messages. More...

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

microtimeout_t getTimeout (void)
 This computes the timeout period for scheduling transmission of the next packet at the "head" of the send buffer. 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...

void Purge (rtp_purge_t flag)
 This function is used to purge the queue(s). More...

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

virtual size_t writeData (const unsigned char *const packet, size_t len)=0
 This function performs the physical I/O for writing a packet to the destination. More...

size_t recvPacket (void)
 This function is used by the service thread to process the next incoming packet and place it in the receive list. More...

virtual size_t readData (unsigned char *buffer, size_t len)=0
 This function performs the physical I/O for reading a packet from the source. More...

virtual bool gotPacket (IncomingRTPPkt *packet)
 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 expireSend (OutgoingRTPPkt *packet)
 A hook to filter packets being sent that have been expired. More...

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

IncomingRTPPktgetWaiting (uint32 timestamp, const RTPSource &src=dummysource)
 This is used to fetch a packet in the receive queue and to expire packets older than the current timestamp. More...

void endQueue ()
 This method ends the queue and service threads. More...

void Final ()
 The queue removes itself when the service thread is detached. More...


Protected Attributes

volatile bool active
RTPSourcelocalsrc
timeval initial_time
uint32 current_rate
uint32 initial_timestamp

Friends

class IncomingRTPPkt

Detailed Description

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

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 RTPQueue::putPacket method.

Incoming packets can be retrieved via:

Author:
David Sugar <dyfet@ostel.com>


Constructor & Destructor Documentation

RTPQueue::RTPQueue int   pri,
uint32   size = 7
[protected]
 

Constructor.

This will generate a random application SSRC identifier.

Parameters:
pri   service thread base priority relative to its parent
size   an estimation of the number of participants in the session

RTPQueue::RTPQueue uint32   ssrc,
int   pri,
uint32   size = 7
[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
pri   service thread base priority relative to it's parent
size   an estimation of the number of participants in the session

virtual RTPQueue::~RTPQueue   [protected, virtual]
 

The queue destructor flushes the queue and stops all services.


Member Function Documentation

virtual void RTPQueue::Bye const char *const   reason [inline, protected, virtual]
 

A plugin point for posting of BYE messages.

Reimplemented in QueueRTCPManager.

void RTPQueue::Final   [inline, protected]
 

The queue removes itself when the service thread is detached.

void RTPQueue::Purge rtp_purge_t   flag [protected]
 

This function is used to purge the queue(s).

Depending on the flag value, it purges the packets waiting to be sent, waiting to be picked up from the reception queue, or both.

virtual void RTPQueue::RTCPService microtimeout_t &   wait [inline, protected, virtual]
 

A plugin point for a scheduler of RTCP packets.

The default implementation in RTPQueue is to do nothing.

Parameters:
wait   queue scheduling timeout

Reimplemented in QueueRTCPManager.

uint32 RTPQueue::RTPOctetCount   const [inline]
 

Get the total number of octets (payload only) sent so far.

Returns:
total number of octets sent as payload in RTP packets.

uint32 RTPQueue::RTPSendCount   const [inline]
 

Get the total number of packets sent so far.

Returns:
total number of packets sent

void RTPQueue::Start void   [inline]
 

Make Start public.

void RTPQueue::endQueue   [protected]
 

This method ends the queue and service threads.

virtual void RTPQueue::expireRecv IncomingRTPPkt *   packet [inline, protected, virtual]
 

A hook to filter packets in the receive queue that are being expired.

Parameters:
packet   expired from the recv queue.

virtual void RTPQueue::expireSend OutgoingRTPPkt *   packet [inline, protected, virtual]
 

A hook to filter packets being sent that have been expired.

Parameters:
packet   expired from the send queue.

const RTPData& RTPQueue::getCookedPacket const RTPSource &   src = dummysource
 

Attempt to get a cooked packet.

If available, thid method will retrieve the first cooked packet. A packet is said to be cooked if:

  1. There is no disorder or lost between the last retrieved packet an the current packet.
  2. There is disorder or lost, but the queue has reached its maximun size.
Therefore, cooking means recomposing a corrupted stream -waiting for the disordered packet, regenerating it (if FEC is enabled) or asking for retransmission- whenever it is possible.

If the queue has not yet reached its maximun size (that can be set with RTPQueue::setKitchenSize), ccRTP will try to cook the packets before allowing the application to pick them up. Note that if there are more packets than the maximun, they will not be thrown away.

In order to accomplish this task, at the beginning no packet will be released until the queue reaches the kitchen size (this will provide a buffer to ccRTP where to cook the packets). Then, provided that there is no disorder, ccRTP will release every packet when asked (note that usual applications will try to retrieve packets, broadly speaking, at the same rate they are received, so the kitchen will remain the same (maximun) size if there is no lost).

If the newest packet (the one with the minor timestamp) in the queue is disordered, ccRTP will not release it until the kitchen reaches at least it maximun size. When the maximun size is reached, if disorder could not be fixed, ccRTP will then release the packet. Thus, unrepairable disorder implies the queue will stop providing packets for a while and then provide a disordered packet.

If a lost packet arrives after newer packets have been retrieved, it will be silently discarded.

Summary:

If the next packet is ordered, it will be released wheter or not the kitchen is full.

If the next packet is disordered, it will be released only when the kitchen has at least its maximun size.

Parameters:
src   optional source selector.
Returns:
the block of data contained in the first "cooked" packet.
See also:
RTPQueue::setKitchenSize , RTPQueue::isCookedWaiting

uint32 RTPQueue::getCurrentTimestamp rtp_payload_t   pt const
 

Get the timestamp 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 RTPQueue::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.
Note:
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
Parameters:
pt   payload type of the packets sent. Determines the timestamp increasing rate.

uint16 RTPQueue::getFirstSequence const RTPSource &   src = dummysource
 

Get the sequence id of the first packet waiting.

Returns:
sequence id of first packet.
Parameters:
src   optional source selector.

uint32 RTPQueue::getFirstTimestamp const RTPSource &   src = dummysource
 

Get timestamp of first packet waiting in the queue.

Parameters:
src   optional source selector.
Returns:
timestamp of first arrival packet.

microtimeout_t RTPQueue::getGlobalKitchenDuration   const [inline]
 

Get the current global kitchen size.

Note that the kitchen size can be modified individually for every source, so it is not guaranteed that this is the current kitchen for all sources.

Returns:
global kitchen size, in microseconds

const RTPSource& RTPQueue::getLocalInfo   const [inline]
 

Get the application description.

Returns:
The RTPSource object describing the local application

size_t RTPQueue::getPacket uint32   stamp,
unsigned char *   data,
size_t   max,
const RTPSource &   src = dummysource
 

Retreive data from a specific timestamped packet if such a packet is currently available in the receive buffer.

Parameters:
timestamp   of packet desired.
data   buffer to copy into.
maximum   data size.
src   optional source selector
Returns:
number of packet data bytes retrieved.
Return values:
0   if there is no such packet.

const RTPData& RTPQueue::getPacket uint32   stamp,
const RTPSource &   src = dummysource
 

Retreive data from a specific timestamped packet if such a packet is currently available in the receive buffer.

Parameters:
src   optional source selector.
Returns:
data retrieved from the reception buffer.

size_t RTPQueue::getPartial uint32   timestamp,
unsigned char *   data,
size_t   offset,
size_t   max
 

Get partial data from a packet.

This is often used to support oddball hardware that has unusual or non-standard codec buffering intervals.

Returns:
number of packet data bytes retrieved.
Parameters:
timestamp   of packet desired.
data   buffer to copy into.
offset   to copy from.
maximum   data size.

rtp_payload_t RTPQueue::getPayloadType const RTPSource &   src const
 

Get the payload type of the first available packet.

Parameters:
src   optional source selector
Returns:
payload type of the first available packet

rtp_payload_t RTPQueue::getPayloadType uint32   timestamp,
const RTPSource &   src = dummysource
 

Get the payload type of a specific packet by timestamp.

Parameters:
timestamp   to find.
src   optional source selector
Returns:
payload of specified packet if found.

uint32 RTPQueue::getRate rtp_payload_t   pt = RTP_PAYLOAD_EMPTY const
 

Get the transmission rate for a payload type.

Note that for some payload types, the transmission rate corresponds to the timestamp rate, but this is not true for all payload types.

Returns:
transmission rate corresponding to the specified payload type. If no payload type is specified, returns the timestamp rate corresponding to the first available packet.
Todo:
complete implementation

const RTPSource& RTPQueue::getSource uint32   ssrc const [inline]
 

Get the representation of a session participant by its Synchronization SouRCe identifier.

Parameters:
ssrc   an SSRC identifier
Returns:
a description of the source identified by ssrc

Reimplemented from MembershipControl.

timeout_t RTPQueue::getTimeclock void   [inline]
 

Get the packet timeclock for synchronizing timestamps.

Returns:
runtime in milliseconds since last set.

microtimeout_t RTPQueue::getTimeout void   [protected]
 

This computes the timeout period for scheduling transmission of the next packet at the "head" of the send buffer.

If no packets are waiting, a default timeout is used. This actually forms the "isPending()" timeout of the rtp receiver in the service thread.

Returns:
timeout until next packet is scheduled to send.

uint32 RTPQueue::getTimestampIncrement size_t   packet_size const
 

If your application uses a fixed sampling rate and a fixed payload format, given the size of the next packet to be sent, this method provides the timestamp increment for the next packet.

Parameters:
packet_size   the size of the next packet to be sent
Returns:
the timestamp increment for the next packet

IncomingRTPPkt* RTPQueue::getWaiting uint32   timestamp,
const RTPSource &   src = dummysource
[protected]
 

This is used to fetch a packet in the receive queue and to expire packets older than the current timestamp.

Returns:
packet buffer object for current timestamp if found.
Parameters:
timestamp   timestamp requested.
src   optional source selector
Note:
if found, the packet is removed from the reception queue

virtual bool RTPQueue::gotPacket IncomingRTPPkt *   packet [inline, protected, virtual]
 

A virtual function to support parsing of arriving packets to determine if they should be kept in the queue and to dispatch events.

Returns:
true if packet is kept.
Parameters:
packet   returned.

bool RTPQueue::isActive void   const [inline]
 

Get active connection state flag.

Returns:
true if connection "active".

bool RTPQueue::isComplete   [inline]
 

Is last packet processed "complete" or are sequences missing?

Returns:
true if complete.
Todo:
maybe, with the new RTPData, this is unnecessary. Could be useful for an application that is trying to figure out whether to start processing data or wait for misordered packets.

bool RTPQueue::isCookedWaiting void   const
 

Determine if cooked packets are waiting in the reception queue.

Note that isCookedWaiting() == true implies isWaiting() == true.

Returns:
true if there are cooked packets waiting.
Todo:
implement it

bool RTPQueue::isMarked void   [inline]
 

Is last packet processed "marked" (used to signal end on multi-sequence sends).

Returns:
true if marked.
Todo:
maybe, with the new RTPData, this is unnecessary.

virtual bool RTPQueue::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.

Reimplemented in RTPDuplex.

bool RTPQueue::isSending void   const
 

Determine if outgoing packets are waiting to send.

Returns:
true if there are packets waiting to be send.

bool RTPQueue::isWaiting const RTPSource &   src = dummysource const
 

Determine if packets are waiting in the reception queue.

Parameters:
src   optional source selector.
Returns:
true if packets are waiting.

void RTPQueue::putPacket uint32   stamp,
rtp_payload_t   payload,
const unsigned char *   data = NULL,
size_t   len = 0,
bool   mark = false
 

This is used to create a data packet in the send queue.

Sometimes a "NULL" or empty packet will be used instead, and these are known as "silent" packets. "Silent" packets are used simply to "push" the scheduler along more accurately by giving the appearence that a next packet is waiting to be sent and to provide a valid timestamp for that packet.

Parameters:
stamp   timestamp for expected send time of packet.
payload   format of this packet.
data   value or NULL if special "silent" packet.
length   may be 0 to indicate a default by payload type.
mark   mark field in the RTP header

virtual size_t RTPQueue::readData unsigned char *   buffer,
size_t   len
[protected, pure virtual]
 

This function performs the physical I/O for reading a packet from the source.

It is a virtual that is overriden in the derived class.

Returns:
number of bytes read.
Parameters:
packet   read buffer.
length   of data to read.

Reimplemented in RTPDuplex.

size_t RTPQueue::recvPacket void   [protected]
 

This function is used by the service thread to process the next incoming packet and place it in the receive list.

Returns:
number of payload bytes received. <0 if error.

size_t RTPQueue::sendPacket void   [protected]
 

This function is used by the service thread to process the next outgoing packet pending in the sending queue.

Returns:
number of bytes sent. 0 if silent, <0 if error.

void RTPQueue::setEndToEndDelay microtimeout_t   t [inline]
 

This method sets the maximun end to end delay allowed.

If the processing delay plus the trip time for a packet is greater than the end to end delay, the packet is discarded, and the application cannot get it.

This is a way of setting an upper bound to the end to end delay, computed as the elapsed time between the packet timestamping at the sender side, and the picking of the packet at the receiver side.

Parameters:
t   maximum end to end delay allowed. A value of 0 implies there is no limit and is the default

void RTPQueue::setExpired microtimeout_t   t [inline]
 

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.

Parameters:
timeout   to expire unsent packets in milliseconds.

void RTPQueue::setGlobalKitchenDuration microtimeout_t   t
 

Specify how much time the incoming packets will be buffered for each and every source.

Note that the size is specified in temporal units, thus the internal queue will usually hold as many packets as necessary to fill the specified amount of time. The default size is 0 us.

If using only the "high level" method for retrieving packets, RTPQueue::getCookedPacket(), before providing disordered packets to the application, ccRTP will try to cook them. The bigger the specified time, the higher the probability of reordering and recomposing the stream in case of corruption is.

Parameters:
t   amount of time the reception buffer fills. 0 means there is no buffer/kitchen and RTPQueue::getCookedPacket behaves as RTPQueue::getPacket does.
See also:
RTPSource::setKitchenSize() , RTPQueue::getCookedPacket() , RTPQueue::isCookedWaiting()

void RTPQueue::setGlobalKitchenSize uint32   s
 

size_t RTPQueue::setPartial uint32   timestamp,
unsigned char *   data,
size_t   offset,
size_t   max
 

Set partial data for an already queued packet.

This is often used for multichannel data.

Returns:
number of packet data bytes set.
Parameters:
timestamp   of packet desired.
data   buffer to copy from.
offset   to copy from.
maximum   data size.

void RTPQueue::setSegmentSize size_t   size [inline]
 

Set maximum packet segment size before fragmenting sends.

Parameters:
maximum   packet size.

void RTPQueue::setSessionBandwidth uint32   bw [inline]
 

Specify the bandwidth of the current session.

Parameters:
bw   bandwidth of the current session, in bits/s.
See also:
QueueRTCPManager::setControlBandwidth

void RTPQueue::setTimeclock void   [inline]
 

Set the packet timeclock for synchronizing timestamps.

void RTPQueue::setTimeout microtimeout_t   t [inline]
 

Set the default scheduling timeout to use when no data packets are waiting to be sent.

Parameters:
timeout   in milliseconds.

void RTPQueue::setTypeOfService type_of_service_t   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.
Todo:
Implement fair competition with tcp

virtual void RTPQueue::timerTick void   [inline, protected, virtual]
 

A plugin point for timer tick driven events.

virtual size_t RTPQueue::writeData const unsigned char *const   buffer,
size_t   len
[protected, pure virtual]
 

This function performs the physical I/O for writing a packet to the destination.

It is a virtual that is overriden in the derived class.

Returns:
number of bytes sent.
Parameters:
packet   to write.
length   of data to write.

Reimplemented in RTPDuplex.


Friends And Related Function Documentation

friend class IncomingRTPPkt [friend]
 


Member Data Documentation

volatile bool RTPQueue::active [protected]
 

uint32 RTPQueue::current_rate [protected]
 

struct timeval RTPQueue::initial_time [protected]
 

uint32 RTPQueue::initial_timestamp [protected]
 

RTPSource* RTPQueue::localsrc [protected]
 


The documentation for this class was generated from the following file:
Generated at Sat Jan 5 09:08:55 2002 for ccRTP by doxygen1.2.10 written by Dimitri van Heesch, © 1997-2001