mediafmt.h

Go to the documentation of this file.

/*
 * mediafmt.h
 *
 * Media Format descriptions
 *
 * 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 H323 Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): ______________________________________.
 *
 * $Revision: 32687 $
 * $Author: rjongbloed $
 * $Date: 2014-09-05 13:52:07 +1000 (Fri, 05 Sep 2014) $
 */

#ifndef OPAL_OPAL_MEDIAFMT_H
#define OPAL_OPAL_MEDIAFMT_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal_config.h>

#include <opal/mediatype.h>
#include <rtp/rtp.h>
#include <ptlib/bitwise_enum.h>

#if OPAL_VIDEO
#include <ptlib/videoio.h>
#endif

#include <limits>


class PluginCodec_OptionMap;
class OpalMediaFormat;
class H225_BandWidth;
class PASN_Integer;



class OpalBandwidth {
  public:
    enum Direction {
      Rx = 1,
      Tx,
      RxTx,
      TxRx = RxTx
    };
    friend std::ostream & operator<<(std::ostream & strm, OpalBandwidth::Direction dir);

    typedef unsigned int_type;

    __inline OpalBandwidth(int_type bps = 0) : m_bps(bps) { }
    __inline OpalBandwidth & operator=(int_type bps) { m_bps = bps; return *this; }
    __inline operator int_type() const { return m_bps; }

    OpalBandwidth(const PString & str);

    __inline OpalBandwidth   operator+ (const OpalBandwidth & bw) const { return OpalBandwidth(m_bps + bw.m_bps); }
    __inline OpalBandwidth   operator- (const OpalBandwidth & bw) const { return OpalBandwidth(m_bps - bw.m_bps); }
    __inline OpalBandwidth & operator+=(const OpalBandwidth & bw)       { m_bps += bw.m_bps; return *this; }
    __inline OpalBandwidth & operator-=(const OpalBandwidth & bw)       { m_bps += bw.m_bps; return *this; }
    __inline OpalBandwidth & operator&=(const OpalBandwidth & bw)       { if (m_bps > bw.m_bps) m_bps = bw.m_bps; return *this; }

    friend std::ostream & operator<<(std::ostream & strm, const OpalBandwidth & bw);
    friend std::istream & operator>>(std::istream & strm, OpalBandwidth & bw);

#if OPAL_H323
    OpalBandwidth(const H225_BandWidth & bw);
    OpalBandwidth & operator=(const H225_BandWidth & bw);
    void SetH225(H225_BandWidth & bw) const;
    void SetH245(PASN_Integer & bitRate) const;
    void FromH245(const PASN_Integer & bitRate);
#endif
    unsigned kbps() const { return (m_bps+999)/1000; }

    static OpalBandwidth Max() { return OpalBandwidth(UINT_MAX); }

  protected:
    int_type m_bps;
};



PLIST(OpalMediaFormatBaseList, OpalMediaFormat);

class OpalMediaFormatList : public OpalMediaFormatBaseList
{
  PCLASSINFO(OpalMediaFormatList, OpalMediaFormatBaseList);
  public:
    OpalMediaFormatList();

    OpalMediaFormatList(
      const OpalMediaFormat & format    
    );

    OpalMediaFormatList(const OpalMediaFormatList & l) : OpalMediaFormatBaseList(l) { }

    OpalMediaFormatList & operator+=(
      const char * wildcard    
    ) { PConstString w(wildcard); return operator+=(w); }

    OpalMediaFormatList & operator+=(
      const PString & wildcard    
    );

    OpalMediaFormatList & operator+=(
      const OpalMediaFormat & format    
    );

    OpalMediaFormatList & operator+=(
      const OpalMediaFormatList & formats    
    );

    OpalMediaFormatList & operator-=(
      const OpalMediaFormat & format    
    );

    OpalMediaFormatList & operator-=(
      const OpalMediaFormatList & formats    
    );

    const_iterator FindFormat(
      RTP_DataFrame::PayloadTypes rtpPayloadType, 
      const unsigned clockRate = 0,               
      const char * rtpEncodingName = NULL,        
      const char * protocol = NULL,               
      const_iterator start = const_iterator()     
    ) const;

    const_iterator FindFormat(
      const PString & wildcard,    
      const_iterator start = const_iterator() 
    ) const;

    PBoolean HasFormat(
      RTP_DataFrame::PayloadTypes rtpPayloadType 
    ) const { return FindFormat(rtpPayloadType) != end(); }

    PBoolean HasFormat(
      const PString & wildcard    
    ) const { return FindFormat(wildcard) != end(); }

    bool HasType(
      const OpalMediaType & type,
      bool mustBeTransportable = true
    ) const;

    OpalMediaTypeList GetMediaTypes() const;

    void Reorder(
      const PStringArray & order
    );

    void Remove(
      const PStringArray & mask
    );

    void RemoveNonTransportable();

  private:
    virtual PINDEX Append(PObject *) { return P_MAX_INDEX; }
    virtual PINDEX Insert(const PObject &, PObject *) { return P_MAX_INDEX; }
};



class OpalMediaOption : public PObject
{
    PCLASSINFO(OpalMediaOption, PObject);
  public:
    // Note the below enum must be identical to PluginCodec_OptionMerge in opalplugin.h
    enum MergeType {
      NoMerge,
      MinMerge,
      MaxMerge,
      EqualMerge,
      NotEqualMerge,
      AlwaysMerge,
      CustomMerge,
      IntersectionMerge, // Set intersection, applies to numeric (bit wise AND) or string (common substrings)

