OpalMediaFormat Class Reference

#include <mediafmt.h>

Inheritance diagram for OpalMediaFormat:

OpalAudioFormat OpalH224MediaFormat OpalPluginMediaFormat

List of all members.

Public Types

enum  StandardClockRate { AudioClockRate = 8000, VideoClockRate = 90000 }

Public Member Functions

 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)
OpalMediaFormatoperator= (RTP_DataFrame::PayloadTypes rtpPayloadType)
OpalMediaFormatoperator= (const char *wildcard)
OpalMediaFormatoperator= (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 Merge (const OpalMediaFormat &mediaFormat)
PString GetName () const
PBoolean IsValid () const
PBoolean IsTransportable () const
RTP_DataFrame::PayloadTypes GetPayloadType () const
void SetPayloadType (RTP_DataFrame::PayloadTypes type)
const char * GetEncodingName () const
OpalMediaType GetMediaType () const
bool NeedsJitterBuffer () const
unsigned GetBandwidth () const
PINDEX GetFrameSize () const
unsigned GetFrameTime () const
unsigned GetTimeUnits () const
unsigned GetClockRate () const
PStringToString GetOptions () const
PINDEX GetOptionCount () const
const OpalMediaOptionGetOption (PINDEX index) const
bool GetOptionValue (const PString &name, PString &value) const
bool SetOptionValue (const PString &name, const PString &value)
bool GetOptionBoolean (const PString &name, bool dflt=PFalse) const
bool SetOptionBoolean (const PString &name, bool value)
int GetOptionInteger (const PString &name, int dflt=0) const
bool SetOptionInteger (const PString &name, int value)
double GetOptionReal (const PString &name, double dflt=0) const
bool SetOptionReal (const PString &name, double value)
PINDEX GetOptionEnum (const PString &name, PINDEX dflt=0) const
bool SetOptionEnum (const PString &name, PINDEX value)
PString GetOptionString (const PString &name, const PString &dflt=PString::Empty()) const
bool SetOptionString (const PString &name, const PString &value)
bool GetOptionOctets (const PString &name, PBYTEArray &octets) const
bool SetOptionOctets (const PString &name, const PBYTEArray &octets)
bool SetOptionOctets (const PString &name, const BYTE *data, PINDEX length)
bool AddOption (OpalMediaOption *option, PBoolean overwrite=PFalse)
bool HasOption (const PString &name) const
OpalMediaOptionFindOption (const PString &name) const
bool IsValidForProtocol (const PString &protocol) const
time_t GetCodecVersionTime () const
ostream & PrintOptions (ostream &strm) const
virtual PBoolean IsEmpty () const
 operator PString () const
 operator const char * () const
bool operator== (const char *other) const
bool operator!= (const char *other) const
bool operator== (const PString &other) const
bool operator!= (const PString &other) const
bool operator== (const OpalMediaFormat &other) const
bool operator!= (const OpalMediaFormat &other) const

Static Public Member Functions

static const PString & BandwidthTIASOption ()
static const PString & MaxPacketRateOption ()
static const PString & NeedsJitterOption ()
static const PString & MaxBitRateOption ()
static const PString & TargetBitRateOption ()
static const PString & MaxFrameSizeOption ()
static const PString & FrameTimeOption ()
static const PString & ClockRateOption ()
static OpalMediaFormatList GetAllRegisteredMediaFormats ()
static void GetAllRegisteredMediaFormats (OpalMediaFormatList &copy)
static bool SetRegisteredMediaFormat (const OpalMediaFormat &mediaFormat)

Protected Member Functions

void Construct (OpalMediaFormatInternal *info)

Protected Attributes

PMutex _mutex
OpalMediaFormatInternalm_info

Friends

class OpalMediaFormatInternal
class OpalMediaFormatList
bool operator== (const char *other, const OpalMediaFormat &fmt)
bool operator!= (const char *other, const OpalMediaFormat &fmt)
bool operator== (const PString &other, const OpalMediaFormat &fmt)
bool operator!= (const PString &other, const OpalMediaFormat &fmt)


Detailed Description

This class describes a media format as used in the OPAL system. A media format is the type of any media data that is trasferred between OPAL entities. For example an audio codec such as G.723.1 is a media format, a video codec such as H.261 is also a media format.

Member Enumeration Documentation

Enumerator:
AudioClockRate  8kHz sample rate
VideoClockRate  90kHz sample rate


Constructor & Destructor Documentation

OpalMediaFormat::OpalMediaFormat ( OpalMediaFormatInternal info = NULL  ) 

Default constructor creates a PCM-16 media format.

OpalMediaFormat::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 
)

