OPAL  Version 3.12.9
mediafmt.h
Go to the documentation of this file.
1 /*
2  * mediafmt.h
3  *
4  * Media Format descriptions
5  *
6  * Open Phone Abstraction Library (OPAL)
7  * Formally known as the Open H323 project.
8  *
9  * Copyright (c) 2001 Equivalence Pty. Ltd.
10  *
11  * The contents of this file are subject to the Mozilla Public License
12  * Version 1.0 (the "License"); you may not use this file except in
13  * compliance with the License. You may obtain a copy of the License at
14  * http://www.mozilla.org/MPL/
15  *
16  * Software distributed under the License is distributed on an "AS IS"
17  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
18  * the License for the specific language governing rights and limitations
19  * under the License.
20  *
21  * The Original Code is Open H323 Library.
22  *
23  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
24  *
25  * Contributor(s): ______________________________________.
26  *
27  * $Revision: 31002 $
28  * $Author: rjongbloed $
29  * $Date: 2013-11-29 09:53:33 +1100 (Fri, 29 Nov 2013) $
30  */
31 
32 #ifndef OPAL_OPAL_MEDIAFMT_H
33 #define OPAL_OPAL_MEDIAFMT_H
34 
35 #ifdef P_USE_PRAGMA
36 #pragma interface
37 #endif
38 
39 #include <opal/buildopts.h>
40 
41 #include <opal/mediatype.h>
42 #include <rtp/rtp.h>
43 #include <ptlib/bitwise_enum.h>
44 
45 #if OPAL_VIDEO
46 #include <ptlib/videoio.h>
47 #endif
48 
49 #include <limits>
50 
51 
52 class PluginCodec_OptionMap;
53 class OpalMediaFormat;
54 class H225_BandWidth;
55 
56 
58 
63 class OpalBandwidth {
64  public:
65  enum Direction {
66  Rx = 1,
67  Tx,
68  RxTx,
69  TxRx = RxTx
70  };
71  friend std::ostream & operator<<(std::ostream & strm, OpalBandwidth::Direction dir);
72 
73  typedef unsigned int_type;
74 
75  __inline OpalBandwidth(int_type bps = 0) : m_bps(bps) { }
76  __inline OpalBandwidth & operator=(int_type bps) { m_bps = bps; return *this; }
77  __inline operator int_type() const { return m_bps; }
78 
79  __inline OpalBandwidth operator+ (const OpalBandwidth & bw) const { return OpalBandwidth(m_bps + bw.m_bps); }
80  __inline OpalBandwidth operator- (const OpalBandwidth & bw) const { return OpalBandwidth(m_bps - bw.m_bps); }
81  __inline OpalBandwidth & operator+=(const OpalBandwidth & bw) { m_bps += bw.m_bps; return *this; }
82  __inline OpalBandwidth & operator-=(const OpalBandwidth & bw) { m_bps += bw.m_bps; return *this; }
83  __inline OpalBandwidth & operator&=(const OpalBandwidth & bw) { if (m_bps > bw.m_bps) m_bps = bw.m_bps; return *this; }
84 
85  friend std::ostream & operator<<(std::ostream & strm, const OpalBandwidth & bw);
86  friend std::istream & operator>>(std::istream & strm, OpalBandwidth & bw);
87 
88 #if OPAL_H323
89  OpalBandwidth(const H225_BandWidth & bw);
90  OpalBandwidth & operator=(const H225_BandWidth & bw);
91  void SetH225(H225_BandWidth & bw) const;
92  unsigned AsH225() const { return (m_bps+99)/100; }
93 #endif
94  unsigned kbps() const { return (m_bps+999)/1000; }
95 
96  static OpalBandwidth Max() { return OpalBandwidth(UINT_MAX); }
97 
98  protected:
99  int_type m_bps;
100 };
101 
102 
104 
105 PLIST(OpalMediaFormatBaseList, OpalMediaFormat);
106 
109 class OpalMediaFormatList : public OpalMediaFormatBaseList
110 {
111  PCLASSINFO(OpalMediaFormatList, OpalMediaFormatBaseList);
112  public:
117  OpalMediaFormatList();
118 
121  OpalMediaFormatList(
122  const OpalMediaFormat & format
123  );
124 
127  OpalMediaFormatList(const OpalMediaFormatList & l) : OpalMediaFormatBaseList(l) { }
129 
135  OpalMediaFormatList & operator+=(
136  const char * wildcard
137  ) { PConstString w(wildcard); return operator+=(w); }
138 
142  OpalMediaFormatList & operator+=(
143  const PString & wildcard
144  );
145 
149  OpalMediaFormatList & operator+=(
150  const OpalMediaFormat & format
151  );
152 
156  OpalMediaFormatList & operator+=(
157  const OpalMediaFormatList & formats
158  );
159 
163  OpalMediaFormatList & operator-=(
164  const OpalMediaFormat & format
165  );
166 
170  OpalMediaFormatList & operator-=(
171  const OpalMediaFormatList & formats
172  );
173 
190  const_iterator FindFormat(
191  RTP_DataFrame::PayloadTypes rtpPayloadType,
192  const unsigned clockRate = 0,
193  const char * rtpEncodingName = NULL,
194  const char * protocol = NULL,
195  const_iterator start = const_iterator()
196  ) const;
197 
214  const_iterator FindFormat(
215  const PString & wildcard,
216  const_iterator start = const_iterator()
217  ) const;
218 
221  PBoolean HasFormat(
222  RTP_DataFrame::PayloadTypes rtpPayloadType
223  ) const { return FindFormat(rtpPayloadType) != end(); }
224 
230  PBoolean HasFormat(
231  const PString & wildcard
232  ) const { return FindFormat(wildcard) != end(); }
233 
236  bool HasType(
237  const OpalMediaType & type,
238  bool mustBeTransportable = true
239  ) const;
240 
243  OpalMediaTypeList GetMediaTypes() const;
244 
260  void Reorder(
261  const PStringArray & order
262  );
263 
282  void Remove(
283  const PStringArray & mask
284  );
285 
288  void RemoveNonTransportable();
290 
291  private:
292  virtual PINDEX Append(PObject *) { return P_MAX_INDEX; }
293  virtual PINDEX Insert(const PObject &, PObject *) { return P_MAX_INDEX; }
294 };
295 
296 
298 
301 class OpalMediaOption : public PObject
302 {
303  PCLASSINFO(OpalMediaOption, PObject);
304  public:
305  // Note the below enum must be identical to PluginCodec_OptionMerge in opalplugin.h
306  enum MergeType {
307  NoMerge,
308  MinMerge,
309  MaxMerge,
310  EqualMerge,
311  NotEqualMerge,
312  AlwaysMerge,
313  CustomMerge,
314  IntersectionMerge, // Set intersection, applies to numeric (bit wise AND) or string (common substrings)
315 
316  // Synonyms
317  AndMerge = MinMerge, // Applies to Boolean option or Enum with two elements
318  OrMerge = MaxMerge // Applies to Boolean option or Enum with two elements
319  };
320 
321  protected:
322  OpalMediaOption(
323  const PString & name
324  );
325  OpalMediaOption(
326  const char * name,
327  bool readOnly,
328  MergeType merge
329  );
330 
331  public:
332  virtual Comparison Compare(const PObject & obj) const;
333 
334  virtual bool Merge(
335  const OpalMediaOption & option
336  );
337 
338  virtual bool ValidateMerge(
339  const OpalMediaOption & option
340  ) const;
341 
342  virtual Comparison CompareValue(
343  const OpalMediaOption & option
344  ) const = 0;
345  virtual void Assign(
346  const OpalMediaOption & option
347  ) = 0;
348 
349  PString AsString() const;
350  bool FromString(const PString & value);
351 
352  const PString & GetName() const { return m_name; }
353 
354  bool IsReadOnly() const { return m_readOnly; }
355  void SetReadOnly(bool readOnly) { m_readOnly = readOnly; }
356 
357  MergeType GetMerge() const { return m_merge; }
358  void SetMerge(MergeType merge) { m_merge = merge; }
359 
360 #if OPAL_SIP
361  const PString & GetFMTPName() const { return m_FMTPName; }
362  void SetFMTPName(const char * name) { m_FMTPName = name; }
363 
364  const PString & GetFMTPDefault() const { return m_FMTPDefault; }
365  void SetFMTPDefault(const char * value) { m_FMTPDefault = value; }
366 
367  void SetFMTP(const char * name, const char * dflt)
368  {
369  m_FMTPName = name;
370  m_FMTPDefault = dflt;
371  }
372 #define OPAL_SET_MEDIA_OPTION_FMTP(opt, name, dflt) (opt)->SetFMTP(name, dflt)
373 #else
374 #define OPAL_SET_MEDIA_OPTION_FMTP(opt, name, dflt)
375 #endif // OPAL_SIP
376 
377 #if OPAL_H323
378  struct H245GenericInfo {
379  H245GenericInfo();
380  H245GenericInfo(
381  unsigned mask,
382  const char * dflt = NULL
383  );
384 
385  unsigned ordinal;
386 
387  enum Modes {
388  None,
389  Collapsing,
390  NonCollapsing
391  } mode;
392 
393  enum IntegerTypes {
394  UnsignedInt,
395  Unsigned32,
396  BooleanArray
397  } integerType;
398 
399  bool excludeTCS;
400  bool excludeOLC;
401  bool excludeReqMode;
402  int position; // Position in sequence for parameter
403  PString defaultValue; // Do not include parameter if this value
404  };
405 
406  const H245GenericInfo & GetH245Generic() const { return m_H245Generic; }
407  void SetH245Generic(const H245GenericInfo & genericInfo) { m_H245Generic = genericInfo; }
408 #define OPAL_SET_MEDIA_OPTION_H245(opt, ...) (opt)->SetH245Generic(OpalMediaOption::H245GenericInfo(__VA_ARGS__))
409 #else
410 #define OPAL_SET_MEDIA_OPTION_H245(opt, ...)
411 #endif // OPAL_H323
412 
413  protected:
414  PCaselessString m_name;
415  bool m_readOnly;
416  MergeType m_merge;
417 
418 #if OPAL_SIP
419  PCaselessString m_FMTPName;
420  PString m_FMTPDefault;
421 #endif // OPAL_SIP
422 
423 #if OPAL_H323
424  H245GenericInfo m_H245Generic;
425 #endif // OPAL_H323
426 };
427 
428 
429 template <typename T>
430 class OpalMediaOptionValue : public OpalMediaOption
431 {
432  PCLASSINFO(OpalMediaOptionValue, OpalMediaOption);
433  public:
434  OpalMediaOptionValue(
435  const char * name,
436  bool readOnly,
437  OpalMediaOption::MergeType merge = OpalMediaOption::MinMerge,
438  T value = T()
439  )
440  : OpalMediaOption(name, readOnly, merge)
441  , m_value(value)
442  {
443  }
444 
445  virtual PObject * Clone() const
446  {
447  return new OpalMediaOptionValue(*this);
448  }
449 
450  virtual void PrintOn(ostream & strm) const
451  {
452  strm << m_value;
453  }
454 
455  virtual void ReadFrom(istream & strm)
456  {
457  strm >> m_value;
458  }
459 
460  virtual bool Merge(const OpalMediaOption & option)
461  {
462  if (m_merge != IntersectionMerge)
463  return OpalMediaOption::Merge(option);
464 
465  const OpalMediaOptionValue * otherOption = PDownCast(const OpalMediaOptionValue, &option);
466  if (otherOption == NULL)
467  return false;
468 
469  m_value &= otherOption->m_value;
470  return true;
471  }
472 
473  virtual Comparison CompareValue(const OpalMediaOption & option) const
474  {
475  const OpalMediaOptionValue * otherOption = PDownCast(const OpalMediaOptionValue, &option);
476  if (otherOption == NULL)
477  return GreaterThan;
478  if (m_value < otherOption->m_value)
479  return LessThan;
480  if (m_value > otherOption->m_value)
481  return GreaterThan;
482  return EqualTo;
483  }
484 
485  virtual void Assign(const OpalMediaOption & option)
486  {
487  const OpalMediaOptionValue * otherOption = PDownCast(const OpalMediaOptionValue, &option);
488  if (otherOption != NULL)
489  m_value = otherOption->m_value;
490  }
491 
492  T GetValue() const
493  {
494  return m_value;
495  }
496 
497  void SetValue(T value)
498  {
499  m_value = value;
500  }
501 
502  protected:
503  T m_value;
504 };
505 
506 
507 template <typename T>
508 class OpalMediaOptionNumericalValue : public OpalMediaOptionValue<T>
509 {
510  typedef OpalMediaOptionValue<T> BaseClass;
511  PCLASSINFO(OpalMediaOptionNumericalValue, BaseClass);
512  public:
513  OpalMediaOptionNumericalValue(
514  const char * name,
515  bool readOnly,
516  OpalMediaOption::MergeType merge = OpalMediaOption::MinMerge,
517  T value = 0,
518  T minimum = std::numeric_limits<T>::min(),
519  T maximum = std::numeric_limits<T>::max()
520  )
521  : BaseClass(name, readOnly, merge, value)
522  , m_minimum(minimum)
523  , m_maximum(maximum)
524  {
525  }
526 
527  virtual PObject * Clone() const
528  {
529  return new OpalMediaOptionNumericalValue(*this);
530  }
531 
532  virtual void ReadFrom(istream & strm)
533  {
534  T temp = 0;
535  strm >> temp;
536  if (strm.fail())
537  return;
538  if (temp >= m_minimum && temp <= m_maximum)
539  this->m_value = temp;
540  else
541  strm.setstate(ios::badbit);
542  }
543 
544  void SetValue(T value)
545  {
546  if (value < m_minimum)
547  this->m_value = m_minimum;
548  else if (value > m_maximum)
549  this->m_value = m_maximum;
550  else
551  this->m_value = value;
552  }
553 
554  void SetMinimum(T m)
555  {
556  this->m_minimum = m;
557  }
558 
559  void SetMaximum(T m)
560  {
561  this->m_maximum = m;
562  }
563 
564  protected:
565  T m_minimum;
566  T m_maximum;
567 };
568 
569 
570 typedef OpalMediaOptionNumericalValue<bool> OpalMediaOptionBoolean;
571 typedef OpalMediaOptionNumericalValue<int> OpalMediaOptionInteger;
572 typedef OpalMediaOptionNumericalValue<unsigned> OpalMediaOptionUnsigned;
573 
574 // Wrapper class so we can implement intersection (&= operator) for floating point
575 class OpalMediaOptionRealValue
576 {
577  double m_value;
578  public:
579  OpalMediaOptionRealValue(double value = 0) : m_value(value) { }
580  operator double() const { return m_value; }
581  void operator&=(double other) { if (m_value > other) m_value = other; }
582  friend ostream & operator<<(ostream & strm, const OpalMediaOptionRealValue & value) { return strm << value.m_value; }
583  friend istream & operator>>(istream & strm, OpalMediaOptionRealValue & value) { return strm >> value.m_value; }
584 };
585 
586 typedef OpalMediaOptionNumericalValue<OpalMediaOptionRealValue> OpalMediaOptionReal;
587 
588 
589 class OpalMediaOptionEnum : public OpalMediaOption
590 {
591  PCLASSINFO(OpalMediaOptionEnum, OpalMediaOption);
592  public:
593  OpalMediaOptionEnum(
594  const char * name,
595  bool readOnly
596  );
597  OpalMediaOptionEnum(
598  const char * name,
599  bool readOnly,
600  const char * const * enumerations,
601  PINDEX count,
602  MergeType merge = EqualMerge,
603  PINDEX value = 0
604  );
605 
606  virtual PObject * Clone() const;
607  virtual void PrintOn(ostream & strm) const;
608  virtual void ReadFrom(istream & strm);
609 
610  virtual Comparison CompareValue(const OpalMediaOption & option) const;
611  virtual void Assign(const OpalMediaOption & option);
612 
613  PINDEX GetValue() const { return m_value; }
614  void SetValue(PINDEX value);
615 
616  const PStringArray & GetEnumerations() const { return m_enumerations; }
617  void SetEnumerations(const PStringArray & e)
618  {
619  m_enumerations = e;
620  }
621 
622  protected:
623  PStringArray m_enumerations;
624  PINDEX m_value;
625 };
626 
627 
628 class OpalMediaOptionString : public OpalMediaOption
629 {
630  PCLASSINFO(OpalMediaOptionString, OpalMediaOption);
631  public:
632  OpalMediaOptionString(
633  const char * name,
634  bool readOnly
635  );
636  OpalMediaOptionString(
637  const char * name,
638  bool readOnly,
639  const PString & value
640  );
641 
642  virtual PObject * Clone() const;
643  virtual void PrintOn(ostream & strm) const;
644  virtual void ReadFrom(istream & strm);
645 
646  virtual bool Merge(const OpalMediaOption & option);
647  virtual Comparison CompareValue(const OpalMediaOption & option) const;
648  virtual void Assign(const OpalMediaOption & option);
649 
650  const PString & GetValue() const { return m_value; }
651  void SetValue(const PString & value);
652 
653  protected:
654  PString m_value;
655 };
656 
657 
658 class OpalMediaOptionOctets : public OpalMediaOption
659 {
660  PCLASSINFO(OpalMediaOptionOctets, OpalMediaOption);
661  public:
662  OpalMediaOptionOctets(
663  const char * name,
664  bool readOnly,
665  bool base64 = false
666  );
667  OpalMediaOptionOctets(
668  const char * name,
669  bool readOnly,
670  bool base64,
671  const PBYTEArray & value
672  );
673  OpalMediaOptionOctets(
674  const char * name,
675  bool readOnly,
676  bool base64,
677  const BYTE * data,
678  PINDEX length
679  );
680 
681  virtual PObject * Clone() const;
682  virtual void PrintOn(ostream & strm) const;
683  virtual void ReadFrom(istream & strm);
684 
685  virtual Comparison CompareValue(const OpalMediaOption & option) const;
686  virtual void Assign(const OpalMediaOption & option);
687 
688  const PBYTEArray & GetValue() const { return m_value; }
689  void SetValue(const PBYTEArray & value);
690  void SetValue(const BYTE * data, PINDEX length);
691 
692  void SetBase64(bool b)
693  {
694  m_base64 = b;
695  }
696 
697  protected:
698  PBYTEArray m_value;
699  bool m_base64;
700 };
701 
702 
704 
705 class OpalMediaFormatInternal : public PObject
706 {
707  PCLASSINFO(OpalMediaFormatInternal, PObject);
708  public:
709  OpalMediaFormatInternal(
710  const char * fullName,
711  const OpalMediaType & mediaType,
712  RTP_DataFrame::PayloadTypes rtpPayloadType,
713  const char * encodingName,
714  bool needsJitter,
715  OpalBandwidth bandwidth,
716  PINDEX frameSize,
717  unsigned frameTime,
718  unsigned clockRate,
719  time_t timeStamp
720  );
721 
722  const PCaselessString & GetName() const { return formatName; }
723 
724  virtual PObject * Clone() const;
725  virtual void PrintOn(ostream & strm) const;
726 
727  virtual bool IsValid() const;
728  virtual bool IsTransportable() const;
729 
730  virtual PStringToString GetOptions() const;
731  virtual bool GetOptionValue(const PString & name, PString & value) const;
732  virtual bool SetOptionValue(const PString & name, const PString & value);
733  virtual bool GetOptionBoolean(const PString & name, bool dflt) const;
734  virtual bool SetOptionBoolean(const PString & name, bool value);
735  virtual int GetOptionInteger(const PString & name, int dflt) const;
736  virtual bool SetOptionInteger(const PString & name, int value);
737  virtual double GetOptionReal(const PString & name, double dflt) const;
738  virtual bool SetOptionReal(const PString & name, double value);
739  virtual PINDEX GetOptionEnum(const PString & name, PINDEX dflt) const;
740  virtual bool SetOptionEnum(const PString & name, PINDEX value);
741  virtual PString GetOptionString(const PString & name, const PString & dflt) const;
742  virtual bool SetOptionString(const PString & name, const PString & value);
743  virtual bool GetOptionOctets(const PString & name, PBYTEArray & octets) const;
744  virtual bool SetOptionOctets(const PString & name, const PBYTEArray & octets);
745  virtual bool SetOptionOctets(const PString & name, const BYTE * data, PINDEX length);
746  virtual bool AddOption(OpalMediaOption * option, PBoolean overwrite = false);
747  virtual OpalMediaOption * FindOption(const PString & name) const;
748 
749  virtual bool ToNormalisedOptions();
750  virtual bool ToCustomisedOptions();
751  virtual bool Merge(const OpalMediaFormatInternal & mediaFormat);
752 
753  virtual bool ValidateMerge(const OpalMediaFormatInternal & mediaFormat) const;
754 
755  virtual bool IsValidForProtocol(const PString & protocol) const;
756 
757  protected:
758  bool AdjustByOptionMaps(
759  PTRACE_PARAM(const char * operation,)
760  bool (*adjuster)(PluginCodec_OptionMap & original, PluginCodec_OptionMap & changed)
761  );
762 
763  PCaselessString formatName;
764  RTP_DataFrame::PayloadTypes rtpPayloadType;
765  PCaselessString rtpEncodingName;
766  OpalMediaType mediaType;
767  PMutex media_format_mutex;
768  PSortedList<OpalMediaOption> options;
769  time_t codecVersionTime;
770  bool forceIsTransportable;
771  int m_channels;
772 
773  friend bool operator==(const char * other, const OpalMediaFormat & fmt);
774  friend bool operator!=(const char * other, const OpalMediaFormat & fmt);
775  friend bool operator==(const PString & other, const OpalMediaFormat & fmt);
776  friend bool operator!=(const PString & other, const OpalMediaFormat & fmt);
777 
778  friend class OpalMediaFormat;
779  friend class OpalMediaFormatList;
780  friend class OpalAudioFormatInternal;
781 };
782 
783 
785 
791 class OpalMediaFormat : public PContainer
792 {
793  PCLASSINFO(OpalMediaFormat, PContainer)
794  public:
795  OpalMediaFormat(const OpalMediaFormat & c);
796  virtual ~OpalMediaFormat();
797  OpalMediaFormat & operator=(const OpalMediaFormat & c) { AssignContents(c); return *this; }
798  virtual PBoolean MakeUnique();
799  protected:
800  virtual void DestroyContents();
801  virtual void AssignContents(const PContainer & c);
802 
803  public:
806  OpalMediaFormat(
807  OpalMediaFormatInternal * info = NULL
808  );
809 
823  OpalMediaFormat(
824  const char * fullName,
825  const OpalMediaType & mediaType,
826  RTP_DataFrame::PayloadTypes rtpPayloadType,
827  const char * encodingName,
828  PBoolean needsJitter,
829  OpalBandwidth bandwidth,
830  PINDEX frameSize,
831  unsigned frameTime,
832  unsigned clockRate,
833  time_t timeStamp = 0
834  );
835 
845  OpalMediaFormat(
846  RTP_DataFrame::PayloadTypes rtpPayloadType,
847  unsigned clockRate,
848  const char * rtpEncodingName = NULL,
849  const char * protocol = NULL
850  );
851 
865  OpalMediaFormat(
866  const char * wildcard
867  );
868 
882  OpalMediaFormat(
883  const PString & wildcard
884  );
885 
889  OpalMediaFormat & operator=(
890  RTP_DataFrame::PayloadTypes rtpPayloadType
891  );
892 
896  OpalMediaFormat & operator=(
897  const char * wildcard
898  );
899 
903  OpalMediaFormat & operator=(
904  const PString & wildcard
905  );
906 
909  virtual PObject * Clone() const;
910 
913  virtual Comparison Compare(const PObject & obj) const;
914 
919  virtual void PrintOn(ostream & strm) const;
920 
923  virtual void ReadFrom(istream & strm);
924 
929  bool ToNormalisedOptions();
930 
934  bool ToCustomisedOptions();
935 
938  bool Update(
939  const OpalMediaFormat & mediaFormat
940  );
941 
952  bool Merge(
953  const OpalMediaFormat & mediaFormat,
954  bool copyPayloadType = false
955  );
958  bool ValidateMerge(
959  const OpalMediaFormat & mediaFormat
960  ) const;
961 
964  PString GetName() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? "" : m_info->formatName; }
965 
970  PBoolean IsValid() const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->IsValid(); }
971 
975  PBoolean IsTransportable() const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->IsTransportable(); }
976 
982  RTP_DataFrame::PayloadTypes GetPayloadType() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? RTP_DataFrame::IllegalPayloadType : m_info->rtpPayloadType; }
983  void SetPayloadType(RTP_DataFrame::PayloadTypes type) { PWaitAndSignal m(m_mutex); MakeUnique(); if (m_info != NULL) m_info->rtpPayloadType = type; }
984 
987  const char * GetEncodingName() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? "" : (const char *)m_info->rtpEncodingName; }
988 
991  OpalMediaType GetMediaType() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? OpalMediaType() : m_info->mediaType; }
992 
996  bool NeedsJitterBuffer() const { return GetOptionBoolean(NeedsJitterOption()); }
997  static const PString & NeedsJitterOption();
998 
1001  OpalBandwidth GetMaxBandwidth() const { return GetOptionInteger(MaxBitRateOption()); }
1002  static const PString & MaxBitRateOption();
1003 
1006  OpalBandwidth GetUsedBandwidth() const { return GetOptionInteger(TargetBitRateOption(), GetOptionInteger(MaxBitRateOption())); }
1007  static const PString & TargetBitRateOption();
1008 
1013  PINDEX GetFrameSize() const { return GetOptionInteger(MaxFrameSizeOption()); }
1014  static const PString & MaxFrameSizeOption();
1015 
1019  unsigned GetFrameTime() const { return GetOptionInteger(FrameTimeOption()); }
1020  static const PString & FrameTimeOption();
1021 
1024  unsigned GetTimeUnits() const { return GetClockRate()/1000; }
1025 
1026  enum StandardClockRate {
1027  AudioClockRate = 8000,
1028  VideoClockRate = 90000
1029  };
1030 
1033  unsigned GetClockRate() const { return GetOptionInteger(ClockRateOption(), AudioClockRate); }
1034  static const PString & ClockRateOption();
1035 
1038  static const PString & ProtocolOption();
1039 
1046  static const PString & MaxTxPacketSizeOption();
1047 
1051  PStringToString GetOptions() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? PStringToString() : m_info->GetOptions(); }
1052 
1055  PINDEX GetOptionCount() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? 0 : m_info->options.GetSize(); }
1056 
1060  const OpalMediaOption & GetOption(
1061  PINDEX index
1062  ) const { PWaitAndSignal m(m_mutex); return m_info->options[index]; }
1063 
1068  bool GetOptionValue(
1069  const PString & name,
1070  PString & value
1071  ) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->GetOptionValue(name, value); }
1072 
1079  bool SetOptionValue(
1080  const PString & name,
1081  const PString & value
1082  ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionValue(name, value); }
1083 
1087  bool GetOptionBoolean(
1088  const PString & name,
1089  bool dflt = false
1090  ) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->GetOptionBoolean(name, dflt); }
1091 
1098  bool SetOptionBoolean(
1099  const PString & name,
1100  bool value
1101  ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionBoolean(name, value); }
1102 
1106  int GetOptionInteger(
1107  const PString & name,
1108  int dflt = 0
1109  ) const { PWaitAndSignal m(m_mutex); return m_info == NULL ? dflt : m_info->GetOptionInteger(name, dflt); }
1110 
1118  bool SetOptionInteger(
1119  const PString & name,
1120  int value
1121  ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionInteger(name, value); }
1122 
1126  double GetOptionReal(
1127  const PString & name,
1128  double dflt = 0
1129  ) const { PWaitAndSignal m(m_mutex); return m_info == NULL ? dflt : m_info->GetOptionReal(name, dflt); }
1130 
1137  bool SetOptionReal(
1138  const PString & name,
1139  double value
1140  ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionReal(name, value); }
1141 
1149  template <typename Enum>
1150  Enum GetOptionEnum(
1151  const PString & name,
1152  Enum dflt = (Enum)0
1153  ) const { PWaitAndSignal m(m_mutex); return m_info == NULL ? dflt : (Enum)m_info->GetOptionEnum(name, dflt); }
1154 
1164  template <typename Enum>
1165  bool SetOptionEnum(
1166  const PString & name,
1167  Enum value
1168  ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionEnum(name, value); }
1169 
1173  PString GetOptionString(
1174  const PString & name,
1175  const PString & dflt = PString::Empty()
1176  ) const { PWaitAndSignal m(m_mutex); return m_info == NULL ? dflt : m_info->GetOptionString(name, dflt); }
1177 
1184  bool SetOptionString(
1185  const PString & name,
1186  const PString & value
1187  ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionString(name, value); }
1188 
1192  bool GetOptionOctets(
1193  const PString & name,
1194  PBYTEArray & octets
1195  ) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->GetOptionOctets(name, octets); }
1196 
1203  bool SetOptionOctets(
1204  const PString & name,
1205  const PBYTEArray & octets
1206  ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionOctets(name, octets); }
1207  bool SetOptionOctets(
1208  const PString & name,
1209  const BYTE * data,
1210  PINDEX length
1211  ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->SetOptionOctets(name, data, length); }
1212 
1215  static OpalMediaFormatList GetAllRegisteredMediaFormats();
1216  static void GetAllRegisteredMediaFormats(
1217  OpalMediaFormatList & copy
1218  );
1219 
1223  static bool SetRegisteredMediaFormat(
1224  const OpalMediaFormat & mediaFormat
1225  );
1226 
1230  static bool RemoveRegisteredMediaFormat(
1231  const OpalMediaFormat & mediaFormat
1232  );
1233 
1237  bool AddOption(
1238  OpalMediaOption * option,
1239  PBoolean overwrite = false
1240  ) { PWaitAndSignal m(m_mutex); MakeUnique(); return m_info != NULL && m_info->AddOption(option, overwrite); }
1241 
1245  bool HasOption(const PString & name) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->FindOption(name) != NULL; }
1246 
1250  OpalMediaOption * FindOption(
1251  const PString & name
1252  ) const { PWaitAndSignal m(m_mutex); return m_info == NULL ? NULL : m_info->FindOption(name); }
1253 
1257  template <class T> T * FindOptionAs(
1258  const PString & name
1259  ) const { return dynamic_cast<T *>(FindOption(name)); }
1260 
1266  bool IsValidForProtocol(const PString & protocol) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->IsValidForProtocol(protocol); }
1267 
1268  time_t GetCodecVersionTime() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? 0 : m_info->codecVersionTime; }
1269 
1270  ostream & PrintOptions(ostream & strm) const
1271  {
1272  PWaitAndSignal m(m_mutex);
1273  if (m_info != NULL)
1274  strm << setw(-1) << *m_info;
1275  return strm;
1276  }
1277 
1278 #if OPAL_VIDEO
1279 
1281  void AdjustVideoArgs(
1282  PVideoDevice::OpenArgs & args
1283  ) const;
1284 #endif
1285 
1286  // Backward compatibility
1287  virtual PBoolean IsEmpty() const { PWaitAndSignal m(m_mutex); return m_info == NULL || !m_info->IsValid(); }
1288  operator PString() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? "" : m_info->formatName; }
1289  operator const char *() const { PWaitAndSignal m(m_mutex); return m_info == NULL ? "" : m_info->formatName; }
1290  bool operator==(const char * other) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->formatName == other; }
1291  bool operator!=(const char * other) const { PWaitAndSignal m(m_mutex); return m_info == NULL || m_info->formatName != other; }
1292  bool operator==(const PString & other) const { PWaitAndSignal m(m_mutex); return m_info != NULL && m_info->formatName == other; }
1293  bool operator!=(const PString & other) const { PWaitAndSignal m(m_mutex); return m_info == NULL || m_info->formatName != other; }
1294  bool operator==(const OpalMediaFormat & other) const { PWaitAndSignal m(m_mutex); return Compare(other) == EqualTo; }
1295  bool operator!=(const OpalMediaFormat & other) const { PWaitAndSignal m(m_mutex); return Compare(other) != EqualTo; }
1296  friend bool operator==(const char * other, const OpalMediaFormat & fmt) { return fmt.m_info != NULL && fmt.m_info->formatName == other; }
1297  friend bool operator!=(const char * other, const OpalMediaFormat & fmt) { return fmt.m_info == NULL || fmt.m_info->formatName != other; }
1298  friend bool operator==(const PString & other, const OpalMediaFormat & fmt) { return fmt.m_info != NULL && fmt.m_info->formatName == other; }
1299  friend bool operator!=(const PString & other, const OpalMediaFormat & fmt) { return fmt.m_info == NULL || fmt.m_info->formatName != other; }
1300 
1301 #if OPAL_H323
1302  static const PString & MediaPacketizationOption();
1303  static const PString & MediaPacketizationsOption();
1304  PStringArray GetMediaPacketizations() const;
1305  PStringSet GetMediaPacketizationSet() const { return PStringSet(GetMediaPacketizations()); }
1306  void SetMediaPacketizations(const PStringSet & packetizations);
1307 #endif
1308 
1309  private:
1310  PBoolean SetSize(PINDEX) { return true; }
1311 
1312  protected:
1313  void Construct(OpalMediaFormatInternal * info);
1314 
1315  OpalMediaFormatInternal * m_info;
1316  PMutex m_mutex;
1317 
1318  friend class OpalMediaFormatInternal;
1319  friend class OpalMediaFormatList;
1320 };
1321 
1322 
1323 class OpalAudioFormatInternal : public OpalMediaFormatInternal
1324 {
1325  public:
1326  OpalAudioFormatInternal(
1327  const char * fullName,
1328  RTP_DataFrame::PayloadTypes rtpPayloadType,
1329  const char * encodingName,
1330  PINDEX frameSize,
1331  unsigned frameTime,
1332  unsigned rxFrames,
1333  unsigned txFrames,
1334  unsigned maxFrames,
1335  unsigned clockRate,
1336  time_t timeStamp = 0
1337  );
1338  virtual PObject * Clone() const;
1339  virtual bool Merge(const OpalMediaFormatInternal & mediaFormat);
1340 };
1341 
1342 class OpalAudioFormat : public OpalMediaFormat
1343 {
1344  PCLASSINFO(OpalAudioFormat, OpalMediaFormat);
1345  public:
1346  OpalAudioFormat(
1347  OpalMediaFormatInternal * info = NULL
1348  ) : OpalMediaFormat(info) { }
1349  OpalAudioFormat(
1350  const char * fullName,
1351  RTP_DataFrame::PayloadTypes rtpPayloadType,
1352  const char * encodingName,
1353  PINDEX frameSize,
1354  unsigned frameTime,
1355  unsigned rxFrames,
1356  unsigned txFrames,
1357  unsigned maxFrames = 256,
1358  unsigned clockRate = 8000,
1359  time_t timeStamp = 0
1360  );
1361 
1362  static const PString & RxFramesPerPacketOption();
1363  static const PString & TxFramesPerPacketOption();
1364  static const PString & MaxFramesPerPacketOption();
1365  static const PString & ChannelsOption();
1366 };
1367 
1368 #if OPAL_VIDEO
1369 class OpalVideoFormatInternal : public OpalMediaFormatInternal
1370 {
1371  public:
1372  OpalVideoFormatInternal(
1373  const char * fullName,
1374  RTP_DataFrame::PayloadTypes rtpPayloadType,
1375  const char * encodingName,
1376  unsigned maxFrameWidth,
1377  unsigned maxFrameHeight,
1378  unsigned maxFrameRate,
1379  unsigned maxBitRate,
1380  time_t timeStamp = 0
1381  );
1382  virtual PObject * Clone() const;
1383  virtual bool Merge(const OpalMediaFormatInternal & mediaFormat);
1384 };
1385 
1386 
1387 class OpalVideoFormat : public OpalMediaFormat
1388 {
1389  PCLASSINFO(OpalVideoFormat, OpalMediaFormat);
1390  public:
1391  OpalVideoFormat(
1392  OpalMediaFormatInternal * info = NULL
1393  ) : OpalMediaFormat(info) { }
1394  OpalVideoFormat(
1395  const char * fullName,
1396  RTP_DataFrame::PayloadTypes rtpPayloadType,
1397  const char * encodingName,
1398  unsigned maxFrameWidth,
1399  unsigned maxFrameHeight,
1400  unsigned maxFrameRate,
1401  unsigned maxBitRate,
1402  time_t timeStamp = 0
1403  );
1404 
1405  static const PString & FrameWidthOption();
1406  static const PString & FrameHeightOption();
1407  static const PString & MinRxFrameWidthOption();
1408  static const PString & MinRxFrameHeightOption();
1409  static const PString & MaxRxFrameWidthOption();
1410  static const PString & MaxRxFrameHeightOption();
1411  static const PString & TemporalSpatialTradeOffOption();
1412  static const PString & TxKeyFramePeriodOption();
1413  static const PString & RateControlPeriodOption(); // Period over which the rate controller maintains the target bit rate.
1414  static const PString & RateControllerOption(); // String for controller algorithm. Empty is none.
1415 
1426  P_DECLARE_STREAMABLE_ENUM(ContentRole,
1427  eNoRole,
1428  ePresentation,
1429  eMainRole,
1430  eSpeaker,
1431  eSignLanguage
1432  );
1433 
1434  enum { ContentRoleMask = 15 };
1435  __inline static unsigned ContentRoleBit(ContentRole contentRole) { return contentRole != eNoRole ? (1<<(contentRole-1)) : 0; }
1436  static const PString & ContentRoleOption();
1437  static const PString & ContentRoleMaskOption();
1438 
1440  P_DECLARE_STREAMABLE_BITWISE_ENUM_EX(
1441  RTCPFeedback,
1442  7,
1443  (
1444  e_NoRTCPFb,
1445  e_PLI,
1446  e_FIR,
1447  e_TMMBR,
1448  e_TSTR,
1449  e_VBCM,
1450  e_NACK,
1451  e_SLI
1452  ),
1453  "", "pli", "fir", "tmmbr", "tstr", "vcbm", "nack", "sli"
1454  );
1456  static const PString & RTCPFeedbackOption();
1457 };
1458 #endif
1459 
1460 
1461 #include <codec/known.h>
1462 
1463 
1464 extern const OpalAudioFormat & GetOpalPCM16();
1465 extern const OpalAudioFormat & GetOpalPCM16S();
1466 extern const OpalAudioFormat & GetOpalPCM16_16KHZ();
1467 extern const OpalAudioFormat & GetOpalPCM16S_16KHZ();
1468 extern const OpalAudioFormat & GetOpalPCM16_32KHZ();
1469 extern const OpalAudioFormat & GetOpalPCM16S_32KHZ();
1470 extern const OpalAudioFormat & GetOpalPCM16_48KHZ();
1471 extern const OpalAudioFormat & GetOpalPCM16S_48KHZ();
1472 extern const OpalAudioFormat & GetOpalL16_MONO_8KHZ();
1473 extern const OpalAudioFormat & GetOpalL16_STEREO_8KHZ();
1474 extern const OpalAudioFormat & GetOpalL16_MONO_16KHZ();
1475 extern const OpalAudioFormat & GetOpalL16_STEREO_16KHZ();
1476 extern const OpalAudioFormat & GetOpalL16_MONO_32KHZ();
1477 extern const OpalAudioFormat & GetOpalL16_STEREO_32KHZ();
1478 extern const OpalAudioFormat & GetOpalL16_MONO_48KHZ();
1479 extern const OpalAudioFormat & GetOpalL16_STEREO_48KHZ();
1480 extern const OpalAudioFormat & GetOpalG711_ULAW_64K();
1481 extern const OpalAudioFormat & GetOpalG711_ALAW_64K();
1482 extern const OpalAudioFormat & GetOpalG722();
1483 extern const OpalAudioFormat & GetOpalG7221_24K();
1484 extern const OpalAudioFormat & GetOpalG7221_32K();
1485 extern const OpalAudioFormat & GetOpalG7221_48K();
1486 extern const OpalAudioFormat & GetOpalG7222();
1487 extern const OpalAudioFormat & GetOpalG726_40K();
1488 extern const OpalAudioFormat & GetOpalG726_32K();
1489 extern const OpalAudioFormat & GetOpalG726_24K();
1490 extern const OpalAudioFormat & GetOpalG726_16K();
1491 extern const OpalAudioFormat & GetOpalG728();
1492 extern const OpalAudioFormat & GetOpalG729();
1493 extern const OpalAudioFormat & GetOpalG729A();
1494 extern const OpalAudioFormat & GetOpalG729B();
1495 extern const OpalAudioFormat & GetOpalG729AB();
1496 extern const OpalAudioFormat & GetOpalG7231_6k3();
1497 extern const OpalAudioFormat & GetOpalG7231_5k3();
1498 extern const OpalAudioFormat & GetOpalG7231A_6k3();
1499 extern const OpalAudioFormat & GetOpalG7231A_5k3();
1500 extern const OpalAudioFormat & GetOpalGSM0610();
1501 extern const OpalAudioFormat & GetOpalGSMAMR();
1502 extern const OpalAudioFormat & GetOpaliLBC();
1503 
1504 #if OPAL_VIDEO
1505 extern const OpalVideoFormat & GetOpalH261();
1506 extern const OpalVideoFormat & GetOpalH263();
1507 extern const OpalVideoFormat & GetOpalH263plus();
1508 extern const OpalVideoFormat & GetOpalH264_MODE0();
1509 extern const OpalVideoFormat & GetOpalH264_MODE1();
1510 extern const OpalVideoFormat & GetOpalMPEG4();
1511 #endif // OPAL_VIDEO
1512 
1513 extern const OpalMediaFormat & GetOpalRFC2833();
1514 
1515 #if OPAL_T38_CAPABILITY
1516 extern const OpalMediaFormat & GetOpalCiscoNSE();
1517 extern const OpalMediaFormat & GetOpalT38();
1518 #endif
1519 
1520 
1521 #define OpalPCM16 GetOpalPCM16()
1522 #define OpalPCM16S GetOpalPCM16S()
1523 #define OpalPCM16_16KHZ GetOpalPCM16_16KHZ()
1524 #define OpalPCM16S_16KHZ GetOpalPCM16S_16KHZ()
1525 #define OpalPCM16_32KHZ GetOpalPCM16_32KHZ()
1526 #define OpalPCM16S_32KHZ GetOpalPCM16S_32KHZ()
1527 #define OpalPCM16_48KHZ GetOpalPCM16_48KHZ()
1528 #define OpalPCM16S_48KHZ GetOpalPCM16S_48KHZ()
1529 #define OpalL16_MONO_8KHZ GetOpalL16_MONO_8KHZ()
1530 #define OpalL16_STEREO_8KHZ GetOpalL16_STEREO_8KHZ()
1531 #define OpalL16_MONO_16KHZ GetOpalL16_MONO_16KHZ()
1532 #define OpalL16_STEREO_16KHZ GetOpalL16_STEREO_16KHZ()
1533 #define OpalL16_MONO_32KHZ GetOpalL16_MONO_32KHZ()
1534 #define OpalL16_STEREO_32KHZ GetOpalL16_STEREO_32KHZ()
1535 #define OpalL16_MONO_48KHZ GetOpalL16_MONO_48KHZ()
1536 #define OpalL16_STEREO_48KHZ GetOpalL16_STEREO_48KHZ()
1537 #define OpalG711_ULAW_64K GetOpalG711_ULAW_64K()
1538 #define OpalG711_ALAW_64K GetOpalG711_ALAW_64K()
1539 #define OpalG722 GetOpalG722()
1540 #define OpalG7221 OpalG7221_32K
1541 #define OpalG7221_24K GetOpalG7221_24K()
1542 #define OpalG7221_32K GetOpalG7221_32K()
1543 #define OpalG7221_48K GetOpalG7221_48K()
1544 #define OpalG7222 GetOpalG7222()
1545 #define OpalG726_40K GetOpalG726_40K()
1546 #define OpalG726_32K GetOpalG726_32K()
1547 #define OpalG726_24K GetOpalG726_24K()
1548 #define OpalG726_16K GetOpalG726_16K()
1549 #define OpalG728 GetOpalG728()
1550 #define OpalG729 GetOpalG729()
1551 #define OpalG729A GetOpalG729A()
1552 #define OpalG729B GetOpalG729B()
1553 #define OpalG729AB GetOpalG729AB()
1554 #define OpalG7231_6k3 GetOpalG7231_6k3()
1555 #define OpalG7231_5k3 GetOpalG7231_5k3()
1556 #define OpalG7231A_6k3 GetOpalG7231A_6k3()
1557 #define OpalG7231A_5k3 GetOpalG7231A_5k3()
1558 #define OpalGSM0610 GetOpalGSM0610()
1559 #define OpalGSMAMR GetOpalGSMAMR()
1560 #define OpaliLBC GetOpaliLBC()
1561 #define OpalRFC2833 GetOpalRFC2833()
1562 #define OpalCiscoNSE GetOpalCiscoNSE()
1563 #define OpalT38 GetOpalT38()
1564 
1565 #if OPAL_VIDEO
1566 #define OpalH261 GetOpalH261()
1567 #define OpalH263 GetOpalH263()
1568 #define OpalH263plus GetOpalH263plus()
1569 #define OpalH264 GetOpalH264_MODE1()
1570 #define OpalH264_MODE0 GetOpalH264_MODE0()
1571 #define OpalH264_MODE1 GetOpalH264_MODE1()
1572 #define OpalMPEG4 GetOpalMPEG4()
1573 #endif
1574 
1575 #define OpalL16Mono8kHz OpalL16_MONO_8KHZ
1576 #define OpalL16Mono16kHz OpalL16_MONO_16KHZ
1577 #define OpalG711uLaw OpalG711_ULAW_64K
1578 #define OpalG711ALaw OpalG711_ALAW_64K
1579 
1580 
1581 #endif // OPAL_OPAL_MEDIAFMT_H
1582 
1583 
1584 // End of File ///////////////////////////////////////////////////////////////