cqueue.h

ccrtp, ccrtp-1.5.0.tar.gz

// Copyright (C) 2001,2002,2004 Federico Montesino Pouzols <[e-mail]>.
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
//
// As a special exception, you may use this file as part of a free software
// library without restriction.  Specifically, if other files instantiate
// templates or use macros or inline functions from this file, or you compile
// this file and link it with other files to produce an executable, this
// file does not by itself cause the resulting executable to be covered by
// the GNU General Public License.  This exception does not however
// invalidate any other reasons why the executable file might be covered by
// the GNU General Public License.
//
// This exception applies only to the code released under the name GNU
// ccRTP.  If you copy code from other releases into a copy of GNU
// ccRTP, as the General Public License permits, the exception does
// not apply to the code that you add in this way.  To avoid misleading
// anyone as to the status of such modified files, you must delete
// this exception notice from them.
//
// If you write modifications of your own for GNU ccRTP, it is your choice
// whether to permit this exception to apply to your modifications.
// If you do not wish that, delete this exception notice.
//

/**
 * @file cqueue.h
 *
 * @short Generic RTCP control queues.
 **/

#ifndef	CCXX_RTP_CQUEUE_H_
#define CCXX_RTP_CQUEUE_H_

#include <ccrtp/ioqueue.h>

