rtp_session.h

Go to the documentation of this file.

/*
 * rtp_session.h
 *
 * RTP protocol session
 *
 * Open H323 Library
 *
 * Copyright (c) 1998-2012 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open H323 Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions of this code were written with the assisance of funding from
 * Vovida Networks, Inc. http://www.vovida.com.
 *
 * Contributor(s): ______________________________________.
 *
 * $Revision: 31007 $
 * $Author: rjongbloed $
 * $Date: 2013-11-29 12:10:28 +1100 (Fri, 29 Nov 2013) $
 */

#ifndef OPAL_RTP_RTP_SESSION_H
#define OPAL_RTP_RTP_SESSION_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal/buildopts.h>

#include <rtp/rtp.h>
#include <rtp/jitter.h>
#include <opal/mediasession.h>
#include <ptlib/sockets.h>
#include <ptlib/safecoll.h>
#include <ptclib/pnat.h>
#include <ptclib/url.h>

#include <list>


class PNatMethod;
class RTCP_XR_Metrics;



class OpalRTPSession : public OpalMediaSession
{
    PCLASSINFO(OpalRTPSession, OpalMediaSession);
  public:
    static const PCaselessString & RTP_AVP();
    static const PCaselessString & RTP_AVPF();

    OpalRTPSession(const Init & init);

    ~OpalRTPSession();

    virtual const PCaselessString & GetSessionType() const { return RTP_AVP(); }
    virtual bool Open(const PString & localInterface, const OpalTransportAddress & remoteAddress, bool isMediaAddress);
    virtual bool IsOpen() const;
    virtual bool Close();
    virtual bool Shutdown(bool reading);
    virtual OpalTransportAddress GetLocalAddress(bool isMediaAddress = true) const;
    virtual OpalTransportAddress GetRemoteAddress(bool isMediaAddress = true) const;
    virtual bool SetRemoteAddress(const OpalTransportAddress & remoteAddress, bool isMediaAddress = true);

    virtual void AttachTransport(Transport & transport);
    virtual Transport DetachTransport();

    virtual void SetExternalTransport(const OpalTransportAddressArray & transports);

    virtual OpalMediaStream * CreateMediaStream(
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID, 
      bool isSource
    );

    bool SetJitterBufferSize(
      const OpalJitterBuffer::Init & init   
    );

    unsigned GetJitterBufferSize() const;
    unsigned GetJitterBufferDelay() const { return GetJitterBufferSize()/GetJitterTimeUnits(); }
    
    unsigned GetJitterTimeUnits() const { return m_timeUnits; }

    virtual bool ReadData(
      RTP_DataFrame & frame   
    );

    virtual bool WriteData(
      RTP_DataFrame & frame   
    );

    virtual bool WriteOOBData(
      RTP_DataFrame & frame,
      bool rewriteTimeStamp = true
    );

    virtual bool WriteControl(
      RTP_ControlFrame & frame    
    );

    virtual void Restart(
      bool isReading
    );

    virtual PString GetLocalHostName();

#if OPAL_STATISTICS
    virtual void GetStatistics(OpalMediaStatistics & statistics, bool receiver) const;
#endif


    enum SendReceiveStatus {
      e_ProcessPacket,
      e_IgnorePacket,
      e_AbortTransport
    };
    virtual SendReceiveStatus OnSendData(RTP_DataFrame & frame);
    virtual SendReceiveStatus OnSendControl(RTP_ControlFrame & frame);
    virtual SendReceiveStatus OnReceiveData(RTP_DataFrame & frame);
    virtual SendReceiveStatus OnReceiveControl(RTP_ControlFrame & frame);

    class ReceiverReport : public PObject  {
        PCLASSINFO(ReceiverReport, PObject);
      public:
        void PrintOn(ostream &) const;

        DWORD sourceIdentifier;
        DWORD fractionLost;         /* fraction lost since last SR/RR */
        DWORD totalLost;            /* cumulative number of packets lost (signed!) */
        DWORD lastSequenceNumber;   /* extended last sequence number received */
        DWORD jitter;               /* interarrival jitter */
        PTimeInterval lastTimestamp;/* last SR packet from this source */
        PTimeInterval delay;        /* delay since last SR packet */
    };
    PARRAY(ReceiverReportArray, ReceiverReport);

    class SenderReport : public PObject  {
        PCLASSINFO(SenderReport, PObject);
      public:
        void PrintOn(ostream &) const;

        DWORD sourceIdentifier;
        PTime realTimestamp;
        DWORD rtpTimestamp;
        DWORD packetsSent;
        DWORD octetsSent;
    };