      // Synonyms
      AndMerge = MinMerge,  // Applies to Boolean option or Enum with two elements
      OrMerge  = MaxMerge   // Applies to Boolean option or Enum with two elements
    };

  protected:
    OpalMediaOption(
      const PString & name
    );
    OpalMediaOption(
      const char * name,
      bool readOnly,
      MergeType merge
    );

  public:
    virtual Comparison Compare(const PObject & obj) const;

    virtual bool Merge(
      const OpalMediaOption & option
    );

    virtual bool ValidateMerge(
      const OpalMediaOption & option
    ) const;

    virtual Comparison CompareValue(
      const OpalMediaOption & option
    ) const = 0;
    virtual void Assign(
      const OpalMediaOption & option
    ) = 0;

    PString AsString() const;
    bool FromString(const PString & value);

    const PString & GetName() const { return m_name; }

    bool IsReadOnly() const { return m_readOnly; }
    void SetReadOnly(bool readOnly) { m_readOnly = readOnly; }

    MergeType GetMerge() const { return m_merge; }
    void SetMerge(MergeType merge) { m_merge = merge; }

#if OPAL_SIP
    const PString & GetFMTPName() const { return m_FMTPName; }
    void SetFMTPName(const char * name) { m_FMTPName = name; }

    const PString & GetFMTPDefault() const { return m_FMTPDefault; }
    void SetFMTPDefault(const char * value) { m_FMTPDefault = value; }

    void SetFMTP(const char * name, const char * dflt)
    {
      m_FMTPName = name;
      m_FMTPDefault = dflt;
    }
#define OPAL_SET_MEDIA_OPTION_FMTP(opt, name, dflt) (opt)->SetFMTP(name, dflt)
#else
#define OPAL_SET_MEDIA_OPTION_FMTP(opt, name, dflt)
#endif // OPAL_SIP

#if OPAL_H323
    struct H245GenericInfo {
      H245GenericInfo();
      H245GenericInfo(
        unsigned mask,
        const char * dflt = NULL
      );

      unsigned ordinal;

      enum Modes {
        None,
        Collapsing,
        NonCollapsing
      } mode;

      enum IntegerTypes {
        UnsignedInt,
        Unsigned32,
        BooleanArray
      } integerType;

      bool    excludeTCS;
      bool    excludeOLC;
      bool    excludeReqMode;
      int     position;     // Position in sequence for parameter
      PString defaultValue; // Do not include parameter if this value
    };

    const H245GenericInfo & GetH245Generic() const { return m_H245Generic; }
    void SetH245Generic(const H245GenericInfo & genericInfo) { m_H245Generic = genericInfo; }
#define OPAL_SET_MEDIA_OPTION_H245(opt, ...) (opt)->SetH245Generic(OpalMediaOption::H245GenericInfo(__VA_ARGS__))
#else
#define OPAL_SET_MEDIA_OPTION_H245(opt, ...)
#endif // OPAL_H323

  protected:
    PCaselessString m_name;
    bool            m_readOnly;
    MergeType       m_merge;

#if OPAL_SIP
    PCaselessString m_FMTPName;
    PString         m_FMTPDefault;
#endif // OPAL_SIP

#if OPAL_H323
    H245GenericInfo m_H245Generic;
#endif // OPAL_H323
};


template <typename T>
class OpalMediaOptionValue : public OpalMediaOption
{
    PCLASSINFO(OpalMediaOptionValue, OpalMediaOption);
  public:
    OpalMediaOptionValue(
      const char * name,
      bool readOnly,
      OpalMediaOption::MergeType merge = OpalMediaOption::MinMerge,
      T value = T()
    )
      : OpalMediaOption(name, readOnly, merge)
      , m_value(value)
    {
    }

    virtual PObject * Clone() const
    {
      return new OpalMediaOptionValue(*this);
    }

    virtual void PrintOn(ostream & strm) const
    {
      strm << m_value;
    }

    virtual void ReadFrom(istream & strm)
    {
      strm >> m_value;
    }

    virtual bool Merge(const OpalMediaOption & option)
    {
      if (m_merge != IntersectionMerge)
        return OpalMediaOption::Merge(option);

      const OpalMediaOptionValue * otherOption = PDownCast(const OpalMediaOptionValue, &option);
      if (otherOption == NULL)
        return false;

      m_value &= otherOption->m_value;
      return true;
    }

    virtual Comparison CompareValue(const OpalMediaOption & option) const
    {
      const OpalMediaOptionValue * otherOption = PDownCast(const OpalMediaOptionValue, &option);
      if (otherOption == NULL)
        return GreaterThan;
      if (m_value < otherOption->m_value)
        return LessThan;
      if (m_value > otherOption->m_value)
        return GreaterThan;
      return EqualTo;
    }

    virtual void Assign(const OpalMediaOption & option)
    {
      const OpalMediaOptionValue * otherOption = PDownCast(const OpalMediaOptionValue, &option);
      if (otherOption != NULL)
        m_value = otherOption->m_value;
    }

    T GetValue() const
    {
      return m_value;
    }

    void SetValue(T value)
    {
      m_value = value;
    }

  protected:
    T m_value;
};


template <typename T>
class OpalMediaOptionNumericalValue : public OpalMediaOptionValue<T>
{
    typedef OpalMediaOptionValue<T> BaseClass;
    PCLASSINFO(OpalMediaOptionNumericalValue, BaseClass);
  public:
    OpalMediaOptionNumericalValue(
      const char * name,
      bool readOnly,
      OpalMediaOption::MergeType merge = OpalMediaOption::MinMerge,
      T value = 0,
      T minimum = std::numeric_limits<T>::min(),
      T maximum = std::numeric_limits<T>::max()
    )
      : BaseClass(name, readOnly, merge, value)
      , m_minimum(minimum)
      , m_maximum(maximum)
    {
    }