#ifdef	CCXX_NAMESPACES
namespace ost {
#endif

/**
 * @defgroup cqueue Generic RTCP control queues.
 * @{
 **/

/**
 * @class QueueRTCPManager
 * @short Adds generic management of RTCP functions to an RTP data
 * queue.
 *
 * Extends an RTP data i/o queue adding management of RTCP functions:
 *
 * Provide feedback on the quality of the data distribution.
 *
 * Convey the CNAME (persistent transport-level identifier) for every
 * RTP source.
 *
 * Control the sending rate of RTCP packets
 *
 * Convey minimal control information about the participants
 *
 * This class implements generic RTCP behaviour (as specified in RFC
 * 1889/draft-ietf-avt-rtp-new) and may be specialized for specific
 * profiles (see AVPQueue) or particular RTCP extensions.
 *
 * @author Federico Montesino Pouzols <[e-mail]>
 **/
class __EXPORT QueueRTCPManager : public RTPDataQueue,
	protected RTCPCompoundHandler
{
public:
	/**
	 * Get the most recent sender report received from a
	 * synchronization source.
	 *
	 * @param src Synchronization source of the sender info.
	 * @return Most recent sender info received from src.
	 * @retval NULL when no sender report has been received from
	 * the specified source.
	 **/
	RTCPSenderInfo* getMRSenderInfo(SyncSource& src);

	/**
	 * Ask for the info in the most recent receiver report about
	 * the local source received from the source given as
	 * parameter.
	 *
	 * @param srcFrom Source of the receiver info.
	 * @return most recent receiver info received from src.
	 * @retval NULL when no receiver report has been received from
	 * the specified source.
	 */
	RTCPReceiverInfo* getMRReceiverInfo(SyncSource& srcFrom);

	/**
	 * Set how much time the stack will wait before deleting a
	 * synchronization source that has sent an RTCP BYE packet.
	 *
	 * @param delay delay in microseconds.
	 *
	 * @note The default delay is 1000000 microseconds
	 **/
	void setLeavingDelay(microtimeout_t delay)
	{ leavingDelay = delay; }

	/**
	 * This method sets the maximum 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.
	 *
	 * @param t maximum end to end delay allowed. A value of 0
	 * implies there is no limit and is the default
	 */
	inline void
	setEnd2EndDelay(microtimeout_t t)
		{ end2EndDelay = t; };

	inline microtimeout_t
	getDefaultEnd2EndDelay() const
	{ return defaultEnd2EndDelay; }

	inline microtimeout_t
	getEnd2EndDelay() const
	{ return end2EndDelay; }

	/**
	 * Specify the fraction of the total control bandwith to be
	 * dedicated to senders reports.
	 *
	 * @param fraction fraction of bandwidth, must be between 0 an 1.
	 *
	 * This method sets the fraction of the global control
	 * bandwidth that will be dedicated to senders reports. Of
	 * course, <code>1 - fraction</code> will be dedicated to
	 * receivers reports.
	 *
	 * @see setControlBandwidth
	 */
	inline void
	setSendersControlFraction(float fraction)
	{ sendControlBwFract = fraction; recvControlBwFract = 1 - fraction;};

	/**
	 * Manually set the minimum interval for sending RTP compound
	 * packets
	 *
	 * @param interval minimum interval between RTCP packets, in
	 * microseconds.
	 *
	 * @see computeRTCPInterval()
	 **/
	void
	setMinRTCPInterval(microtimeout_t interval)
	{ rtcpMinInterval = interval; }

	/**
	 * Get the total number of RTCP packets sent until now
	 **/
	inline uint32
	getSendRTCPPacketCount() const
	{ return ctrlSendCount; }

protected:
	QueueRTCPManager(uint32 size = RTPDataQueue::defaultMembersHashSize,
			 RTPApplication& app = defaultApplication());

	QueueRTCPManager(uint32 ssrc,
			 uint32 size = RTPDataQueue::defaultMembersHashSize,
			 RTPApplication& app = defaultApplication());

	virtual
	~QueueRTCPManager();

	const RTPApplication&
	getApplication()
	{ return queueApplication; }

	inline void
	setControlBandwidth(float fraction)
	{ controlBwFract = fraction; }

	float
	getControlBandwidth() const
	{ return controlBwFract; }

	/**
	 * Build and send RTCP packets following timing rules
	 * (including the "timer reconsideration" algorithm).
	 **/
	void
	controlTransmissionService();

	/**
	 * Process incoming RTCP packets pending in the control
	 * reception socket.
	 **/
	void
	controlReceptionService();

	/**
	 * Appy collision and loop detection and correction algorithm
	 * when receiving RTCP packets. Follows section 8.2 in
	 * draft-ietf-avp-rtp-new.
	 *
	 * @param sourceLink link to the source object.
	 * @param is_new whether the source has been just recorded.
	 * @param na RTCP packet network address.
	 * @param tp RTCP packet source transport port.
	 *
	 * @return whether the packet must not be discarded.
	 **/
	bool checkSSRCInRTCPPkt(SyncSourceLink& sourceLink, bool is_new,
				InetAddress& na, tpport_t tp);

	void
	endQueueRTCPManager();

	/**
	 * Plug-in for processing (acquire information carried in) an
	 * incoming RTCP Sender Report. The default implementation in
	 * this class only processes the sender information and the
	 * receiver report blocks about the local source.
	 *
	 * @param source Synchronization source this report comes from.
	 * @param SR Sender report structure.
	 * @param blocks Number of report blocks in the packet.
	 **/
	virtual void
	onGotSR(SyncSource& source, SendReport& SR, uint8 blocks);

	/**
	 * Plug-in for processing (acquire information carried in) an
	 * incoming RTCP Receiver Report. The default implementation
	 * in this class only processes the receiver report blocks
	 * about the local source.
	 *
	 * @param source Synchronization source this report comes from.
	 * @param RR Receiver report structure
	 * @param blocks Number of report blocks in the packet
	 **/
	virtual void
	onGotRR(SyncSource& source, RecvReport& RR, uint8 blocks);

	/**
	 * @param source Synchronization source of SDES RTCP packet.
	 * @param pkt SDES RTCP packet received.
	 **/
	bool
	onGotSDES(SyncSource& source, RTCPPacket& pkt);

	/**
	 * Plug-in for handling of SDES chunks.
	 *
	 * @param source Synchronization source of SDES chunk.
	 * @param chunk SDES chunk structure.
	 * @param len Length of chunk, in octets.
	 *
	 * @return whether there was a CNAME.
	 **/
	virtual bool
	onGotSDESChunk(SyncSource& source, SDESChunk& chunk, size_t len);

	/**
	 * Plug-in for handling of APP (application specific) RTCP
	 * packets.
	 *
	 * @param - Synchronization source of this packet.
	 * @param - RTCP APP packet struct.
	 * @param - Length of the app data packet, including ssrc.
	 * name and app. specific data.
	 **/
	inline virtual void
	onGotAPP(SyncSource&, RTCPCompoundHandler::APPPacket&,
		 size_t)
	{ return; }

	inline timeval
	getRTCPCheckInterval()
	{ return rtcpCheckInterval; }

	/**
	 * Get the number of data packets sent at the time the last SR
	 * was generated.
	 **/
	uint32
	getLastSendPacketCount() const
	{ return lastSendPacketCount; }

	/**
	 * @param n Number of members.
	 **/
	inline void
	setPrevMembersNum(uint32 n)
	{ reconsInfo.rtcpPMembers = n; };

	inline uint32
	getPrevMembersCount() const
	{ return reconsInfo.rtcpPMembers; };

	/**
	 * This method is used to send an RTCP BYE packet.  An RTCP
	 * BYE packet is sent when one of the the following
	 * circumstances occur:
	 * - when leaving the session
	 * - when we have detected that another synchronization source
	 * in the same session is using the same SSRC identifier as
	 * us.
	 *
	 * Try to post a BYE message. It will send a BYE packet as
	 * long as at least one RTP or RTCP packet has been sent
	 * before. If the number of members in the session is more
	 * than 50, the algorithm described in section 6.3.7 of
	 * RFC 3550 is applied in order to avoid a flood
	 * of BYE messages.
	 *
	 * @param reason reason to specify in the BYE packet.
	 **/
	size_t
	dispatchBYE(const std::string& reason);

	size_t
	sendControlToDestinations(unsigned char* buffer, size_t len);

private:
	QueueRTCPManager(const QueueRTCPManager &o);