    virtual void OnRxSenderReport(const SenderReport & sender,
                                  const ReceiverReportArray & reports);
    virtual void OnRxReceiverReport(DWORD src,
                                    const ReceiverReportArray & reports);
    virtual void OnReceiverReports(const ReceiverReportArray & reports);

    class SourceDescription : public PObject  {
        PCLASSINFO(SourceDescription, PObject);
      public:
        SourceDescription(DWORD src) { sourceIdentifier = src; }
        void PrintOn(ostream &) const;

        DWORD            sourceIdentifier;
        POrdinalToString items;
    };
    PARRAY(SourceDescriptionArray, SourceDescription);
    virtual void OnRxSourceDescription(const SourceDescriptionArray & descriptions);

    virtual void OnRxGoodbye(const PDWORDArray & sources,
                             const PString & reason);

    virtual void OnRxApplDefined(const PString & type, unsigned subtype, DWORD src,
                                 const BYTE * data, PINDEX size);

#if OPAL_RTCP_XR
    class ExtendedReport : public PObject  {
        PCLASSINFO(ExtendedReport, PObject);
      public:
        void PrintOn(ostream &) const;

        DWORD sourceIdentifier;
        DWORD lossRate;            /* fraction of RTP data packets lost */ 
        DWORD discardRate;         /* fraction of RTP data packets discarded */
        DWORD burstDensity;        /* fraction of RTP data packets within burst periods */
        DWORD gapDensity;          /* fraction of RTP data packets within inter-burst gaps */
        DWORD roundTripDelay;  /* the most recently calculated round trip time */    
        DWORD RFactor;            /* voice quality metric of the call */
        DWORD mosLQ;               /* MOS for listen quality */
        DWORD mosCQ;               /* MOS for conversational quality */
        DWORD jbNominal;      /* current nominal jitter buffer delay, in ms */ 
        DWORD jbMaximum;      /* current maximum jitter buffer delay, in ms */
        DWORD jbAbsolute;     /* current absolute maximum jitter buffer delay, in ms */
    };
    PARRAY(ExtendedReportArray, ExtendedReport);

    virtual void OnRxExtendedReport(
      DWORD src,
      const ExtendedReportArray & reports
    );

    RTCP_XR_Metrics * GetExtendedMetrics() const { return m_metrics; }
#endif // OPAL_RTCP_XR


    bool IsAudio() const { return m_isAudio; }

    void SetAudio(
      bool aud    
    ) { m_isAudio = aud; }

    PString GetCanonicalName() const;

    void SetCanonicalName(const PString & name);

    PString GetToolName() const;

    void SetToolName(const PString & name);

    RTPExtensionHeaders GetExtensionHeaders() const;

    void SetExtensionHeader(const RTPExtensionHeaders & ext);

    DWORD GetSyncSourceOut() const { return syncSourceOut; }

    bool AllowAnySyncSource() const { return allowAnySyncSource; }

    void SetAnySyncSource(
      bool allow    
    ) { allowAnySyncSource = allow; }

    void SetIgnorePayloadTypeChanges(
      bool ignore   
    ) { ignorePayloadTypeChanges = ignore; }

    const PTimeInterval & GetMaxNoReceiveTime() { return m_maxNoReceiveTime; }

    void SetMaxNoReceiveTime(
      const PTimeInterval & interval 
    )  { m_maxNoReceiveTime = interval; }

    const PTimeInterval & GetMaxNoTransmitTime() { return m_maxNoTransmitTime; }

    void SetMaxNoTransmitTime(
      const PTimeInterval & interval 
    )  { m_maxNoTransmitTime = interval; }

    const PTimeInterval & GetReportTimeInterval() { return m_reportTimer.GetResetTime(); }

    void SetReportTimeInterval(
      const PTimeInterval & interval 
    )  { m_reportTimer.RunContinuous(interval); }

    unsigned GetTxStatisticsInterval() { return txStatisticsInterval; }

    void SetTxStatisticsInterval(
      unsigned packets   
    );

    unsigned GetRxStatisticsInterval() { return rxStatisticsInterval; }

    void SetRxStatisticsInterval(
      unsigned packets   
    );

    void ClearStatistics();

    virtual WORD GetLocalDataPort() const { return m_localDataPort; }

    virtual WORD GetLocalControlPort() const { return m_localControlPort; }

    virtual WORD GetRemoteDataPort() const { return m_remoteDataPort; }

    virtual WORD GetRemoteControlPort() const { return m_remoteControlPort; }

