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: 32454 $
 * $Author: rjongbloed $
 * $Date: 2014-08-08 17:38:38 +1000 (Fri, 08 Aug 2014) $
 */

#ifndef OPAL_RTP_RTP_SESSION_H
#define OPAL_RTP_RTP_SESSION_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal_config.h>

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

#include <list>


class OpalRTPEndPoint;
class PNatMethod;
class PSTUNServer;
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);
#if OPAL_ICE
    virtual void SetRemoteUserPass(const PString & user, const PString & pass);
#endif

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

    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,                          
      const PIPSocketAddressAndPort * remote = NULL,  
      bool rewriteHeader = true                       
    );

    void SendReport(bool force);

    virtual bool WriteControl(
      RTP_ControlFrame & frame,                      
      const PIPSocketAddressAndPort * remote = NULL  
    );

    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, bool rewriteHeader);
    virtual SendReceiveStatus OnSendControl(RTP_ControlFrame & frame);
    virtual SendReceiveStatus OnReceiveData(RTP_DataFrame & frame, PINDEX pduSize);
    virtual SendReceiveStatus OnReceiveData(RTP_DataFrame & frame);
#if OPAL_RTP_FEC
    virtual SendReceiveStatus OnSendRedundantFrame(RTP_DataFrame & frame);
    virtual SendReceiveStatus OnSendRedundantData(RTP_DataFrame::PayloadTypes & payloadType, unsigned & timestamp, BYTE * data, PINDEX & size);
    virtual SendReceiveStatus OnReceiveRedundantFrame(RTP_DataFrame & frame);
    virtual SendReceiveStatus OnReceiveRedundantData(RTP_DataFrame::PayloadTypes payloadType, unsigned timestamp, const BYTE * data, PINDEX size);
#endif
    virtual SendReceiveStatus OnReceiveControl(RTP_ControlFrame & frame);

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

        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:
#if PTRACING
        void PrintOn(ostream &) const;
#endif

        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; }
#if PTRACING
        void PrintOn(ostream &) const;
#endif

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

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

    typedef PNotifierListTemplate<const RTP_ControlFrame::ApplDefinedInfo &> ApplDefinedNotifierList;
    typedef PNotifierTemplate<const RTP_ControlFrame::ApplDefinedInfo &> ApplDefinedNotifier;

    virtual void OnRxApplDefined(const RTP_ControlFrame::ApplDefinedInfo & info);

    void AddApplDefinedNotifier(const ApplDefinedNotifier & notifier)
    {
      m_applDefinedNotifiers.Add(notifier);
    }

    void RemoveApplDefinedNotifier(const ApplDefinedNotifier & notifier)
    {
      m_applDefinedNotifiers.Remove(notifier);
    }

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

        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


    void SetSinglePort(bool v = true) { m_singlePort = v; }

    bool IsAudio() const { return m_isAudio; }

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

#if OPAL_RTP_FEC

    RTP_DataFrame::PayloadTypes GetRedundencyPayloadType() const { return m_redundencyPayloadType; }

    void SetRedundencyPayloadType(RTP_DataFrame::PayloadTypes pt) { m_redundencyPayloadType = pt; }

    RTP_DataFrame::PayloadTypes GetUlpFecPayloadType() const { return m_ulpFecPayloadType; }

    void SetUlpFecPayloadType(RTP_DataFrame::PayloadTypes pt) { m_ulpFecPayloadType = pt; }
#endif // OPAL_RTP_FEC

    PString GetCanonicalName() const;

    void SetCanonicalName(const PString & name);

    PString GetGroupId() const;

    void SetGroupId(const PString & id);

    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; }

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

    DWORD GetRoundTripTime() const { return roundTripTime; }

    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 GetLastSentTimestamp() const { return lastSentTimestamp; }
    const PTimeInterval & GetLastSentPacketTime() const { return lastSentPacketTime; }
    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();

    bool SetQoS(const PIPSocket::QoS & qos);

  protected:
    ReceiverReportArray BuildReceiverReportArray(const RTP_ControlFrame & frame, PINDEX offset);
    void AddReceiverReport(RTP_ControlFrame::ReceiverReport & receiver);
    bool InitialiseControlFrame(RTP_ControlFrame & report);
    virtual SendReceiveStatus ReadDataPDU(RTP_DataFrame & frame);
    virtual SendReceiveStatus OnReadTimeout(RTP_DataFrame & frame);
    
    virtual bool InternalReadData(RTP_DataFrame & frame);
    virtual SendReceiveStatus ReadControlPDU();
    virtual SendReceiveStatus ReadRawPDU(
      BYTE * framePtr,
      PINDEX & frameSize,
      bool fromDataChannel
    );
    virtual bool HandleUnreachable(PTRACE_PARAM(const char * channelName));
    virtual bool WriteRawPDU(
      const BYTE * framePtr,
      PINDEX frameSize,
      bool toDataChannel,
      const PIPSocketAddressAndPort * remote = NULL
    );

    OpalRTPEndPoint   & m_endpoint;
    bool                m_singlePort;
    bool                m_isAudio;
    unsigned            m_timeUnits;
    PString             m_canonicalName;
    PString             m_groupId;
    PString             m_toolName;
    RTPExtensionHeaders m_extensionHeaders;
    PTimeInterval       m_maxNoReceiveTime;
    PTimeInterval       m_maxNoTransmitTime;
#if OPAL_RTP_FEC
    RTP_DataFrame::PayloadTypes m_redundencyPayloadType;
    RTP_DataFrame::PayloadTypes m_ulpFecPayloadType;
#endif

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

    RTP_DataFrameList m_pendingPackets;
    void SaveOutOfOrderPacket(RTP_DataFrame & frame);

    // 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 roundTripTime;

    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, TimedSendReport);

    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::QoS m_qos;

    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;

    ApplDefinedNotifierList m_applDefinedNotifiers;

#if OPAL_ICE
    PSTUNServer * m_stunServer;
#endif

#if PTRACING
    unsigned m_levelTxRR;
    unsigned m_levelRxSR;
    unsigned m_levelRxRR;
    unsigned m_levelRxSDES;
#endif

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

    P_REMOVE_VIRTUAL(int,WaitForPDU(PUDPSocket&,PUDPSocket&,const PTimeInterval&),0);
    P_REMOVE_VIRTUAL(SendReceiveStatus,ReadDataOrControlPDU(BYTE *,PINDEX,bool),e_AbortTransport);
    P_REMOVE_VIRTUAL(bool,WriteDataOrControlPDU(const BYTE *,PINDEX,bool),false);
    P_REMOVE_VIRTUAL(SendReceiveStatus,OnSendData(RTP_DataFrame &),e_AbortTransport);


  friend class RTP_JitterBuffer;
};


#endif // OPAL_RTP_RTP_H