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: 24650 $
 * $Author: rjongbloed $
 * $Date: 2010-08-12 03:52:20 -0500 (Thu, 12 Aug 2010) $
 */

#ifndef OPAL_OPAL_MEDIAFMT_H
#define OPAL_OPAL_MEDIAFMT_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#ifdef _MSC_VER
#if _MSC_VER < 1300   
#pragma warning(disable:4663)
#endif
#endif

#include <opal/buildopts.h>

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

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

#include <limits>

#ifdef min
#undef min
#endif
#ifdef max
#undef max
#endif

class OpalMediaFormat;



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

    void Remove(
      const PStringArray & mask
    );

    void Reorder(
      const PStringArray & order
    );

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

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



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; }
#endif // OPAL_SIP

#if OPAL_H323
    struct H245GenericInfo {
      H245GenericInfo() { memset(this, 0, sizeof(*this)); }
      unsigned ordinal:16;
      enum Modes {
        None,
        Collapsing,
        NonCollapsing
      } mode:3;
      enum IntegerTypes {
        UnsignedInt,
        Unsigned32,
        BooleanArray
      } integerType:3;
      bool excludeTCS:1;
      bool excludeOLC:1;
      bool excludeReqMode:1;
    };

    const H245GenericInfo & GetH245Generic() const { return m_H245Generic; }
    void SetH245Generic(const H245GenericInfo & genericInfo) { m_H245Generic = genericInfo; }
#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,
      MergeType merge = MinMerge,
      T value = 0,
      T minimum = std::numeric_limits<T>::min(),
      T maximum = std::numeric_limits<T>::max()
    ) : OpalMediaOption(name, readOnly, merge),
        m_value(value),
        m_minimum(minimum),
        m_maximum(maximum)
    { }

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

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

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

    static __inline bool Intersect(bool a, bool b)         { return a && b; }
    static __inline bool Intersect(int a, int b)           { return a & b; }
    static __inline bool Intersect(unsigned a, unsigned b) { return a & b; }
    static __inline bool Intersect(double a, double b)     { return std::min(a, b); }

    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;
      SetValue(Intersect(GetValue(), otherOption->GetValue()));
      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)
    {
      if (value < m_minimum)
        m_value = m_minimum;
      else if (value > m_maximum)
        m_value = m_maximum;
      else
        m_value = value;
    }

    void SetMinimum(T m)
    {
      m_minimum = m;
    }

    void SetMaximum(T m)
    {
      m_maximum = m;
    }

  protected:
    T m_value;
    T m_minimum;
    T m_maximum;
};


typedef OpalMediaOptionValue<bool>     OpalMediaOptionBoolean;
typedef OpalMediaOptionValue<int>      OpalMediaOptionInteger;
typedef OpalMediaOptionValue<unsigned> OpalMediaOptionUnsigned;
typedef OpalMediaOptionValue<double>   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 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,
      PBoolean     needsJitter,
      unsigned 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:
    PCaselessString              formatName;
    RTP_DataFrame::PayloadTypes  rtpPayloadType;
    PString                      rtpEncodingName;
    OpalMediaType                mediaType;
    PMutex                       media_format_mutex;
    PSortedList<OpalMediaOption> options;
    time_t                       codecVersionTime;
    bool                         forceIsTransportable;
    int                          m_channels;

  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) : PContainer(c), m_info(c.m_info) { }
    OpalMediaFormat & operator=(const OpalMediaFormat & c)     { AssignContents(c); return *this; }
    virtual ~OpalMediaFormat()                                 { Destruct(); }
    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,                   
      unsigned 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 ValidateMerge(
      const OpalMediaFormat & mediaFormat
    ) const;

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

    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 ? "" : m_info->rtpEncodingName.GetPointer(); }

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

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

    unsigned GetBandwidth() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? 0 : m_info->GetOptionInteger(MaxBitRateOption(), 0); }
    static const PString & MaxBitRateOption();
    static const PString & TargetBitRateOption();

    PINDEX GetFrameSize() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? 0 : m_info->GetOptionInteger(MaxFrameSizeOption(), 0); }
    static const PString & MaxFrameSizeOption();

    unsigned GetFrameTime() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? 0 : m_info->GetOptionInteger(FrameTimeOption(), 0); }
    static const PString & FrameTimeOption();

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

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

    unsigned GetClockRate() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? 0 : m_info->GetOptionInteger(ClockRateOption(), 1000); }
    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); }

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

    bool SetOptionEnum(
      const PString & name,   
      PINDEX 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 SetRegisteredMediaFormat(
      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); }

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

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

  protected:
    void Construct(OpalMediaFormatInternal * info);

    OpalMediaFormatInternal * m_info;
    PMutex                    m_mutex;

  friend class OpalMediaFormatInternal;
  friend class OpalMediaFormatList;
};


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

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