    virtual PObject * Clone() const
    {
      return new OpalMediaOptionNumericalValue(*this);
    }

    virtual void ReadFrom(istream & strm)
    {
      T temp = 0;
      strm >> temp;
      if (strm.fail())
        return;
      if (temp >= m_minimum && temp <= m_maximum)
        this->m_value = temp;
      else
        strm.setstate(ios::badbit);
    }

    void SetValue(T value)
    {
      if (value < m_minimum)
        this->m_value = m_minimum;
      else if (value > m_maximum)
        this->m_value = m_maximum;
      else
        this->m_value = value;
    }

    void SetMinimum(T m)
    {
      this->m_minimum = m;
    }

    void SetMaximum(T m)
    {
      this->m_maximum = m;
    }

  protected:
    T m_minimum;
    T m_maximum;
};


typedef OpalMediaOptionNumericalValue<bool>     OpalMediaOptionBoolean;
typedef OpalMediaOptionNumericalValue<int>      OpalMediaOptionInteger;
typedef OpalMediaOptionNumericalValue<unsigned> OpalMediaOptionUnsigned;

// Wrapper class so we can implement intersection (&= operator) for floating point
class OpalMediaOptionRealValue
{
    double m_value;
  public:
    OpalMediaOptionRealValue(double value = 0) : m_value(value) { }
    operator double() const { return m_value; }
    void operator&=(double other) { if (m_value > other) m_value = other; }
    friend ostream & operator<<(ostream & strm, const OpalMediaOptionRealValue & value) { return strm << value.m_value; }
    friend istream & operator>>(istream & strm,       OpalMediaOptionRealValue & value) { return strm >> value.m_value; }
};

typedef OpalMediaOptionNumericalValue<OpalMediaOptionRealValue> OpalMediaOptionReal;


class OpalMediaOptionEnum : public OpalMediaOption
{
    PCLASSINFO(OpalMediaOptionEnum, OpalMediaOption);
  public:
    OpalMediaOptionEnum(
      const char * name,
      bool readOnly
    );
    OpalMediaOptionEnum(
      const char * name,
      bool readOnly,
      const char * const * enumerations,
      PINDEX count,
      MergeType merge = EqualMerge,
      PINDEX value = 0
    );

    virtual PObject * Clone() const;
    virtual void PrintOn(ostream & strm) const;
    virtual void ReadFrom(istream & strm);

    virtual bool Merge(const OpalMediaOption & option);
    virtual Comparison CompareValue(const OpalMediaOption & option) const;
    virtual void Assign(const OpalMediaOption & option);

    PINDEX GetValue() const { return m_value; }
    void SetValue(PINDEX value);

    const PStringArray & GetEnumerations() const { return m_enumerations; }
    void SetEnumerations(const PStringArray & e)
    {
      m_enumerations = e;
    }

  protected:
    PStringArray m_enumerations;
    PINDEX       m_value;
};


class OpalMediaOptionString : public OpalMediaOption
{
    PCLASSINFO(OpalMediaOptionString, OpalMediaOption);
  public:
    OpalMediaOptionString(
      const char * name,
      bool readOnly
    );
    OpalMediaOptionString(
      const char * name,
      bool readOnly,
      const PString & value
    );

    virtual PObject * Clone() const;
    virtual void PrintOn(ostream & strm) const;
    virtual void ReadFrom(istream & strm);

    virtual bool Merge(const OpalMediaOption & option);
    virtual Comparison CompareValue(const OpalMediaOption & option) const;
    virtual void Assign(const OpalMediaOption & option);

    const PString & GetValue() const { return m_value; }
    void SetValue(const PString & value);

  protected:
    PString m_value;
};


class OpalMediaOptionOctets : public OpalMediaOption
{
    PCLASSINFO(OpalMediaOptionOctets, OpalMediaOption);
  public:
    OpalMediaOptionOctets(
      const char * name,
      bool readOnly,
      bool base64 = false
    );
    OpalMediaOptionOctets(
      const char * name,
      bool readOnly,
      bool base64,
      const PBYTEArray & value
    );
    OpalMediaOptionOctets(
      const char * name,
      bool readOnly,
      bool base64,
      const BYTE * data,
      PINDEX length
    );

    virtual PObject * Clone() const;
    virtual void PrintOn(ostream & strm) const;
    virtual void ReadFrom(istream & strm);

    virtual Comparison CompareValue(const OpalMediaOption & option) const;
    virtual void Assign(const OpalMediaOption & option);

    const PBYTEArray & GetValue() const { return m_value; }
    void SetValue(const PBYTEArray & value);
    void SetValue(const BYTE * data, PINDEX length);

    void SetBase64(bool b)
    {
      m_base64 = b;
    }

  protected:
    PBYTEArray m_value;
    bool       m_base64;
};



class OpalMediaFormatInternal : public PObject
{
    PCLASSINFO(OpalMediaFormatInternal, PObject);
  public:
    OpalMediaFormatInternal(
      const char  * fullName,
      const OpalMediaType & mediaType,
      RTP_DataFrame::PayloadTypes rtpPayloadType,
      const char  * encodingName,
      bool          needsJitter,
      OpalBandwidth bandwidth,
      PINDEX        frameSize,
      unsigned      frameTime,
      unsigned      clockRate,
      time_t        timeStamp
    );