This form of the constructor will register the full details of the media format into an internal database. This would typically be used as a static global. In fact it would be very dangerous for an instance to use this constructor in any other way, especially local variables.

If the rtpPayloadType is RTP_DataFrame::DynamicBase, then the RTP payload type is actually set to the first unused dynamic RTP payload type that is in the registers set of media formats.

The frameSize parameter indicates that the media format has a maximum size for each data frame, eg G.723.1 frames are no more than 24 bytes long. If zero then there is no intrinsic maximum, eg G.711.

Parameters:
fullName Full name of media format
mediaType media type for this format
rtpPayloadType RTP payload type code
encodingName RTP encoding name
needsJitter Indicate format requires a jitter buffer
bandwidth Bandwidth in bits/second
frameSize Size of frame in bytes (if applicable)
frameTime Time for frame in RTP units (if applicable)
clockRate Clock rate for data (if applicable)
timeStamp timestamp (for versioning)

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

Construct a media format, searching database for information. This constructor will search through the RegisteredMediaFormats list for the match of the payload type, if found the other information fields are set from the database. If not found then the ancestor string is set to the empty string.

Note it is impossible to determine the order of registration so this should not be relied on.

Parameters:
rtpPayloadType RTP payload type code
clockRate clock rate
rtpEncodingName RTP payload type name
protocol valid protocol (if NULL, then all)

OpalMediaFormat::OpalMediaFormat ( const char *  wildcard  ) 

Construct a media format, searching database for information. This constructor will search through the RegisteredMediaFormats list for the wildcard match of the parameter string, if found the other information fields are set from the database. If not found then the ancestor string is set to the empty string.

The wildcard string is a simple substring match using the '*' character. For example: "G.711*" would match the first of "G.711-uLaw-64k" and "G.711-ALaw-64k" to have been registered.

Note it is impossible to determine the order of registration so this should not be relied on.

Parameters:
wildcard Wildcard name to search for

OpalMediaFormat::OpalMediaFormat ( const PString &  wildcard  ) 

Construct a media format, searching database for information. This constructor will search through the RegisteredMediaFormats list for the wildcard match of the parameter string, if found the other information fields are set from the database. If not found then the ancestor string is set to the empty string.

The wildcard string is a simple substring match using the '*' character. For example: "G.711*" would match the first of "G.711-uLaw-64k" and "G.711-ALaw-64k" to have been registered.

Note it is impossible to determine the order of registration so this should not be relied on.

Parameters:
wildcard Wildcard name to search for


Member Function Documentation

bool OpalMediaFormat::AddOption ( OpalMediaOption option,
PBoolean  overwrite = PFalse 
) [inline]

Add a new option to this media format

References _mutex, OpalMediaFormatInternal::AddOption(), and m_info.

static const PString& OpalMediaFormat::BandwidthTIASOption (  )  [static]

static const PString& OpalMediaFormat::ClockRateOption (  )  [static]

Referenced by GetClockRate().

virtual PObject* OpalMediaFormat::Clone (  )  const [virtual]

Create a copy of the media format.

Reimplemented in OpalH224MediaFormat.

virtual Comparison OpalMediaFormat::Compare ( const PObject &  obj  )  const [virtual]

Compare two media formats.

Referenced by operator!=(), and operator==().

void OpalMediaFormat::Construct ( OpalMediaFormatInternal info  )  [protected]

OpalMediaOption* OpalMediaFormat::FindOption ( const PString &  name  )  const [inline]

Get a pointer to the specified media format option. Returns NULL if thee option does not exist.

References _mutex, OpalMediaFormatInternal::FindOption(), and m_info.

static const PString& OpalMediaFormat::FrameTimeOption (  )  [static]

Referenced by GetFrameTime().

static void OpalMediaFormat::GetAllRegisteredMediaFormats ( OpalMediaFormatList copy  )  [static]

Parameters:
copy List to receive the copy of the master list

static OpalMediaFormatList OpalMediaFormat::GetAllRegisteredMediaFormats (  )  [static]

Get a copy of the list of media formats that have been registered.

unsigned OpalMediaFormat::GetBandwidth (  )  const [inline]

Get the average bandwidth used in bits/second.

References _mutex, OpalMediaFormatInternal::GetOptionInteger(), m_info, and MaxBitRateOption().

unsigned OpalMediaFormat::GetClockRate (  )  const [inline]

Get the clock rate in Hz for this format.

References _mutex, ClockRateOption(), OpalMediaFormatInternal::GetOptionInteger(), and m_info.

Referenced by GetTimeUnits().