    virtual PUDPSocket & GetDataSocket() { return *m_dataSocket; }

    virtual PUDPSocket & GetControlSocket() { return *m_controlSocket; }

    DWORD GetPacketsSent() const { return packetsSent; }

    DWORD GetOctetsSent() const { return octetsSent; }

    DWORD GetPacketsReceived() const { return packetsReceived; }

    DWORD GetOctetsReceived() const { return octetsReceived; }

    DWORD GetPacketsLost() const { return packetsLost; }

    DWORD GetPacketsLostByRemote() const { return packetsLostByRemote; }

    DWORD GetPacketsOutOfOrder() const { return packetsOutOfOrder; }

    DWORD GetPacketsTooLate() const;

    DWORD GetPacketOverruns() const;

    DWORD GetAverageSendTime() const { return averageSendTime; }

    DWORD GetMarkerRecvCount() const { return markerRecvCount; }

    DWORD GetMarkerSendCount() const { return markerSendCount; }

    DWORD GetMaximumSendTime() const { return maximumSendTime; }

    DWORD GetMinimumSendTime() const { return minimumSendTime; }

    DWORD GetAverageReceiveTime() const { return averageReceiveTime; }

    DWORD GetMaximumReceiveTime() const { return maximumReceiveTime; }

    DWORD GetMinimumReceiveTime() const { return minimumReceiveTime; }

    enum { JitterRoundingGuardBits = 4 };
    DWORD GetAvgJitterTime() const { return (jitterLevel>>JitterRoundingGuardBits)/GetJitterTimeUnits(); }

    DWORD GetMaxJitterTime() const { return (maximumJitterLevel>>JitterRoundingGuardBits)/GetJitterTimeUnits(); }

    DWORD GetJitterTimeOnRemote() const { return jitterLevelOnRemote/GetJitterTimeUnits(); }

    virtual void SetCloseOnBYE(bool v)  { m_closeOnBye = v; }

    virtual void SendFlowControl(
      unsigned maxBitRate,    
      unsigned overhead = 0,  
      bool notify = false     
    );

#if OPAL_VIDEO

    virtual void SendIntraFrameRequest(bool rfc2032, bool pictureLoss);

    virtual void SendTemporalSpatialTradeOff(unsigned tradeOff);
#endif

    void SetNextSentSequenceNumber(WORD num) { lastSentSequenceNumber = (WORD)(num-1); }

    DWORD GetSyncSourceIn() const { return syncSourceIn; }

    typedef PNotifierTemplate<SendReceiveStatus &> FilterNotifier;
    #define PDECLARE_RTPFilterNotifier(cls, fn) PDECLARE_NOTIFIER2(RTP_DataFrame, cls, fn, OpalRTPSession::SendReceiveStatus &)
    #define PCREATE_RTPFilterNotifier(fn) PCREATE_NOTIFIER2(fn, OpalRTPSession::SendReceiveStatus &)

    void AddFilter(const FilterNotifier & filter);

    virtual void SendBYE();

  protected:
    ReceiverReportArray BuildReceiverReportArray(const RTP_ControlFrame & frame, PINDEX offset);
    void AddReceiverReport(RTP_ControlFrame::ReceiverReport & receiver);
    bool InsertReportPacket(RTP_ControlFrame & report);
    virtual int WaitForPDU(PUDPSocket & dataSocket, PUDPSocket & controlSocket, const PTimeInterval & timer);
    virtual SendReceiveStatus ReadDataPDU(RTP_DataFrame & frame);
    virtual SendReceiveStatus OnReadTimeout(RTP_DataFrame & frame);
    
    virtual bool InternalReadData(RTP_DataFrame & frame);
    virtual SendReceiveStatus ReadControlPDU();
    virtual SendReceiveStatus ReadDataOrControlPDU(
      BYTE * framePtr,
      PINDEX frameSize,
      bool fromDataChannel
    );
    virtual bool HandleUnreachable(PTRACE_PARAM(const char * channelName));
    virtual bool WriteDataOrControlPDU(
      const BYTE * framePtr,
      PINDEX frameSize,
      bool toDataChannel
    );


    bool                m_isAudio;
    unsigned            m_timeUnits;
    PString             m_canonicalName;
    PString             m_toolName;
    RTPExtensionHeaders m_extensionHeaders;
    PTimeInterval       m_maxNoReceiveTime;
    PTimeInterval       m_maxNoTransmitTime;

