mediastrm.h

Go to the documentation of this file.

/*
 * mediastrm.h
 *
 * Media Stream classes
 *
 * Open Phone Abstraction Library (OPAL)
 * Formally known as the Open H323 project.
 *
 * Copyright (c) 2001 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 Phone Abstraction Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): ______________________________________.
 *
 * $Revision: 31688 $
 * $Author: rjongbloed $
 * $Date: 2014-04-07 15:10:24 +1000 (Mon, 07 Apr 2014) $
 */

#ifndef OPAL_OPAL_MEDIASTRM_H
#define OPAL_OPAL_MEDIASTRM_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal_config.h>

#include <ptclib/delaychan.h>

#include <opal/mediafmt.h>
#include <opal/mediacmd.h>
#include <rtp/jitter.h>
#include <ptlib/safecoll.h>
#include <ptclib/guid.h>


class OpalRTPSession;
class OpalMediaPatch;
class OpalLine;
class OpalConnection;
class OpalRTPConnection;
class OpalMediaStatistics;


typedef PSafePtr<OpalMediaPatch, PSafePtrMultiThreaded> OpalMediaPatchPtr;


class OpalMediaStream : public PSafeObject
{
    PCLASSINFO(OpalMediaStream, PSafeObject);
  protected:
    OpalMediaStream(
      OpalConnection & conn,               
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      bool isSource                        
    );

  public:
    ~OpalMediaStream();

  public:
    void PrintOn(
      ostream & strm    
    ) const;

    virtual OpalMediaFormat GetMediaFormat() const;

    virtual bool SetMediaFormat(
      const OpalMediaFormat & mediaFormat   
    );

    bool UpdateMediaFormat(
      const OpalMediaFormat & mediaFormat,    
      bool mergeOnly = false                  
    );

    bool ExecuteCommand(
      const OpalMediaCommand & command    
    ) const;

    virtual PBoolean Open();

    virtual bool IsOpen() const;

    virtual PBoolean Start();

    virtual PBoolean Close();

    virtual void OnStartMediaPatch();

    virtual void OnStopMediaPatch(
      OpalMediaPatch & patch    
    );

    virtual PBoolean WritePackets(
      RTP_DataFrameList & packets
    );

    virtual PBoolean ReadPacket(
      RTP_DataFrame & packet
    );

    virtual PBoolean WritePacket(
      RTP_DataFrame & packet
    );

    virtual PBoolean ReadData(
      BYTE * data,      
      PINDEX size,      
      PINDEX & length   
    );

    virtual PBoolean WriteData(
      const BYTE * data,   
      PINDEX length,       
      PINDEX & written     
    );

    bool PushPacket(
      RTP_DataFrame & packet
    );

    virtual PBoolean SetDataSize(
      PINDEX dataSize,  
      PINDEX frameTime  
    );

    PINDEX GetDataSize() const { return m_defaultDataSize; }

    virtual PBoolean IsSynchronous() const = 0;

    virtual PBoolean RequiresPatchThread(
      OpalMediaStream * stream  
    ) const;
    virtual PBoolean RequiresPatchThread() const; // For backward compatibility

    virtual bool EnableJitterBuffer(bool enab = true) const;

    OpalConnection & GetConnection() const { return connection; }

    bool IsSource() const { return m_isSource; }

    bool IsSink() const { return !m_isSource; }

    unsigned GetSessionID() const { return sessionID; }

    void SetSessionID(unsigned id) { sessionID = id; }

    PString GetID() const { return identifier; }

    unsigned GetTimestamp() const { return timestamp; }

    void SetTimestamp(unsigned ts) { timestamp = ts; }

    bool GetMarker() const { return marker; }

    void SetMarker(bool m) { marker = m; }

    bool IsPaused() const { return m_paused; }

    bool SetPaused(
      bool pause  
    ) { return InternalSetPaused(pause, true, false); }
    