    const PCaselessString & GetName() const { return formatName; }

    virtual PObject * Clone() const;
    virtual void PrintOn(ostream & strm) const;

    virtual bool IsValid() const;
    virtual bool IsTransportable() const;

    virtual PStringToString GetOptions() const;
    virtual bool GetOptionValue(const PString & name, PString & value) const;
    virtual bool SetOptionValue(const PString & name, const PString & value);
    virtual bool GetOptionBoolean(const PString & name, bool dflt) const;
    virtual bool SetOptionBoolean(const PString & name, bool value);
    virtual int GetOptionInteger(const PString & name, int dflt) const;
    virtual bool SetOptionInteger(const PString & name, int value);
    virtual double GetOptionReal(const PString & name, double dflt) const;
    virtual bool SetOptionReal(const PString & name, double value);
    virtual PINDEX GetOptionEnum(const PString & name, PINDEX dflt) const;
    virtual bool SetOptionEnum(const PString & name, PINDEX value);
    virtual PString GetOptionString(const PString & name, const PString & dflt) const;
    virtual bool SetOptionString(const PString & name, const PString & value);
    virtual bool GetOptionOctets(const PString & name, PBYTEArray & octets) const;
    virtual bool SetOptionOctets(const PString & name, const PBYTEArray & octets);
    virtual bool SetOptionOctets(const PString & name, const BYTE * data, PINDEX length);
    virtual bool AddOption(OpalMediaOption * option, PBoolean overwrite = false);
    virtual OpalMediaOption * FindOption(const PString & name) const;

    virtual bool ToNormalisedOptions();
    virtual bool ToCustomisedOptions();
    virtual bool Merge(const OpalMediaFormatInternal & mediaFormat);

    virtual bool ValidateMerge(const OpalMediaFormatInternal & mediaFormat) const;

    virtual bool IsValidForProtocol(const PString & protocol) const;

  protected:
    bool AdjustByOptionMaps(
      PTRACE_PARAM(const char * operation,)
      bool (*adjuster)(PluginCodec_OptionMap & original, PluginCodec_OptionMap & changed)
    );

    PCaselessString              formatName;
    RTP_DataFrame::PayloadTypes  rtpPayloadType;
    PCaselessString              rtpEncodingName;
    OpalMediaType                mediaType;
    PMutex                       media_format_mutex;
    PSortedList<OpalMediaOption> options;
    time_t                       codecVersionTime;
    bool                         forceIsTransportable;

  friend bool operator==(const char * other, const OpalMediaFormat & fmt);
  friend bool operator!=(const char * other, const OpalMediaFormat & fmt);
  friend bool operator==(const PString & other, const OpalMediaFormat & fmt);
  friend bool operator!=(const PString & other, const OpalMediaFormat & fmt);

  friend class OpalMediaFormat;
  friend class OpalMediaFormatList;
  friend class OpalAudioFormatInternal;
};



class OpalMediaFormat : public PContainer
{
    PCLASSINFO(OpalMediaFormat, PContainer)
  public:
    OpalMediaFormat(const OpalMediaFormat & c);
    virtual ~OpalMediaFormat();
    OpalMediaFormat & operator=(const OpalMediaFormat & c)     { AssignContents(c); return *this; }
    virtual PBoolean MakeUnique();
  protected:
    virtual void DestroyContents();
    virtual void AssignContents(const PContainer & c);

  public:
    OpalMediaFormat(
      OpalMediaFormatInternal * info = NULL
    );

    OpalMediaFormat(
      const char * fullName,                      
      const OpalMediaType & mediaType,            
      RTP_DataFrame::PayloadTypes rtpPayloadType, 
      const char * encodingName,                  
      PBoolean     needsJitter,                   
      OpalBandwidth bandwidth,                    
      PINDEX   frameSize,                         
      unsigned frameTime,                         
      unsigned clockRate,                         
      time_t timeStamp = 0                        
    );

    OpalMediaFormat(
      RTP_DataFrame::PayloadTypes rtpPayloadType, 
      unsigned clockRate,                         
      const char * rtpEncodingName = NULL,        
      const char * protocol = NULL                
    );

    OpalMediaFormat(
      const char * wildcard  
    );

    OpalMediaFormat(
      const PString & wildcard  
    );
    
    OpalMediaFormat & operator=(
      RTP_DataFrame::PayloadTypes rtpPayloadType 
    );

    OpalMediaFormat & operator=(
      const char * wildcard  
    );

    OpalMediaFormat & operator=(
      const PString & wildcard  
    );

    virtual PObject * Clone() const;

    virtual Comparison Compare(const PObject & obj) const;

    virtual void PrintOn(ostream & strm) const;

    virtual void ReadFrom(istream & strm);

    bool ToNormalisedOptions();

    bool ToCustomisedOptions();

    bool Update(
      const OpalMediaFormat & mediaFormat
    );

    bool Merge(
      const OpalMediaFormat & mediaFormat,
      bool copyPayloadType = false
    );
    bool ValidateMerge(
      const OpalMediaFormat & mediaFormat
    ) const;