#if OPAL_VIDEO
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
    );
    virtual PObject * Clone() const;
    virtual bool Merge(const OpalMediaFormatInternal & mediaFormat);
};


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

    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 & RateControlEnableOption();
    static const PString & RateControllerOption();
    static const PString & RateControllerBitRateScalerOption();

    enum ContentRole {
      eNoRole,
      ePresentation,
      eMainRole,
      eSpeaker,
      eSignLanguage,
      eNumRoles
    };
    enum { ContentRoleMask = 15 };
    __inline static unsigned ContentRoleBit(ContentRole contentRole) { return contentRole != eNoRole ? (1<<(contentRole-1)) : 0; }
    static const PString & ContentRoleOption();
    static const PString & ContentRoleMaskOption();
};
#endif

// List of known media formats

#define OPAL_PCM16          "PCM-16"
#define OPAL_PCM16S         "PCM-16S"
#define OPAL_PCM16_16KHZ    "PCM-16-16kHz"
#define OPAL_PCM16S_16KHZ   "PCM-16S-16kHz"
#define OPAL_PCM16_32KHZ    "PCM-16-32kHz"
#define OPAL_PCM16S_32KHZ   "PCM-16S-32kHz"
#define OPAL_PCM16_48KHZ    "PCM-16-48kHz"
#define OPAL_PCM16S_48KHZ   "PCM-16S-48kHz"
#define OPAL_L16_MONO_8KHZ  "Linear-16-Mono-8kHz"
#define OPAL_L16_STEREO_8KHZ "Linear-16-Stereo-8kHz"
#define OPAL_L16_MONO_16KHZ "Linear-16-Mono-16kHz"
#define OPAL_L16_STEREO_16KHZ "Linear-16-Stereo-16kHz"
#define OPAL_L16_MONO_32KHZ "Linear-16-Mono-32kHz"
#define OPAL_L16_STEREO_32KHZ "Linear-16-Stereo-32kHz"
#define OPAL_L16_MONO_48KHZ "Linear-16-Mono-48kHz"
#define OPAL_L16_STEREO_48KHZ "Linear-16-Stereo-48kHz"
#define OPAL_G711_ULAW_64K  "G.711-uLaw-64k"
#define OPAL_G711_ALAW_64K  "G.711-ALaw-64k"
#define OPAL_G722           "G.722"
#define OPAL_G7221          "G.722.1"
#define OPAL_G7222          "G.722.2"
#define OPAL_G726_40K       "G.726-40K"
#define OPAL_G726_32K       "G.726-32K"
#define OPAL_G726_24K       "G.726-24K"
#define OPAL_G726_16K       "G.726-16K"
#define OPAL_G728           "G.728"
#define OPAL_G729           "G.729"
#define OPAL_G729A          "G.729A"
#define OPAL_G729B          "G.729B"
#define OPAL_G729AB         "G.729A/B"
#define OPAL_G7231          "G.723.1"
#define OPAL_G7231_6k3      OPAL_G7231
#define OPAL_G7231_5k3      "G.723.1(5.3k)"
#define OPAL_G7231A_6k3     "G.723.1A(6.3k)"
#define OPAL_G7231A_5k3     "G.723.1A(5.3k)"
#define OPAL_GSM0610        "GSM-06.10"
#define OPAL_GSMAMR         "GSM-AMR"
#define OPAL_iLBC           "iLBC"
#define OPAL_H261           "H.261"
#define OPAL_H263           "H.263"
#define OPAL_H264_MODE0     "H.264-0"
#define OPAL_H264_MODE1     "H.264-1"
#define OPAL_MPEG4          "MPEG4"
#define OPAL_RFC2833        "UserInput/RFC2833"
#define OPAL_CISCONSE       "NamedSignalEvent"
#define OPAL_T38            "T.38"

extern const OpalAudioFormat & GetOpalPCM16();
extern const OpalAudioFormat & GetOpalPCM16S();
extern const OpalAudioFormat & GetOpalPCM16_16KHZ();
extern const OpalAudioFormat & GetOpalPCM16S_16KHZ();
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();
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 & GetOpalGSM0610();
extern const OpalAudioFormat & GetOpalGSMAMR();
extern const OpalAudioFormat & GetOpaliLBC();

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_16KHZ    GetOpalPCM16_16KHZ()
#define OpalPCM16S_16KHZ   GetOpalPCM16S_16KHZ()
#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          GetOpalG7221()
#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 OpalGSM0610        GetOpalGSM0610()
#define OpalGSMAMR         GetOpalGSMAMR()
#define OpaliLBC           GetOpaliLBC()
#define OpalRFC2833        GetOpalRFC2833()
#define OpalCiscoNSE       GetOpalCiscoNSE()
#define OpalT38            GetOpalT38()

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

#define OPAL_T140             "T.140"
#define OpalT140              GetOpalT140()
extern const OpalMediaFormat & GetOpalT140();

#if OPAL_HAS_MSRP
#define OPAL_MSRP           "MSRP"
#define OpalMSRP            GetOpalMSRP()
extern const OpalMediaFormat & GetOpalMSRP();
#endif

#if OPAL_HAS_SIPIM
#define OPAL_SIPIM             "SIP-IM"
#define OpalSIPIM              GetOpalSIPIM()
extern const OpalMediaFormat & GetOpalSIPIM();
#endif

#ifdef _MSC_VER
#if _MSC_VER < 1300
#pragma warning(default:4663)
#endif
#endif

#endif  // OPAL_OPAL_MEDIAFMT_H


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

---