    virtual PBoolean SetPatch(
      OpalMediaPatch * patch  
    );

    OpalMediaPatchPtr GetPatch() const { return m_mediaPatch; }

    void AddFilter(
      const PNotifier & filter,   
      const OpalMediaFormat & stage = OpalMediaFormat() 
    ) const;

    bool RemoveFilter(
      const PNotifier & filter,   
      const OpalMediaFormat & stage = OpalMediaFormat() 
    ) const;

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

    P_DECLARE_BITWISE_ENUM(Details, 6,(
      DetailMinimum,
      DetailEOL, // end of line
      DetailNAT,
      DetailSecured,
      DetailFEC,
      DetailAudio,
      DetailAddresses
    ));
    virtual void PrintDetail(
      ostream & strm,
      const char * prefix = NULL,
      Details details = Details::All()
    ) const;

    virtual bool InternalUpdateMediaFormat(const OpalMediaFormat & mediaFormat);
    virtual bool InternalSetPaused(bool pause, bool fromUser, bool fromPatch);
    virtual bool InternalExecuteCommand(const OpalMediaCommand & command);

  protected:
    void IncrementTimestamp(PINDEX size);
    bool InternalWriteData(const BYTE * data, PINDEX length, PINDEX & written);
    OpalMediaPatchPtr InternalSetPatchPart1(OpalMediaPatch * newPatch);
    void InternalSetPatchPart2(const OpalMediaPatchPtr & oldPatch);
    virtual bool InternalSetJitterBuffer(const OpalJitterBuffer::Init & init) const;

    virtual void InternalClose() = 0;

    OpalConnection & connection;
    unsigned         sessionID;
    WORD             m_sequenceNumber;
    PString          identifier;
    OpalMediaFormat  mediaFormat;
    bool             m_paused;
    bool             m_isSource;
    bool             m_isOpen;
    PINDEX           m_defaultDataSize;
    unsigned         timestamp;
    bool             marker;

    OpalMediaPatchPtr m_mediaPatch;

    RTP_DataFrame::PayloadTypes m_payloadType;
    unsigned                    m_frameTime;
    PINDEX                      m_frameSize;

    typedef OpalMediaPatchPtr PatchPtr; // For backward compatibility

  private:
    P_REMOVE_VIRTUAL_VOID(OnPatchStart());
    P_REMOVE_VIRTUAL_VOID(OnPatchStop());
    P_REMOVE_VIRTUAL_VOID(OnStopMediaPatch());
    P_REMOVE_VIRTUAL_VOID(RemovePatch(OpalMediaPatch *));

  friend class OpalMediaPatch;
};

typedef PSafePtr<OpalMediaStream> OpalMediaStreamPtr;


class OpalMediaStreamPacing
{
  public:
    OpalMediaStreamPacing(
      const OpalMediaFormat & mediaFormat 
    );

    void Pace(
      bool reading,     
      PINDEX bytes,     
      bool & marker     
    );

    bool UpdateMediaFormat(
      const OpalMediaFormat & mediaFormat   
    );

  protected:
    bool           m_timeOnMarkers;
    unsigned       m_frameTime;
    PINDEX         m_frameSize;
    unsigned       m_timeUnits;
    PAdaptiveDelay m_delay;
};


class OpalNullMediaStream : public OpalMediaStream, public OpalMediaStreamPacing
{
    PCLASSINFO(OpalNullMediaStream, OpalMediaStream);
  public:
    OpalNullMediaStream(
      OpalConnection & conn,               
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      bool isSource,                       
      bool isSynchronous = false           
    );
    OpalNullMediaStream(
      OpalConnection & conn,               
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      bool isSource,                       
      bool usePacingDelay,                 
      bool requiresPatchThread             
    );

    virtual PBoolean ReadData(
      BYTE * data,      
      PINDEX size,      
      PINDEX & length   
    );

    virtual PBoolean WriteData(
      const BYTE * data,   
      PINDEX length,       
      PINDEX & written     
    );
        