time_t OpalMediaFormat::GetCodecVersionTime (  )  const [inline]

const char* OpalMediaFormat::GetEncodingName (  )  const [inline]

Get the RTP encoding name that is to be used for this media format.

References _mutex, m_info, and OpalMediaFormatInternal::rtpEncodingName.

PINDEX OpalMediaFormat::GetFrameSize (  )  const [inline]

Get the maximum frame size in bytes. If this returns zero then the media format has no intrinsic maximum frame size, eg G.711 would return zero but G.723.1 whoud return 24.

References _mutex, OpalMediaFormatInternal::GetOptionInteger(), m_info, and MaxFrameSizeOption().

unsigned OpalMediaFormat::GetFrameTime (  )  const [inline]

Get the frame time in RTP timestamp units. If this returns zero then the media format is not real time and has no intrinsic timing eg T.120

References _mutex, FrameTimeOption(), OpalMediaFormatInternal::GetOptionInteger(), and m_info.

OpalMediaType OpalMediaFormat::GetMediaType (  )  const [inline]

Get the media type for this format

References _mutex, m_info, and OpalMediaFormatInternal::mediaType.

PString OpalMediaFormat::GetName (  )  const [inline]

Get the name of the format

References _mutex, OpalMediaFormatInternal::formatName, and m_info.

Referenced by MakeOpalTranscoderKey().

const OpalMediaOption& OpalMediaFormat::GetOption ( PINDEX  index  )  const [inline]

Get the option instance at the specified index. This contains the description and value for the option.

Parameters:
index Index of option in list to get

References _mutex, m_info, and OpalMediaFormatInternal::options.

bool OpalMediaFormat::GetOptionBoolean ( const PString &  name,
bool  dflt = PFalse 
) const [inline]

Get the option value of the specified name as a boolean. The default value is returned if the option is not present.

Parameters:
name Option name
dflt Default value if option not present

References _mutex, OpalMediaFormatInternal::GetOptionBoolean(), and m_info.

PINDEX OpalMediaFormat::GetOptionCount (  )  const [inline]

Get the number of options this media format has.

References _mutex, m_info, and OpalMediaFormatInternal::options.

PINDEX OpalMediaFormat::GetOptionEnum ( const PString &  name,
PINDEX  dflt = 0 
) const [inline]

Get the option value of the specified name as an index into an enumeration list. The default value is returned if the option is not present.

Parameters:
name Option name
dflt Default value if option not present

References _mutex, OpalMediaFormatInternal::GetOptionEnum(), and m_info.

int OpalMediaFormat::GetOptionInteger ( const PString &  name,
int  dflt = 0 
) const [inline]

Get the option value of the specified name as an integer. The default value is returned if the option is not present.

Parameters:
name Option name
dflt Default value if option not present

References _mutex, OpalMediaFormatInternal::GetOptionInteger(), and m_info.

bool OpalMediaFormat::GetOptionOctets ( const PString &  name,
PBYTEArray &  octets 
) const [inline]

Get the option value of the specified name as an octet array. Returns PFalse if not present.

Parameters:
name Option name
octets Octets in option

References _mutex, OpalMediaFormatInternal::GetOptionOctets(), and m_info.

double OpalMediaFormat::GetOptionReal ( const PString &  name,
double  dflt = 0 
) const [inline]

Get the option value of the specified name as a real. The default value is returned if the option is not present.

Parameters:
name Option name
dflt Default value if option not present

References _mutex, OpalMediaFormatInternal::GetOptionReal(), and m_info.

PStringToString OpalMediaFormat::GetOptions (  )  const [inline]

Get all of the option values of the format as a dictionary. Each entry is a name value pair.

References _mutex, OpalMediaFormatInternal::GetOptions(), and m_info.

PString OpalMediaFormat::GetOptionString ( const PString &  name,
const PString &  dflt = PString::Empty() 
) const [inline]

Get the option value of the specified name as a string. The default value is returned if the option is not present.

Parameters:
name Option name
dflt Default value if option not present

References _mutex, OpalMediaFormatInternal::GetOptionString(), and m_info.

bool OpalMediaFormat::GetOptionValue ( const PString &  name,
PString &  value 
) const [inline]

Get the option value of the specified name as a string.

Returns false of the option is not present.

Parameters:
name Option name
value String to receive option value

References _mutex, OpalMediaFormatInternal::GetOptionValue(), and m_info.

RTP_DataFrame::PayloadTypes OpalMediaFormat::GetPayloadType (  )  const [inline]

