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): ______________________________________.
 *
 * $Log: mediastrm.h,v $
 * Revision 2.48  2007/09/26 03:45:38  rjongbloed
 * Added missing const in member variable access function.
 *
 * Revision 2.47  2007/09/05 13:23:39  csoutheren
 * Applied 1704162 - Opal mediastrm.cxx added IsOpen check to SetPatch
 * Thanks to Drazen Dimoti
 *
 * Revision 2.46  2007/05/16 10:45:17  dsandras
 * Added 2 new functions to the API thanks to Matthias Schneider <ma30002000
 * yahoo de>. Thanks!
 *
 * Revision 2.45  2007/05/09 01:39:19  csoutheren
 * Remove redundant patch for NULL source streams
 *
 * Revision 2.44  2007/05/02 04:13:21  csoutheren
 * Add delay to OpalFileMediaStream::ReadData and OpalFileMediaStream::WriteData
 *
 * Revision 2.43  2007/04/26 07:01:01  csoutheren
 * Add extra code to deal with getting media formats from connections early enough to do proper
 * gatewaying between calls. The SIP and H.323 code need to have the handing of the remote
 * and local formats standardized, but this will do for now
 *
 * Revision 2.42  2007/04/19 06:34:12  csoutheren
 * Applied 1703206 - OpalVideoFastUpdatePicture over SIP
 * Thanks to Josh Mahonin
 *
 * Revision 2.41  2007/03/29 05:15:48  csoutheren
 * Pass OpalConnection to OpalMediaSream constructor
 * Add ID to OpalMediaStreams so that transcoders can match incoming and outgoing codecs
 *
 * Revision 2.40  2007/01/25 11:48:11  hfriederich
 * OpalMediaPatch code refactorization.
 * Split into OpalMediaPatch (using a thread) and OpalPassiveMediaPatch
 * (not using a thread). Also adds the possibility for source streams
 * to push frames down to the sink streams instead of having a patch
 * thread around.
 *
 * Revision 2.39  2006/12/08 05:39:29  csoutheren
 * Remove warnings under Windows
 *
 * Revision 2.38  2006/12/08 05:13:10  csoutheren
 * Applied 1603783 - To allow media streams to handle more then one patch
 * Thanks to jmatela
 *
 * Revision 2.37  2006/10/11 01:15:15  csoutheren
 * Applied 1552449 - Always use max RTP buffer size
 * Thanks to Simon Zwahlen
 *
 * Revision 2.36  2006/10/10 07:18:18  csoutheren
 * Allow compilation with and without various options
 *
 * Revision 2.35  2006/08/29 08:47:43  rjongbloed
 * Added functions to get average audio signal level from audio streams in
 *   suitable connection types.
 *
 * Revision 2.34  2006/08/28 00:06:10  csoutheren
 * Applied 1545107 - MediaStream - safe access to patch for adding a filter
 * Thanks to Drazen Dimoti
 *
 * Revision 2.33  2006/08/26 08:19:52  hfriederich
 * Add getter method for the RTP Session
 *
 * Revision 2.32  2006/07/14 05:24:49  csoutheren
 * Applied 1509232 - Fix for a bug in OpalMediaPatch::Close method
 * Thanks to Borko Jandras
 *
 * Revision 2.31  2006/07/14 04:22:42  csoutheren
 * Applied 1517397 - More Phobos stability fix
 * Thanks to Dinis Rosario
 *
 * Revision 2.30  2006/07/09 10:18:28  csoutheren
 * Applied 1517393 - Opal T.38
 * Thanks to Drazen Dimoti
 *
 * Revision 2.29  2006/06/21 04:54:15  csoutheren
 * Fixed build with latest PWLib
 *
 * Revision 2.28  2005/11/30 13:35:26  csoutheren
 * Changed tags for Doxygen
 *
 * Revision 2.27  2005/09/04 06:23:38  rjongbloed
 * Added OpalMediaCommand mechanism (via PNotifier) for media streams
 *   and media transcoders to send commands back to remote.
 *
 * Revision 2.26  2005/08/31 13:19:25  rjongbloed
 * Added mechanism for controlling media (especially codecs) including
 *   changing the OpalMediaFormat option list (eg bit rate) and a completely
 *   new OpalMediaCommand abstraction for things like video fast update.
 *
 * Revision 2.25  2005/08/20 07:35:22  rjongbloed
 * Set video RTP timestamps to value dirived from real time clock.
 *
 * Revision 2.24  2005/08/04 17:23:38  dsandras
 * Added function to determine if a stream is open or not.
 *
 * Revision 2.23  2005/04/10 20:48:30  dsandras
 * Added functions to put an OpalMediaStream on pause.
 *
 * Revision 2.22  2005/03/12 00:33:27  csoutheren
 * Fixed problems with STL compatibility on MSVC 6
 * Fixed problems with video streams
 * Thanks to Adrian Sietsma
 *
 * Revision 2.21  2004/12/04 16:35:50  dsandras
 * Added a function to get the PChannel back from the OpalMediaStream.
 *
 * Revision 2.20  2004/10/02 11:50:54  rjongbloed
 * Fixed RTP media stream so assures RTP session is open before starting.
 *
 * Revision 2.19  2004/08/14 07:56:29  rjongbloed
 * Major revision to utilise the PSafeCollection classes for the connections and calls.
 *
 * Revision 2.18  2004/05/17 13:24:18  rjongbloed
 * Added silence suppression.
 *
 * Revision 2.17  2004/03/11 06:54:27  csoutheren
 * Added ability to disable SIP or H.323 stacks
 *
 * Revision 2.16  2003/06/02 02:57:10  rjongbloed
 * Moved LID specific media stream class to LID source file.
 *
 * Revision 2.15  2003/04/16 02:30:21  robertj
 * Fixed comments on ReadData() and WriteData() functions.
 *
 * Revision 2.14  2003/03/17 10:26:59  robertj
 * Added video support.
 *
 * Revision 2.13  2002/11/10 11:33:17  robertj
 * Updated to OpenH323 v1.10.3
 *
 * Revision 2.12  2002/09/16 02:52:35  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 2.11  2002/04/15 08:47:42  robertj
 * Fixed problem with mismatched payload type being propagated.
 * Fixed correct setting of jitter buffer size in RTP media stream.
 *
 * Revision 2.10  2002/02/13 02:33:29  robertj
 * Added ability for media patch (and transcoders) to handle multiple RTP frames.
 * Removed media stream being descended from PChannel, not really useful.
 *
 * Revision 2.9  2002/02/11 07:39:15  robertj
 * Added media bypass for streams between compatible protocols.
 *
 * Revision 2.8  2002/01/22 05:10:58  robertj
 * Removed redundant code
 *
 * Revision 2.7  2002/01/22 05:09:00  robertj
 * Removed payload mismatch detection from RTP media stream.
 * Added function to get media patch from media stream.
 *
 * Revision 2.6  2002/01/14 02:27:32  robertj
 * Added ability to turn jitter buffer off in media stream to allow for patches
 *   that do not require it.
 *
 * Revision 2.5  2001/10/15 04:28:35  robertj
 * Added delayed start of media patch threads.
 *
 * Revision 2.4  2001/10/04 05:44:00  craigs
 * Changed to start media patch threads in Paused state
 *
 * Revision 2.3  2001/10/04 00:41:20  robertj
 * Removed GetMediaFormats() function as is not useful.
 *
 * Revision 2.2  2001/08/21 01:10:35  robertj
 * Fixed propagation of sound channel buffers through media stream.
 *
 * Revision 2.1  2001/08/01 05:51:47  robertj
 * Made OpalMediaFormatList class global to help with documentation.
 *
 * Revision 2.0  2001/07/27 15:48:24  robertj
 * Conversion of OpenH323 to Open Phone Abstraction Library (OPAL)
 *
 */