    PString GetName() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? "" : m_info->formatName; }

    PString GetDescription() const { return GetOptionString(DescriptionOption()); }
    static const PString & DescriptionOption();

    PBoolean IsValid() const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->IsValid(); }

    PBoolean IsTransportable() const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->IsTransportable(); }

    RTP_DataFrame::PayloadTypes GetPayloadType() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? RTP_DataFrame::IllegalPayloadType : m_info->rtpPayloadType; }
    void SetPayloadType(RTP_DataFrame::PayloadTypes type) { PWaitAndSignal m(m_mutex); MakeUnique(); if (m_info != NULL) m_info->rtpPayloadType = type; }

    const char * GetEncodingName() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? "" : (const char *)m_info->rtpEncodingName; }

    OpalMediaType GetMediaType() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? OpalMediaType() : m_info->mediaType; }

    bool IsMediaType(const OpalMediaType & mediaType) const;

    bool NeedsJitterBuffer() const { return GetOptionBoolean(NeedsJitterOption()); }
    static const PString & NeedsJitterOption();

    OpalBandwidth GetMaxBandwidth() const { return GetOptionInteger(MaxBitRateOption()); }
    static const PString & MaxBitRateOption();

    OpalBandwidth GetUsedBandwidth() const { return GetOptionInteger(TargetBitRateOption(), GetOptionInteger(MaxBitRateOption())); }
    static const PString & TargetBitRateOption();

    PINDEX GetFrameSize() const { return GetOptionInteger(MaxFrameSizeOption()); }
    static const PString & MaxFrameSizeOption();

    unsigned GetFrameTime() const { return GetOptionInteger(FrameTimeOption()); }
    static const PString & FrameTimeOption();

    unsigned GetTimeUnits() const { return GetClockRate()/1000; }

    enum StandardClockRate {
      AudioClockRate = 8000,  
      VideoClockRate = 90000  
    };

    unsigned GetClockRate() const { return GetOptionInteger(ClockRateOption(), AudioClockRate); }
    static const PString & ClockRateOption();

    static const PString & ProtocolOption();

    static const PString & MaxTxPacketSizeOption();

    PStringToString GetOptions() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? PStringToString() : m_info->GetOptions(); }

    PINDEX GetOptionCount() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? 0 : m_info->options.GetSize(); }

    const OpalMediaOption & GetOption(
      PINDEX index   
    ) const { PWaitAndSignal m(m_mutex); return m_info->options[index]; }

    bool GetOptionValue(
      const PString & name,   
      PString & value         
    ) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->GetOptionValue(name, value); }

    bool SetOptionValue(
      const PString & name,   
      const PString & value   
    ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionValue(name, value); }

    bool GetOptionBoolean(
      const PString & name,   
      bool dflt = false       
    ) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->GetOptionBoolean(name, dflt); }

    bool SetOptionBoolean(
      const PString & name,   
      bool value              
    ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionBoolean(name, value); }

    int GetOptionInteger(
      const PString & name,   
      int dflt = 0            
    ) const { PWaitAndSignal m(m_mutex); return m_info == NULL ? dflt : m_info->GetOptionInteger(name, dflt); }

    bool SetOptionInteger(
      const PString & name,   
      int value               
    ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionInteger(name, value); }

    double GetOptionReal(
      const PString & name,   
      double dflt = 0         
    ) const { PWaitAndSignal m(m_mutex); return m_info == NULL ? dflt : m_info->GetOptionReal(name, dflt); }

    bool SetOptionReal(
      const PString & name,   
      double value            
    ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionReal(name, value); }

    template <typename Enum>
    Enum GetOptionEnum(
      const PString & name,   
      Enum dflt = (Enum)0     
    ) const { PWaitAndSignal m(m_mutex); return m_info == NULL ? dflt : (Enum)m_info->GetOptionEnum(name, dflt); }

    template <typename Enum>
    bool SetOptionEnum(
      const PString & name,   
      Enum value              
    ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionEnum(name, value); }

    PString GetOptionString(
      const PString & name,                   
      const PString & dflt = PString::Empty() 
    ) const { PWaitAndSignal m(m_mutex); return m_info == NULL ? dflt : m_info->GetOptionString(name, dflt); }

    bool SetOptionString(
      const PString & name,   
      const PString & value   
    ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionString(name, value); }

    bool GetOptionOctets(
      const PString & name, 
      PBYTEArray & octets   
    ) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->GetOptionOctets(name, octets); }

    bool SetOptionOctets(
      const PString & name,       
      const PBYTEArray & octets   
    ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionOctets(name, octets); }
    bool SetOptionOctets(
      const PString & name,       
      const BYTE * data,          
      PINDEX length               
    ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionOctets(name, data, length); }

    static OpalMediaFormatList GetAllRegisteredMediaFormats();
    static void GetAllRegisteredMediaFormats(
      OpalMediaFormatList & copy    
    );

    static bool RegisterKnownMediaFormats(
      const PString & name = PString::Empty() 
    );

    static bool SetRegisteredMediaFormat(
      const OpalMediaFormat & mediaFormat  
    );

    static bool RemoveRegisteredMediaFormat(
      const OpalMediaFormat & mediaFormat  
    );

    bool AddOption(
      OpalMediaOption * option,
      PBoolean overwrite = false
    ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->AddOption(option, overwrite); }

    bool HasOption(const PString & name) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->FindOption(name) != NULL; }

    OpalMediaOption * FindOption(
      const PString & name
    ) const { PWaitAndSignal m(m_mutex); return m_info == NULL ? NULL : m_info->FindOption(name); }

    template <class T> T * FindOptionAs(
      const PString & name
    ) const { return dynamic_cast<T *>(FindOption(name)); }

    bool IsValidForProtocol(const PString & protocol) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->IsValidForProtocol(protocol); }

    time_t GetCodecVersionTime() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? 0 : m_info->codecVersionTime; }

    ostream & PrintOptions(ostream & strm) const
    {
      PWaitAndSignal m(m_mutex);
      if (m_info != NULL)
        strm << setw(-1) << *m_info;
      return strm;
    }