    virtual PBoolean RequiresPatchThread() const;

    virtual PBoolean IsSynchronous() const;

  protected:
    virtual void InternalClose() { }
    virtual bool InternalUpdateMediaFormat(const OpalMediaFormat & newMediaFormat);
    virtual bool InternalSetPaused(bool pause, bool fromUser, bool fromPatch);

    bool m_isSynchronous;
    bool m_requiresPatchThread;
};


class OpalRTPMediaStream : public OpalMediaStream
{
    PCLASSINFO(OpalRTPMediaStream, OpalMediaStream);
  public:
    OpalRTPMediaStream(
      OpalRTPConnection & conn,            
      const OpalMediaFormat & mediaFormat, 
      bool isSource,                       
      OpalRTPSession & rtpSession          
    );

    ~OpalRTPMediaStream();

    virtual PBoolean Open();

    virtual bool IsOpen() const;

    virtual PBoolean ReadPacket(
      RTP_DataFrame & packet
    );

    virtual PBoolean WritePacket(
      RTP_DataFrame & packet
    );

    virtual PBoolean SetDataSize(
      PINDEX dataSize,  
      PINDEX frameTime  
    );

    virtual PBoolean IsSynchronous() const;

    virtual PBoolean RequiresPatchThread() const;

    virtual PBoolean SetPatch(
      OpalMediaPatch * patch  
    );

    virtual OpalRTPSession & GetRtpSession() const
    { return rtpSession; }

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


  protected:
    virtual void InternalClose();
    virtual bool InternalSetJitterBuffer(const OpalJitterBuffer::Init & init) const;
    virtual bool InternalSetPaused(bool pause, bool fromUser, bool fromPatch);

    OpalRTPSession & rtpSession;
#if OPAL_VIDEO
    bool             m_forceIntraFrameFlag;
    PSimpleTimer     m_forceIntraFrameTimer;
#endif
};



class OpalRawMediaStream : public OpalMediaStream
{
    PCLASSINFO(OpalRawMediaStream, OpalMediaStream);
  protected:
    OpalRawMediaStream(
      OpalConnection & conn,               
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      bool isSource,                       
      PChannel * channel,                  
      bool autoDelete                      
    );

    ~OpalRawMediaStream();

  public:
    virtual PBoolean ReadData(
      BYTE * data,      
      PINDEX size,      
      PINDEX & length   
    );

    virtual PBoolean WriteData(
      const BYTE * data,   
      PINDEX length,       
      PINDEX & written     
    );

    PChannel * GetChannel() { return m_channel; }

    bool SetChannel(
      PChannel * channel,     
      bool autoDelete = true  
    );

    virtual unsigned GetAverageSignalLevel();

  protected:
    virtual void InternalClose();

    PChannel * m_channel;
    bool       m_autoDelete;
    PMutex     m_channelMutex;

    PBYTEArray m_silence;

    PUInt64    m_averageSignalSum;
    unsigned   m_averageSignalSamples;
    PMutex     m_averagingMutex;

    void CollectAverage(const BYTE * buffer, PINDEX size);
};



class OpalFileMediaStream : public OpalRawMediaStream, public OpalMediaStreamPacing
{
    PCLASSINFO(OpalFileMediaStream, OpalRawMediaStream);
  public:
    OpalFileMediaStream(
      OpalConnection & conn,               
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      bool isSource,                       
      PFile * file,                        
      bool autoDelete = true               
    );

    OpalFileMediaStream(
      OpalConnection & conn,               
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      bool isSource,                       
      const PFilePath & path               
    );

    virtual PBoolean IsSynchronous() const;

    virtual PBoolean ReadData(
      BYTE * data,      
      PINDEX size,      
      PINDEX & length   
    );

    virtual PBoolean WriteData(
      const BYTE * data,   
      PINDEX length,       
      PINDEX & written     
    );