#ifndef __OPAL_MEDIASTRM_H
#define __OPAL_MEDIASTRM_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <ptclib/delaychan.h>

#include <opal/buildopts.h>
#include <opal/mediafmt.h>
#include <opal/mediacmd.h>
#include <ptclib/guid.h>


class RTP_Session;
class OpalMediaPatch;
class OpalLine;
class OpalConnection;


class OpalMediaStream : public PObject
{
    PCLASSINFO(OpalMediaStream, PObject);
  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 UpdateMediaFormat(
      const OpalMediaFormat & mediaFormat  
    );

    virtual BOOL ExecuteCommand(
      const OpalMediaCommand & command    
    );

    virtual void SetCommandNotifier(
      const PNotifier & notifier    
    );

    virtual BOOL Open();

    virtual BOOL Start();

    virtual BOOL Close();
        
    virtual void OnPatchStart() {};

    virtual BOOL WritePackets(
      RTP_DataFrameList & packets
    );

    virtual BOOL ReadPacket(
      RTP_DataFrame & packet
    );

    virtual BOOL WritePacket(
      RTP_DataFrame & packet
    );

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

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

    BOOL PushPacket(
      RTP_DataFrame & packet
    );

    virtual BOOL SetDataSize(
      PINDEX dataSize  
    );

    PINDEX GetDataSize() const { return defaultDataSize; }

    virtual BOOL IsSynchronous() const = 0;
        
    virtual BOOL RequiresPatch() const;

    virtual BOOL RequiresPatchThread() const;

    virtual void EnableJitterBuffer() const;

    BOOL IsSource() const { return isSource; }

    BOOL IsSink() const { return !isSource; }