#if OPAL_VIDEO

    void AdjustVideoArgs(
      PVideoDevice::OpenArgs & args  
    ) const;
#endif

    // Backward compatibility
    virtual PBoolean IsEmpty() const { PWaitAndSignal m(m_mutex); return m_info == NULL || !m_info->IsValid(); }
    operator PString() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? "" : m_info->formatName; }
    operator const char *() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? "" : m_info->formatName; }
    bool operator==(const char * other) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->formatName == other; }
    bool operator!=(const char * other) const { PWaitAndSignal m(m_mutex); return m_info == NULL || m_info->formatName != other; }
    bool operator==(const PString & other) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->formatName == other; }
    bool operator!=(const PString & other) const { PWaitAndSignal m(m_mutex); return m_info == NULL || m_info->formatName != other; }
    bool operator==(const OpalMediaFormat & other) const { PWaitAndSignal m(m_mutex); return Compare(other) == EqualTo; }
    bool operator!=(const OpalMediaFormat & other) const { PWaitAndSignal m(m_mutex); return Compare(other) != EqualTo; }
    friend bool operator==(const char * other, const OpalMediaFormat & fmt) { return fmt.m_info != NULL && fmt.m_info->formatName == other; }
    friend bool operator!=(const char * other, const OpalMediaFormat & fmt) { return fmt.m_info == NULL || fmt.m_info->formatName != other; }
    friend bool operator==(const PString & other, const OpalMediaFormat & fmt) { return fmt.m_info != NULL && fmt.m_info->formatName == other; }
    friend bool operator!=(const PString & other, const OpalMediaFormat & fmt) { return fmt.m_info == NULL || fmt.m_info->formatName != other; }

#if OPAL_H323
    static const PString & MediaPacketizationOption();
    static const PString & MediaPacketizationsOption();
    PStringArray GetMediaPacketizations() const;
    PStringSet GetMediaPacketizationSet() const { return PStringSet(GetMediaPacketizations()); }
    void SetMediaPacketizations(const PStringSet & packetizations);
#endif

  private:
    PBoolean SetSize(PINDEX) { return true; }

  protected:
    void Construct(OpalMediaFormatInternal * info);

    OpalMediaFormatInternal * m_info;
    PMutex                    m_mutex;

  friend class OpalMediaFormatInternal;
  friend class OpalMediaFormatList;
  friend class OpalVideoFormat;
};


class OpalAudioFormatInternal : public OpalMediaFormatInternal
{
  public:
    OpalAudioFormatInternal(
      const char * fullName,
      RTP_DataFrame::PayloadTypes rtpPayloadType,
      const char * encodingName,
      PINDEX   frameSize,
      unsigned frameTime,
      unsigned rxFrames,
      unsigned txFrames,
      unsigned maxFrames,
      unsigned clockRate,
      time_t timeStamp = 0,
      unsigned channels = 1
    );
    virtual PObject * Clone() const;
    virtual bool Merge(const OpalMediaFormatInternal & mediaFormat);
};

class OpalAudioFormat : public OpalMediaFormat
{
    PCLASSINFO(OpalAudioFormat, OpalMediaFormat);
  public:
    OpalAudioFormat(
      OpalMediaFormatInternal * info = NULL
    ) : OpalMediaFormat(info) { }
    OpalAudioFormat(
      const char * fullName
    ) : OpalMediaFormat(fullName) { }
    OpalAudioFormat(
      const char * fullName,    
      RTP_DataFrame::PayloadTypes rtpPayloadType, 
      const char * encodingName,
      PINDEX   frameSize,       
      unsigned frameTime,       
      unsigned rxFrames,        
      unsigned txFrames,        
      unsigned maxFrames = 256, 
      unsigned clockRate = 8000, 
      time_t timeStamp = 0,     
      unsigned channels = 1     
    );

    static const PString & RxFramesPerPacketOption();
    static const PString & TxFramesPerPacketOption();
    static const PString & MaxFramesPerPacketOption();
    static const PString & ChannelsOption();
};

#if OPAL_VIDEO

class OpalVideoFormatInternal;

class OpalVideoFormat : public OpalMediaFormat
{
    PCLASSINFO(OpalVideoFormat, OpalMediaFormat);
  public:
    OpalVideoFormat(
      OpalVideoFormatInternal * info = NULL
    );
    OpalVideoFormat(
      const char * fullName
    ) : OpalMediaFormat(fullName) { }
    OpalVideoFormat(
      const char * fullName,    
      RTP_DataFrame::PayloadTypes rtpPayloadType, 
      const char * encodingName,
      unsigned maxFrameWidth,   
      unsigned maxFrameHeight,  
      unsigned maxFrameRate,    
      unsigned maxBitRate,      
      time_t timeStamp = 0      
    );

    OpalVideoFormat & operator=(const OpalMediaFormat & other);

    static const PString & FrameWidthOption();
    static const PString & FrameHeightOption();
    static const PString & MinRxFrameWidthOption();
    static const PString & MinRxFrameHeightOption();
    static const PString & MaxRxFrameWidthOption();
    static const PString & MaxRxFrameHeightOption();
    static const PString & TemporalSpatialTradeOffOption();
    static const PString & TxKeyFramePeriodOption();
    static const PString & RateControlPeriodOption(); // Period over which the rate controller maintains the target bit rate.
    static const PString & RateControllerOption(); // String for controller algorithm. Empty is none.
    static const PString & FreezeUntilIntraFrameOption();