Get the RTP payload type that is to be used for this media format. This will either be an intrinsic one for the media format eg GSM or it will be automatically calculated as a dynamic media format that will be uniqueue amongst the registered media formats.

References _mutex, RTP_DataFrame::IllegalPayloadType, m_info, and OpalMediaFormatInternal::rtpPayloadType.

unsigned OpalMediaFormat::GetTimeUnits (  )  const [inline]

Get the number of RTP timestamp units per millisecond.

References GetClockRate().

bool OpalMediaFormat::HasOption ( const PString &  name  )  const [inline]

Determine if media format has the specified option.

References _mutex, OpalMediaFormatInternal::FindOption(), and m_info.

virtual PBoolean OpalMediaFormat::IsEmpty (  )  const [inline, virtual]

PBoolean OpalMediaFormat::IsTransportable (  )  const [inline]

Return PTrue if media format info may be sent via RTP. Some formats are internal use only and are never transported "over the wire".

References _mutex, OpalMediaFormatInternal::IsTransportable(), and m_info.

PBoolean OpalMediaFormat::IsValid (  )  const [inline]

Return PTrue if media format info is valid. This may be used if the single string constructor is used to check that it matched something in the registered media formats database.

References _mutex, OpalMediaFormatInternal::IsValid(), and m_info.

bool OpalMediaFormat::IsValidForProtocol ( const PString &  protocol  )  const [inline]

Returns PTrue if the media format is valid for the protocol specified This allow plugin codecs to customise which protocols they are valid for The default implementation returns true unless the protocol is H.323 and the rtpEncodingName is NULL

Reimplemented in OpalH224MediaFormat.

References _mutex, OpalMediaFormatInternal::IsValidForProtocol(), and m_info.

static const PString& OpalMediaFormat::MaxBitRateOption (  )  [static]

Referenced by GetBandwidth().

static const PString& OpalMediaFormat::MaxFrameSizeOption (  )  [static]

Referenced by GetFrameSize().

static const PString& OpalMediaFormat::MaxPacketRateOption (  )  [static]

bool OpalMediaFormat::Merge ( const OpalMediaFormat mediaFormat  ) 

Merge with another media format. This will alter and validate the options for this media format according to the merge rule for each option. The parameter is typically a "capability" while the current object isthe proposed channel format. This if the current object has a tx number of frames of 3, but the parameter has a value of 1, then the current object will be set to 1.

Returns PFalse if the media formats are incompatible and cannot be merged.

bool OpalMediaFormat::NeedsJitterBuffer (  )  const [inline]

Determine if the media format requires a jitter buffer. As a rule an audio codec needs a jitter buffer and all others do not.

References _mutex, OpalMediaFormatInternal::GetOptionBoolean(), m_info, and NeedsJitterOption().

static const PString& OpalMediaFormat::NeedsJitterOption (  )  [static]

Referenced by NeedsJitterBuffer().

OpalMediaFormat::operator const char * (  )  const [inline]

OpalMediaFormat::operator PString (  )  const [inline]

bool OpalMediaFormat::operator!= ( const OpalMediaFormat other  )  const [inline]

References _mutex, and Compare().

bool OpalMediaFormat::operator!= ( const PString &  other  )  const [inline]

bool OpalMediaFormat::operator!= ( const char *  other  )  const [inline]

OpalMediaFormat& OpalMediaFormat::operator= ( const PString &  wildcard  ) 

Search for the specified format name. This is equivalent to going fmt = OpalMediaFormat(search);

Parameters:
wildcard Wildcard name to search for

OpalMediaFormat& OpalMediaFormat::operator= ( const char *  wildcard  ) 

Search for the specified format name. This is equivalent to going fmt = OpalMediaFormat(search);

Parameters:
wildcard Wildcard name to search for

OpalMediaFormat& OpalMediaFormat::operator= ( RTP_DataFrame::PayloadTypes  rtpPayloadType  ) 

Search for the specified format type. This is equivalent to going fmt = OpalMediaFormat(rtpPayloadType);

Parameters:
rtpPayloadType RTP payload type code

bool OpalMediaFormat::operator== ( const OpalMediaFormat other  )  const [inline]

References _mutex, and Compare().

bool OpalMediaFormat::operator== ( const PString &  other  )  const [inline]

bool OpalMediaFormat::operator== ( const char *  other  )  const [inline]

virtual void OpalMediaFormat::PrintOn ( ostream &  strm  )  const [virtual]

Print media format. Note if the user specifies a width (using setw() for example) of -1, then a details multi-line output of all the options for the format is included.

ostream& OpalMediaFormat::PrintOptions ( ostream &  strm  )  const [inline]

References _mutex, and m_info.