    unsigned GetSessionID() const { return sessionID; }

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

    void SetPaused(BOOL p) { paused = p; }

    BOOL IsOpen() { return isOpen; }
    
    virtual BOOL SetPatch(
      OpalMediaPatch * patch  
    );

    virtual void RemovePatch(OpalMediaPatch * patch);

    OpalMediaPatch * GetPatch() const { return mediaPatch; }

    void AddFilter(const PNotifier & Filter, const OpalMediaFormat & Stage =  OpalMediaFormat());

    BOOL RemoveFilter(const PNotifier & Filter, const OpalMediaFormat & Stage);


    PMutex &  GetDeleteMutex() const { return deleteMutex; }

    PString GetID() const
    { return id; }

    virtual BOOL IsNull() const
    { return FALSE; }

  protected:
    OpalMediaFormat mediaFormat;
    unsigned        sessionID;
    BOOL                  paused;
    BOOL            isSource;
    BOOL            isOpen;
    PINDEX          defaultDataSize;
    unsigned        timestamp;
    BOOL            marker;
    unsigned        mismatchedPayloadTypes;

    OpalMediaPatch * mediaPatch;
    PMutex           patchMutex;
    PNotifier        commandNotifier;

    mutable PMutex  deleteMutex;

    PString id;   
};

PLIST(OpalMediaStreamList, OpalMediaStream);


class OpalNullMediaStream : public OpalMediaStream
{
    PCLASSINFO(OpalNullMediaStream, OpalMediaStream);
  public:
    OpalNullMediaStream(
      OpalConnection & conn,
      const OpalMediaFormat & mediaFormat, 
      unsigned sessionID,                  
      BOOL isSource                        
    );

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

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

    virtual BOOL RequiresPatchThread() const;

    virtual BOOL IsSynchronous() const;

};


class OpalRTPMediaStream : public OpalMediaStream
{
    PCLASSINFO(OpalRTPMediaStream, OpalMediaStream);
  public:
    OpalRTPMediaStream(
      OpalConnection & conn,
      const OpalMediaFormat & mediaFormat, 
      BOOL isSource,                       
      RTP_Session & rtpSession,    
      unsigned minAudioJitterDelay,
      unsigned maxAudioJitterDelay 
    );

    virtual BOOL Open();

    virtual BOOL Close();

    virtual BOOL ReadPacket(
      RTP_DataFrame & packet
    );

    virtual BOOL WritePacket(
      RTP_DataFrame & packet
    );

    virtual BOOL SetDataSize(
      PINDEX dataSize  
    );

    virtual BOOL IsSynchronous() const;

    virtual void EnableJitterBuffer() const;

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

#if OPAL_VIDEO

    virtual void OnPatchStart();

    PDECLARE_NOTIFIER(OpalMediaCommand, OpalRTPMediaStream, OnMediaCommand);
#endif


  protected:
    RTP_Session & rtpSession;
    unsigned      minAudioJitterDelay;
    unsigned      maxAudioJitterDelay;
};



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 BOOL ReadData(
      BYTE * data,      
      PINDEX size,      
      PINDEX & length   
    );

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

    PChannel * GetChannel() { return channel; }
    
    virtual BOOL Close();

    virtual unsigned GetAverageSignalLevel();

  protected:
    PChannel * channel;
    PMutex     channel_mutex;
    BOOL       autoDelete;

    PUInt64    averageSignalSum;
    unsigned   averageSignalSamples;
    void CollectAverage(const BYTE * buffer, PINDEX size);
};



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

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

    virtual BOOL IsSynchronous() const;

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

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

  protected:
    PFile file;
    PAdaptiveDelay fileDelay;
};

#if OPAL_AUDIO
#if P_AUDIO

class PSoundChannel;

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

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

    virtual BOOL SetDataSize(
      PINDEX dataSize  
    );

    virtual BOOL IsSynchronous() const;

  protected:
    PINDEX soundChannelBuffers;
};

#endif

#endif // OPAL_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 autoDelete = TRUE               
    );

    ~OpalVideoMediaStream();

    virtual BOOL Open();

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

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

    virtual BOOL IsSynchronous() const;

    virtual BOOL SetDataSize(
     PINDEX dataSize  
    );

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

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


  protected:
    PVideoInputDevice  * inputDevice;
    PVideoOutputDevice * outputDevice;
    BOOL                 autoDelete;
    PTimeInterval        lastGrabTime;
};

#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         
    );


    virtual BOOL ReadPacket(
      RTP_DataFrame & packet
    );

    virtual BOOL WritePacket(
      RTP_DataFrame & packet
    );

    virtual BOOL IsSynchronous() const;

    virtual BOOL Close();


  private:
    OpalTransportUDP & udpTransport;
};

#endif //__OPAL_MEDIASTRM_H


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

---