    P_DECLARE_STREAMABLE_ENUM(ContentRole,
      eNoRole,
      ePresentation,
      eMainRole,
      eSpeaker,
      eSignLanguage
    );

    enum { ContentRoleMask = 15 };
    __inline static unsigned ContentRoleBit(ContentRole contentRole) { return contentRole != eNoRole ? (1<<(contentRole-1)) : 0; }
    static const PString & ContentRoleOption();
    static const PString & ContentRoleMaskOption();

    P_DECLARE_STREAMABLE_BITWISE_ENUM_EX(
      RTCPFeedback,
      7,
      (
        e_NoRTCPFb,
        e_PLI,      
        e_FIR,      
        e_TMMBR,    
        e_TSTR,     
        e_VBCM,     
        e_NACK,     
        e_SLI       
      ),
      "", "pli", "fir", "tmmbr", "tstr", "vcbm", "nack", "sli"
    );
    static const PString & RTCPFeedbackOption();

#if OPAL_SIP

    P_DECLARE_STREAMABLE_ENUM(ImageAttributeInSDP,
      ImageAttrSuppressed,
      ImageAddrOffered,
      ImageAttrAnswerRequired
    );
    static const PString & UseImageAttributeInSDP();
#endif

    enum VideoFrameType {
      e_UnknownFrameType,
      e_NonFrameBoundary,
      e_IntraFrame,
      e_InterFrame
    };
    VideoFrameType GetVideoFrameType(const BYTE * payloadPtr, PINDEX payloadSize, PBYTEArray & context) const;
};

class OpalVideoFormatInternal : public OpalMediaFormatInternal
{
  public:
    OpalVideoFormatInternal(
      const char * fullName,
      RTP_DataFrame::PayloadTypes rtpPayloadType,
      const char * encodingName,
      unsigned maxFrameWidth,
      unsigned maxFrameHeight,
      unsigned maxFrameRate,
      unsigned maxBitRate,
      time_t timeStamp = 0
    );
    virtual PObject * Clone() const;
    virtual bool Merge(const OpalMediaFormatInternal & mediaFormat);
    virtual OpalVideoFormat::VideoFrameType GetVideoFrameType(const BYTE * payloadPtr, PINDEX payloadSize, PBYTEArray & context) const;
};

#endif // OPAL_VIDEO


#include <codec/known.h>


extern const OpalAudioFormat & GetOpalPCM16(unsigned clockRate, unsigned channels = 1);

extern const OpalAudioFormat & GetOpalPCM16();
extern const OpalAudioFormat & GetOpalPCM16S();
extern const OpalAudioFormat & GetOpalPCM16_12KHZ();
extern const OpalAudioFormat & GetOpalPCM16S_12KHZ();
extern const OpalAudioFormat & GetOpalPCM16_16KHZ();
extern const OpalAudioFormat & GetOpalPCM16S_16KHZ();
extern const OpalAudioFormat & GetOpalPCM16_24KHZ();
extern const OpalAudioFormat & GetOpalPCM16S_24KHZ();
extern const OpalAudioFormat & GetOpalPCM16_32KHZ();
extern const OpalAudioFormat & GetOpalPCM16S_32KHZ();
extern const OpalAudioFormat & GetOpalPCM16_48KHZ();
extern const OpalAudioFormat & GetOpalPCM16S_48KHZ();
extern const OpalAudioFormat & GetOpalL16_MONO_8KHZ();
extern const OpalAudioFormat & GetOpalL16_STEREO_8KHZ();
extern const OpalAudioFormat & GetOpalL16_MONO_16KHZ();
extern const OpalAudioFormat & GetOpalL16_STEREO_16KHZ();
extern const OpalAudioFormat & GetOpalL16_MONO_32KHZ();
extern const OpalAudioFormat & GetOpalL16_STEREO_32KHZ();
extern const OpalAudioFormat & GetOpalL16_MONO_48KHZ();
extern const OpalAudioFormat & GetOpalL16_STEREO_48KHZ();
extern const OpalAudioFormat & GetOpalG711_ULAW_64K();
extern const OpalAudioFormat & GetOpalG711_ALAW_64K();
extern const OpalAudioFormat & GetOpalG722();
extern const OpalAudioFormat & GetOpalG7221_24K();
extern const OpalAudioFormat & GetOpalG7221_32K();
extern const OpalAudioFormat & GetOpalG7221C_24K();
extern const OpalAudioFormat & GetOpalG7221C_32K();
extern const OpalAudioFormat & GetOpalG7221C_48K();
extern const OpalAudioFormat & GetOpalG7222();
extern const OpalAudioFormat & GetOpalG726_40K();
extern const OpalAudioFormat & GetOpalG726_32K();
extern const OpalAudioFormat & GetOpalG726_24K();
extern const OpalAudioFormat & GetOpalG726_16K();
extern const OpalAudioFormat & GetOpalG728();
extern const OpalAudioFormat & GetOpalG729();
extern const OpalAudioFormat & GetOpalG729A();
extern const OpalAudioFormat & GetOpalG729B();
extern const OpalAudioFormat & GetOpalG729AB();
extern const OpalAudioFormat & GetOpalG7231_6k3();
extern const OpalAudioFormat & GetOpalG7231_5k3();
extern const OpalAudioFormat & GetOpalG7231A_6k3();
extern const OpalAudioFormat & GetOpalG7231A_5k3();
extern const OpalAudioFormat & GetOpalG7231_Cisco_A();
extern const OpalAudioFormat & GetOpalG7231_Cisco_AR();
extern const OpalAudioFormat & GetOpalGSM0610();
extern const OpalAudioFormat & GetOpalGSMAMR();
extern const OpalAudioFormat & GetOpaliLBC();
extern const OpalAudioFormat & GetOpalSpeexNB();
extern const OpalAudioFormat & GetOpalSpeexWB();