virtual void OpalMediaFormat::ReadFrom ( istream &  strm  )  [virtual]

Read media format.

bool OpalMediaFormat::SetOptionBoolean ( const PString &  name,
bool  value 
) [inline]

Set the option value of the specified name as a boolean. Note the option will not be added if it does not exist, the option must be explicitly added using AddOption().

Returns false of the option is not present or is not of the same type.

Parameters:
name Option name
value New value for option

References _mutex, m_info, and OpalMediaFormatInternal::SetOptionBoolean().

bool OpalMediaFormat::SetOptionEnum ( const PString &  name,
PINDEX  value 
) [inline]

Set the option value of the specified name as an index into an enumeration. Note the option will not be added if it does not exist, the option must be explicitly added using AddOption().

Returns false of the option is not present or is not of the same type.

Parameters:
name Option name
value New value for option

References _mutex, m_info, and OpalMediaFormatInternal::SetOptionEnum().

bool OpalMediaFormat::SetOptionInteger ( const PString &  name,
int  value 
) [inline]

Set the option value of the specified name as an integer. Note the option will not be added if it does not exist, the option must be explicitly added using AddOption().

Returns false of the option is not present, not of the same type or is putside the allowable range.

Parameters:
name Option name
value New value for option

References _mutex, m_info, and OpalMediaFormatInternal::SetOptionInteger().

bool OpalMediaFormat::SetOptionOctets ( const PString &  name,
const BYTE *  data,
PINDEX  length 
) [inline]

Parameters:
name Option name
data Octets in option
length Number of octets

References _mutex, m_info, and OpalMediaFormatInternal::SetOptionOctets().

bool OpalMediaFormat::SetOptionOctets ( const PString &  name,
const PBYTEArray &  octets 
) [inline]

Set the option value of the specified name as an octet array. Note the option will not be added if it does not exist, the option must be explicitly added using AddOption().

Returns false of the option is not present or is not of the same type.

Parameters:
name Option name
octets Octets in option

References _mutex, m_info, and OpalMediaFormatInternal::SetOptionOctets().

bool OpalMediaFormat::SetOptionReal ( const PString &  name,
double  value 
) [inline]

Set the option value of the specified name as a real. Note the option will not be added if it does not exist, the option must be explicitly added using AddOption().

Returns false of the option is not present or is not of the same type.

Parameters:
name Option name
value New value for option

References _mutex, m_info, and OpalMediaFormatInternal::SetOptionReal().

bool OpalMediaFormat::SetOptionString ( const PString &  name,
const PString &  value 
) [inline]

Set the option value of the specified name as a string. Note the option will not be added if it does not exist, the option must be explicitly added using AddOption().

Returns false of the option is not present or is not of the same type.

Parameters:
name Option name
value New value for option

References _mutex, m_info, and OpalMediaFormatInternal::SetOptionString().

bool OpalMediaFormat::SetOptionValue ( const PString &  name,
const PString &  value 
) [inline]

Set the option value of the specified name as a string. Note the option will not be added if it does not exist, the option must be explicitly added using AddOption().

Returns false of the option is not present.

Parameters:
name Option name
value New option value as string

References _mutex, m_info, and OpalMediaFormatInternal::SetOptionValue().

void OpalMediaFormat::SetPayloadType ( RTP_DataFrame::PayloadTypes  type  )  [inline]

static bool OpalMediaFormat::SetRegisteredMediaFormat ( const OpalMediaFormat mediaFormat  )  [static]

Set the options on the master format list entry. The media format must already be registered. Returns false if not.

Parameters:
mediaFormat Media format to copy to master list

static const PString& OpalMediaFormat::TargetBitRateOption (  )  [static]

bool OpalMediaFormat::ToCustomisedOptions (  ) 

This will do the reverse of ToNormalisedOptions, translating the OPAL "normalised" options to codec specific "custom" options.

bool OpalMediaFormat::ToNormalisedOptions (  ) 

This will translate the codec specific "custom" options to OPAL "normalised" options, e.g. For H.261 "QCIF MPI"="1", "CIF MPI"="5" would be translated to "Frame Width"="176", "Frame Height"="144".


Friends And Related Function Documentation

friend class OpalMediaFormatInternal [friend]

friend class OpalMediaFormatList [friend]

bool operator!= ( const PString &  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 char *  other,
const OpalMediaFormat fmt 
) [friend]


Member Data Documentation

PMutex OpalMediaFormat::_mutex [protected]


The documentation for this class was generated from the following file:

Generated on Fri Apr 10 21:32:55 2009 for OPAL by  doxygen 1.5.8