    DWORD         syncSourceOut;
    DWORD         syncSourceIn;
    DWORD         lastSentTimestamp;
    bool          allowAnySyncSource;
    bool          allowOneSyncSourceChange;
    bool          allowRemoteTransmitAddressChange;
    bool          allowSequenceChange;
    unsigned      txStatisticsInterval;
    unsigned      rxStatisticsInterval;
    WORD          lastSentSequenceNumber;
    WORD          expectedSequenceNumber;
    PTimeInterval lastSentPacketTime;
    PTimeInterval lastReceivedPacketTime;
    PTime         lastSRTimestamp;
    PTime         lastSRReceiveTime;
    PTimeInterval delaySinceLastSR;
    WORD          lastRRSequenceNumber;
    bool          resequenceOutOfOrderPackets;
    unsigned      consecutiveOutOfOrderPackets;
    PTimeInterval outOfOrderWaitTime;
    PTimeInterval outOfOrderPacketTime;
    BYTE          m_lastFIRSequenceNumber;
    BYTE          m_lastTSTOSequenceNumber;

    std::list<RTP_DataFrame> m_outOfOrderPackets;
    void SaveOutOfOrderPacket(RTP_DataFrame & frame);

    DWORD         timeStampOffs;               // offset between incoming media timestamp and timeStampOut
    bool          oobTimeStampBaseEstablished; // true if timeStampOffs has been established by media
    DWORD         oobTimeStampOutBase;         // base timestamp value for oob data
    PTimeInterval oobTimeStampBase;            // base time for oob timestamp

    // Statistics
    PTime firstPacketSent;
    DWORD packetsSent;
    DWORD rtcpPacketsSent;
    DWORD octetsSent;
    PTime firstPacketReceived;
    DWORD packetsReceived;
    DWORD senderReportsReceived;
    DWORD octetsReceived;
    DWORD packetsLost;
    DWORD packetsLostByRemote;
    DWORD packetsOutOfOrder;
    DWORD averageSendTime;
    DWORD maximumSendTime;
    DWORD minimumSendTime;
    DWORD averageReceiveTime;
    DWORD maximumReceiveTime;
    DWORD minimumReceiveTime;
    DWORD jitterLevel;
    DWORD jitterLevelOnRemote;
    DWORD maximumJitterLevel;

    DWORD m_syncTimestamp;
    PTime m_syncRealTime;

    DWORD markerSendCount;
    DWORD markerRecvCount;

    unsigned txStatisticsCount;
    unsigned rxStatisticsCount;
    
#if OPAL_RTCP_XR
    // Calculate the VoIP Metrics for RTCP-XR
    RTCP_XR_Metrics * m_metrics;
    friend class RTCP_XR_Metrics;
#endif

    DWORD    averageSendTimeAccum;
    DWORD    maximumSendTimeAccum;
    DWORD    minimumSendTimeAccum;
    DWORD    averageReceiveTimeAccum;
    DWORD    maximumReceiveTimeAccum;
    DWORD    minimumReceiveTimeAccum;
    DWORD    packetsLostSinceLastRR;
    DWORD    lastTransitTime;
    DWORD    m_lastReceivedStatisticTimestamp;
    
    RTP_DataFrame::PayloadTypes lastReceivedPayloadType;
    bool ignorePayloadTypeChanges;

    PMutex m_reportMutex;
    PTimer m_reportTimer;
    PDECLARE_NOTIFIER(PTimer, OpalRTPSession, SendReport);

    PMutex m_dataMutex;
    PMutex m_readMutex;
    bool   m_closeOnBye;
    bool   m_byeSent;

    list<FilterNotifier> m_filters;

    PIPSocket::Address m_localAddress;
    WORD               m_localDataPort;
    WORD               m_localControlPort;

    PIPSocket::Address m_remoteAddress;
    WORD               m_remoteDataPort;
    WORD               m_remoteControlPort;

    PIPSocket::Address m_remoteTransmitAddress;

    PUDPSocket * m_dataSocket;
    PUDPSocket * m_controlSocket;

    bool m_shutdownRead;
    bool m_shutdownWrite;
    bool m_remoteBehindNAT;
    bool m_localHasRestrictedNAT;
    bool m_firstControl;

    DWORD        m_noTransmitErrors;
    PSimpleTimer m_noTransmitTimer;

    // Make sure JB is last to make sure it is destroyed first.
    typedef PSafePtr<OpalJitterBuffer, PSafePtrMultiThreaded> JitterBufferPtr;
    JitterBufferPtr m_jitterBuffer;

  private:
    OpalRTPSession(const OpalRTPSession &);
    void operator=(const OpalRTPSession &) { }

  friend class RTP_JitterBuffer;
};


#endif // OPAL_RTP_RTP_H