#if OPAL_VIDEO
extern const OpalVideoFormat & GetOpalH261();
extern const OpalVideoFormat & GetOpalH263();
extern const OpalVideoFormat & GetOpalH263plus();
extern const OpalVideoFormat & GetOpalH264_MODE0();
extern const OpalVideoFormat & GetOpalH264_MODE1();
extern const OpalVideoFormat & GetOpalMPEG4();
#endif // OPAL_VIDEO

extern const OpalMediaFormat & GetOpalRFC2833();

#if OPAL_T38_CAPABILITY
extern const OpalMediaFormat & GetOpalCiscoNSE();
extern const OpalMediaFormat & GetOpalT38();
#endif


#define OpalPCM16          GetOpalPCM16()
#define OpalPCM16S         GetOpalPCM16S()
#define OpalPCM16_12KHZ    GetOpalPCM16_12KHZ()
#define OpalPCM16S_12KHZ   GetOpalPCM16S_12KHZ()
#define OpalPCM16_16KHZ    GetOpalPCM16_16KHZ()
#define OpalPCM16S_16KHZ   GetOpalPCM16S_16KHZ()
#define OpalPCM16_24KHZ    GetOpalPCM16_24KHZ()
#define OpalPCM16S_24KHZ   GetOpalPCM16S_24KHZ()
#define OpalPCM16_32KHZ    GetOpalPCM16_32KHZ()
#define OpalPCM16S_32KHZ   GetOpalPCM16S_32KHZ()
#define OpalPCM16_48KHZ    GetOpalPCM16_48KHZ()
#define OpalPCM16S_48KHZ   GetOpalPCM16S_48KHZ()
#define OpalL16_MONO_8KHZ  GetOpalL16_MONO_8KHZ()
#define OpalL16_STEREO_8KHZ GetOpalL16_STEREO_8KHZ()
#define OpalL16_MONO_16KHZ GetOpalL16_MONO_16KHZ()
#define OpalL16_STEREO_16KHZ GetOpalL16_STEREO_16KHZ()
#define OpalL16_MONO_32KHZ GetOpalL16_MONO_32KHZ()
#define OpalL16_STEREO_32KHZ GetOpalL16_STEREO_32KHZ()
#define OpalL16_MONO_48KHZ GetOpalL16_MONO_48KHZ()
#define OpalL16_STEREO_48KHZ GetOpalL16_STEREO_48KHZ()
#define OpalG711_ULAW_64K  GetOpalG711_ULAW_64K()
#define OpalG711_ALAW_64K  GetOpalG711_ALAW_64K()
#define OpalG722           GetOpalG722()
#define OpalG7221          OpalG7221_32K
#define OpalG7221_24K      GetOpalG7221_24K()
#define OpalG7221_32K      GetOpalG7221_32K()
#define OpalG7221C_24K     GetOpalG7221C_24K()
#define OpalG7221C_32K     GetOpalG7221C_32K()
#define OpalG7221C_48K     GetOpalG7221C_48K()
#define OpalG7222          GetOpalG7222()
#define OpalG726_40K       GetOpalG726_40K()
#define OpalG726_32K       GetOpalG726_32K()
#define OpalG726_24K       GetOpalG726_24K()
#define OpalG726_16K       GetOpalG726_16K()
#define OpalG728           GetOpalG728()
#define OpalG729           GetOpalG729()
#define OpalG729A          GetOpalG729A()
#define OpalG729B          GetOpalG729B()
#define OpalG729AB         GetOpalG729AB()
#define OpalG7231_6k3      GetOpalG7231_6k3()
#define OpalG7231_5k3      GetOpalG7231_5k3()
#define OpalG7231A_6k3     GetOpalG7231A_6k3()
#define OpalG7231A_5k3     GetOpalG7231A_5k3()
#define OpalG7231_Cisco_A  GetOpalG7231_Cisco_A()
#define OpalG7231_Cisco_AR GetOpalG7231_Cisco_AR()
#define OpalGSM0610        GetOpalGSM0610()
#define OpalGSMAMR         GetOpalGSMAMR()
#define OpaliLBC           GetOpaliLBC()
#define OpalSpeexNB        GetOpalSpeexNB()
#define OpalSpeexWB        GetOpalSpeexWB()
#define OpalRFC2833        GetOpalRFC2833()
#define OpalCiscoNSE       GetOpalCiscoNSE()
#define OpalT38            GetOpalT38()

#if OPAL_VIDEO
#define OpalH261       GetOpalH261()
#define OpalH263       GetOpalH263()
#define OpalH263plus   GetOpalH263plus()
#define OpalH264       GetOpalH264_MODE1()
#define OpalH264_MODE0 GetOpalH264_MODE0()
#define OpalH264_MODE1 GetOpalH264_MODE1()
#define OpalMPEG4      GetOpalMPEG4()
#endif

#define OpalL16Mono8kHz    OpalL16_MONO_8KHZ
#define OpalL16Mono16kHz   OpalL16_MONO_16KHZ
#define OpalG711uLaw       OpalG711_ULAW_64K
#define OpalG711ALaw       OpalG711_ALAW_64K


#endif  // OPAL_OPAL_MEDIAFMT_H


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