  protected:
    PFile file;
};


#if OPAL_PTLIB_AUDIO

class PSoundChannel;

class OpalAudioMediaStream : public OpalRawMediaStream
{
    PCLASSINFO(OpalAudioMediaStream, OpalRawMediaStream);
  public:
    OpalAudioMediaStream(
      OpalConnection & conn,               
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      bool isSource,                       
      PINDEX buffers,                      
      unsigned bufferTime,                 
      PSoundChannel * channel,             
      bool autoDelete = true               
    );

    OpalAudioMediaStream(
      OpalConnection & conn,               
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      bool isSource,                       
      PINDEX buffers,                      
      unsigned bufferTime,                 
      const PString & deviceName           
    );

    virtual PBoolean SetDataSize(
      PINDEX dataSize,  
      PINDEX frameTime  
    );

    virtual PBoolean IsSynchronous() const;

  protected:
    PINDEX   m_soundChannelBuffers;
    unsigned m_soundChannelBufferTime;
};

#endif // OPAL_PTLIB_AUDIO

#if OPAL_VIDEO

class PVideoInputDevice;
class PVideoOutputDevice;

class OpalVideoMediaStream : public OpalMediaStream
{
    PCLASSINFO(OpalVideoMediaStream, OpalMediaStream);
  public:
    OpalVideoMediaStream(
      OpalConnection & conn,               
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      PVideoInputDevice * inputDevice,     
      PVideoOutputDevice * outputDevice,   
      bool autoDeleteInput = true,         
      bool autoDeleteOutput = true         
    );

    ~OpalVideoMediaStream();

    virtual PBoolean Open();

    virtual PBoolean ReadData(
      BYTE * data,      
      PINDEX size,      
      PINDEX & length   
    );

    virtual PBoolean WriteData(
      const BYTE * data,   
      PINDEX length,       
      PINDEX & written     
    );

    virtual PBoolean IsSynchronous() const;

    virtual PBoolean SetDataSize(
      PINDEX dataSize,  
      PINDEX frameTime  
    );

    virtual void SetVideoInputDevice(
      PVideoInputDevice * device,
      bool autoDelete = true
    );

    virtual PVideoInputDevice * GetVideoInputDevice() const
    {
      return m_inputDevice;
    }

    virtual void SetVideoOutputDevice(
      PVideoOutputDevice * device,
      bool autoDelete = true
    );

    virtual PVideoOutputDevice * GetVideoOutputDevice() const
    {
      return m_outputDevice;
    }


  protected:
    virtual void InternalClose();
    virtual bool InternalUpdateMediaFormat(const OpalMediaFormat & newMediaFormat);
    virtual bool InternalExecuteCommand(const OpalMediaCommand & command);
    bool InternalAdjustDevices();

    PVideoInputDevice  * m_inputDevice;
    PVideoOutputDevice * m_outputDevice;
    bool                 m_autoDeleteInput;
    bool                 m_autoDeleteOutput;
    PTimeInterval        m_lastGrabTime;
    bool                 m_needKeyFrame;
    PMutex               m_devicesMutex;
};

#endif // OPAL_VIDEO

class OpalTransportUDP;

class OpalUDPMediaStream : public OpalMediaStream
{
    PCLASSINFO(OpalUDPMediaStream, OpalMediaStream);
  public:
    OpalUDPMediaStream(
      OpalConnection & conn,               
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      bool isSource,                       
      OpalTransportUDP & transport         
    );

    ~OpalUDPMediaStream();


    virtual PBoolean ReadPacket(
      RTP_DataFrame & packet
    );

    virtual PBoolean WritePacket(
      RTP_DataFrame & packet
    );

    virtual PBoolean IsSynchronous() const;

  private:
    virtual void InternalClose();

    OpalTransportUDP & udpTransport;
};


#endif //OPAL_OPAL_MEDIASTRM_H


// End of File ///////////////////////////////////////////////////////////////