OpalMediaStream Class Reference

#include <mediastrm.h>

Inheritance diagram for OpalMediaStream:

Collaboration diagram for OpalMediaStream:

Public Member Functions
virtual bool	InternalUpdateMediaFormat (const OpalMediaFormat &mediaFormat)
virtual bool	InternalSetPaused (bool pause, bool fromUser, bool fromPatch)
virtual bool	InternalExecuteCommand (const OpalMediaCommand &command)
Overrides from PObject
void	PrintOn (ostream &strm) const
Operations
virtual OpalMediaFormat	GetMediaFormat () const
virtual bool	SetMediaFormat (const OpalMediaFormat &mediaFormat)
bool	UpdateMediaFormat (const OpalMediaFormat &mediaFormat, bool mergeOnly=false)
bool	ExecuteCommand (const OpalMediaCommand &command) const
virtual PBoolean	Open ()
virtual bool	IsOpen () const
virtual PBoolean	Start ()
virtual PBoolean	Close ()
virtual void	OnStartMediaPatch ()
virtual void	OnStopMediaPatch (OpalMediaPatch &patch)
virtual PBoolean	WritePackets (RTP_DataFrameList &packets)
virtual PBoolean	ReadPacket (RTP_DataFrame &packet)
virtual PBoolean	WritePacket (RTP_DataFrame &packet)
virtual PBoolean	ReadData (BYTE *data, PINDEX size, PINDEX &length)
virtual PBoolean	WriteData (const BYTE *data, PINDEX length, PINDEX &written)
bool	PushPacket (RTP_DataFrame &packet)
virtual PBoolean	SetDataSize (PINDEX dataSize, PINDEX frameTime)
PINDEX	GetDataSize () const
virtual PBoolean	IsSynchronous () const =0
virtual PBoolean	RequiresPatchThread (OpalMediaStream *stream) const
virtual PBoolean	RequiresPatchThread () const
virtual bool	EnableJitterBuffer (bool enab=true) const
Member variable access
OpalConnection &	GetConnection () const
bool	IsSource () const
bool	IsSink () const
unsigned	GetSessionID () const
void	SetSessionID (unsigned id)
PString	GetID () const
unsigned	GetTimestamp () const
void	SetTimestamp (unsigned ts)
bool	GetMarker () const
void	SetMarker (bool m)
bool	IsPaused () const
bool	SetPaused (bool pause)
virtual PBoolean	SetPatch (OpalMediaPatch *patch)
OpalMediaPatchPtr	GetPatch () const
void	AddFilter (const PNotifier &filter, const OpalMediaFormat &stage=OpalMediaFormat()) const
bool	RemoveFilter (const PNotifier &filter, const OpalMediaFormat &stage=OpalMediaFormat()) const
virtual void	GetStatistics (OpalMediaStatistics &statistics, bool fromPatch=false) const
	P_DECLARE_BITWISE_ENUM (Details, 6,(DetailMinimum, DetailEOL, DetailNAT, DetailSecured, DetailFEC, DetailAudio, DetailAddresses))
virtual void	PrintDetail (ostream &strm, const char *prefix=NULL, Details details=Details::All()) const

Protected Types
typedef OpalMediaPatchPtr	PatchPtr

Protected Member Functions
void	IncrementTimestamp (PINDEX size)
bool	InternalWriteData (const BYTE *data, PINDEX length, PINDEX &written)
OpalMediaPatchPtr	InternalSetPatchPart1 (OpalMediaPatch *newPatch)
void	InternalSetPatchPart2 (const OpalMediaPatchPtr &oldPatch)
virtual bool	InternalSetJitterBuffer (const OpalJitterBuffer::Init &init) const
virtual void	InternalClose ()=0

Protected Attributes
OpalConnection &	connection
unsigned	sessionID
WORD	m_sequenceNumber
PString	identifier
OpalMediaFormat	mediaFormat
bool	m_paused
bool	m_isSource
bool	m_isOpen
PINDEX	m_defaultDataSize
unsigned	timestamp
bool	marker
OpalMediaPatchPtr	m_mediaPatch
RTP_DataFrame::PayloadTypes	m_payloadType
unsigned	m_frameTime
PINDEX	m_frameSize

Friends
class	OpalMediaPatch

Construction
	OpalMediaStream (OpalConnection &conn, const OpalMediaFormat &mediaFormat, unsigned sessionID, bool isSource)
	~OpalMediaStream ()

Detailed Description

This class describes a media stream as used in the OPAL system. A media stream is the channel through which media data is trasferred between OPAL entities. For example, data being sent to an RTP session over a network would be through a media stream.

Member Typedef Documentation

typedef OpalMediaPatchPtr OpalMediaStream::PatchPtr

protected

Constructor & Destructor Documentation

OpalMediaStream::OpalMediaStream ( OpalConnection &  conn, const OpalMediaFormat &  mediaFormat, unsigned  sessionID, bool  isSource  )

protected

Construct a new media stream.

Parameters

conn	Connection that owns the stream
mediaFormat	Media format for stream
sessionID	Session number for stream
isSource	Is a source stream

OpalMediaStream::~OpalMediaStream

(

)

Destroy the media stream. Make sure the patch, if present, has been stopped and deleted.

Member Function Documentation

void OpalMediaStream::AddFilter	(	const PNotifier &	filter,
		const OpalMediaFormat &	stage = OpalMediaFormat()
	)		const

Add a filter to the owning patch safely.

Parameters

filter	Filter notifier to be called.
stage	Stage in codec pipeline to call filter

virtual PBoolean OpalMediaStream::Close ( )

virtual

Close the media stream.

The default marks the stream as closed and calls OpalConnection::OnClosedMediaStream().

virtual bool OpalMediaStream::EnableJitterBuffer ( bool  enab = true ) const

virtual

Enable jitter buffer for the media stream. Returns true if a jitter buffer is enabled. Returns false if the jitter buffer is disabled or no jitter buffer can be used on the media stream.

The default behaviour does nothing and returns false.

bool OpalMediaStream::ExecuteCommand

(

const OpalMediaCommand &

command

)

const

Execute the command specified to the transcoder. The commands are highly context sensitive, for example OpalVideoUpdatePicture would only apply to a video transcoder.

The default behaviour passes the command on to the OpalMediaPatch.

Returns

true if command is handled.

Parameters

command

Command to execute.

OpalConnection& OpalMediaStream::GetConnection ( ) const

inline

Get the owner connection.

References connection.

PINDEX OpalMediaStream::GetDataSize ( ) const

inline

Get the data size in bytes that is expected to be used. Some media streams can make use of this information to perform optimisations.

References m_defaultDataSize.

PString OpalMediaStream::GetID ( ) const

inline

Get the ID associated with this stream. Used for detecting two the streams associated with a bidirectional media channel

References identifier.

bool OpalMediaStream::GetMarker ( ) const

inline

Get the marker bit of last read.

References marker.

virtual OpalMediaFormat OpalMediaStream::GetMediaFormat ( ) const

virtual

Get the currently selected media format. The media data format is a string representation of the format being transferred by the media channel. It is typically a value as provided by the RTP_PayloadType class.

The default behaviour simply returns the member variable "mediaFormat".

OpalMediaPatchPtr OpalMediaStream::GetPatch ( ) const

inline

Get the patch thread that is using the stream.

References m_mediaPatch.

unsigned OpalMediaStream::GetSessionID ( ) const

inline

Get the session number of the stream.

References sessionID.

virtual void OpalMediaStream::GetStatistics ( OpalMediaStatistics &  statistics, bool  fromPatch = false  ) const

virtual

Reimplemented in OpalRTPMediaStream.

unsigned OpalMediaStream::GetTimestamp ( ) const

inline

Get the timestamp of last read.

References timestamp.

void OpalMediaStream::IncrementTimestamp ( PINDEX  size )

protected

virtual void OpalMediaStream::InternalClose ( )

protectedpure virtual

Close any internal components of the stream. This should be used in preference to overriding the Close() function as it is guaranteed to be called exactly once and avoids race conditions in the shut down sequence of a media stream.

Implemented in OpalMixerMediaStream, OpalVideoMediaStream, OpalLocalMediaStream, OpalRawMediaStream, OpalRTPMediaStream, OpalLineMediaStream, OpalNullMediaStream, OpalIVRMediaStream, OpalMSRPMediaStream, OpalIAX2MediaStream, and OpalT140MediaStream.

virtual bool OpalMediaStream::InternalExecuteCommand ( const OpalMediaCommand &  command )

virtual

Reimplemented in OpalVideoMediaStream.

virtual bool OpalMediaStream::InternalSetJitterBuffer ( const OpalJitterBuffer::Init &  init ) const

protectedvirtual

Reimplemented in OpalMixerMediaStream, and OpalRTPMediaStream.

OpalMediaPatchPtr OpalMediaStream::InternalSetPatchPart1 ( OpalMediaPatch *  newPatch )

protected

void OpalMediaStream::InternalSetPatchPart2 ( const OpalMediaPatchPtr &  oldPatch )

protected

virtual bool OpalMediaStream::InternalSetPaused ( bool  pause, bool  fromUser, bool  fromPatch  )

virtual

Reimplemented in OpalRTPMediaStream, and OpalNullMediaStream.

Referenced by SetPaused().

virtual bool OpalMediaStream::InternalUpdateMediaFormat ( const OpalMediaFormat &  mediaFormat )

virtual

Reimplemented in OpalVideoMediaStream, and OpalNullMediaStream.

bool OpalMediaStream::InternalWriteData ( const BYTE *  data, PINDEX  length, PINDEX &  written  )

protected

virtual bool OpalMediaStream::IsOpen ( ) const

virtual

Returns true if the media stream is open.

Reimplemented in OpalRTPMediaStream.

bool OpalMediaStream::IsPaused ( ) const

inline

Get the paused state for stream.

References m_paused.

bool OpalMediaStream::IsSink ( ) const

inline

Determine of media stream is a source or a sink.

References m_isSource.

Referenced by OpalH224MediaStream::RequiresPatchThread(), and OpalMSRPMediaStream::RequiresPatchThread().

bool OpalMediaStream::IsSource ( ) const

inline

Determine of media stream is a source or a sink.

References m_isSource.

virtual PBoolean OpalMediaStream::IsSynchronous ( ) const

pure virtual

Indicate if the media stream is synchronous. If this returns true then the media stream will block of the amount of time it takes to annunciate the data. For example if the media stream is over a sound card, and 480 bytes of data are to be written it will take 30 milliseconds to complete.

Implemented in OpalUDPMediaStream, OpalMixerMediaStream, OpalVideoMediaStream, OpalLocalMediaStream, OpalFileMediaStream, OpalRTPMediaStream, OpalLineMediaStream, OpalNullMediaStream, OpalIVRMediaStream, OpalMSRPMediaStream, OpalH224MediaStream, OpalIAX2MediaStream, and OpalT140MediaStream.

virtual void OpalMediaStream::OnStartMediaPatch ( )

virtual

Callback that is called on the source stream once the media patch has started. The default behaviour calls OpalConnection::OnMediaPatchStart()

Reimplemented in OpalH224MediaStream.

virtual void OpalMediaStream::OnStopMediaPatch ( OpalMediaPatch &  patch )

virtual

Callback that is called on the source stream once the media patch has started. The default behaviour calls OpalConnection::OnMediaPatchStop()

Parameters

patch

Media patch that is stopping

virtual PBoolean OpalMediaStream::Open ( )

virtual

Open the media stream using the media format.

The default behaviour simply sets the isOpen variable to true.

Reimplemented in OpalMixerMediaStream, OpalVideoMediaStream, OpalRTPMediaStream, OpalLineMediaStream, OpalIVRMediaStream, and OpalMSRPMediaStream.

OpalMediaStream::P_DECLARE_BITWISE_ENUM	(	Details	,
		6	,
		(DetailMinimum, DetailEOL, DetailNAT, DetailSecured, DetailFEC, DetailAudio, DetailAddresses)
	)

virtual void OpalMediaStream::PrintDetail ( ostream &  strm, const char *  prefix = NULL, Details  details = Details::All()  ) const

virtual

void OpalMediaStream::PrintOn

(

ostream &

strm

)

const

Standard stream print function. The PObject class has a << operator defined that calls this function polymorphically.

Parameters

strm	Stream to output text representation

bool OpalMediaStream::PushPacket

(

RTP_DataFrame &

packet

)

Pushes a frame to the patch

virtual PBoolean OpalMediaStream::ReadData ( BYTE *  data, PINDEX  size, PINDEX &  length  )

virtual

Read raw media data from the source media stream. The default behaviour simply calls ReadPacket() on the data portion of the RTP_DataFrame and sets the frames timestamp and marker from the internal member variables of the media stream class.

Parameters

data	Data buffer to read to
size	Size of buffer
length	Length of data actually read

Reimplemented in OpalVideoMediaStream, OpalLocalMediaStream, OpalFileMediaStream, OpalRawMediaStream, OpalLineMediaStream, and OpalNullMediaStream.

virtual PBoolean OpalMediaStream::ReadPacket ( RTP_DataFrame &  packet )

virtual

Read an RTP frame of data from the source media stream. The default behaviour simply calls ReadData() on the data portion of the RTP_DataFrame and sets the frames timestamp and marker from the internal member variables of the media stream class.

Reimplemented in OpalUDPMediaStream, OpalLocalMediaStream, OpalRTPMediaStream, OpalLineMediaStream, OpalMSRPMediaStream, OpalH224MediaStream, OpalIAX2MediaStream, and OpalT140MediaStream.

bool OpalMediaStream::RemoveFilter	(	const PNotifier &	filter,
		const OpalMediaFormat &	stage = OpalMediaFormat()
	)		const

Remove a filter from the owning patch safely.

Parameters

filter	Filter notifier to be called.
stage	Stage in codec pipeline to call filter

virtual PBoolean OpalMediaStream::RequiresPatchThread ( OpalMediaStream *  stream ) const

virtual

Indicate if the media stream requires a OpalMediaPatch thread (active patch). This is called on the source/sink stream and is passed the sink/source stream that the patch will initially be using. The function could conditionally require the patch thread to execute a thread reading and writing data, or prevent it from doing so as it can do so in hardware in some way, e.g. both streams are on the same OpalLineInterfaceDevice.

The default behaviour simply returns true.

Parameters

stream

Other stream in patch

Reimplemented in OpalLineMediaStream.

virtual PBoolean OpalMediaStream::RequiresPatchThread ( ) const

virtual

Reimplemented in OpalMixerMediaStream, OpalRTPMediaStream, OpalNullMediaStream, OpalMSRPMediaStream, OpalH224MediaStream, and OpalT140MediaStream.

virtual PBoolean OpalMediaStream::SetDataSize ( PINDEX  dataSize, PINDEX  frameTime  )

virtual

Set the data size in bytes that is expected to be used. Some media streams can make use of this information to perform optimisations.

The default behaviour does nothing.

Parameters

dataSize	New data size (in total)
frameTime	Individual frame time (if applicable)

Reimplemented in OpalVideoMediaStream, OpalRTPMediaStream, and OpalLineMediaStream.

void OpalMediaStream::SetMarker ( bool  m )

inline

Set marker bit for next write.

References marker.

virtual bool OpalMediaStream::SetMediaFormat ( const OpalMediaFormat &  mediaFormat )

virtual

Set a new media format for the stream. Unlike UpdateMediaFormat() this will shut down the patch and attempt to create new transcoders to meet the requirement.

Returns

false if the no transcoding can be found.

Parameters

mediaFormat

New media format

virtual PBoolean OpalMediaStream::SetPatch ( OpalMediaPatch *  patch )

virtual

Set the patch thread that is using this stream.

Parameters

patch

Media patch thread

Reimplemented in OpalRTPMediaStream.

bool OpalMediaStream::SetPaused ( bool  pause )

inline

Set the paused state for stream. This will stop reading/writing data from the stream. Returns true if the pause state was changed

Parameters

pause

Indicate that the stream should be paused

References InternalSetPaused().

void OpalMediaStream::SetSessionID ( unsigned  id )

inline

Get the session number of the stream.

void OpalMediaStream::SetTimestamp ( unsigned  ts )

inline

Set timestamp for next write.

References timestamp.

virtual PBoolean OpalMediaStream::Start ( )

virtual

Start the media stream.

The default behaviour calls Resume() on the associated OpalMediaPatch thread if it was suspended.

Reimplemented in OpalMixerMediaStream.

bool OpalMediaStream::UpdateMediaFormat	(	const OpalMediaFormat &	mediaFormat,
		bool	mergeOnly = false
	)

Update the media format. This can be used to adjust the parameters of a codec at run time. Note you cannot change the basic media format, eg change GSM0610 to G.711, only options for that format, eg 6k3 mode to 5k3 mode in G.723.1.

If the formats are different, or the mergeOnly parameter is true, then a OpalMediaFormat::Merge() rather than OpalMediaFormat::Update() is performed.

Parameters

mediaFormat	New media format
mergeOnly	Indicate merge parameters

virtual PBoolean OpalMediaStream::WriteData ( const BYTE *  data, PINDEX  length, PINDEX &  written  )

virtual

Write raw media data to the sink media stream. The default behaviour calls WritePacket() on the data portion of the RTP_DataFrame and and sets the internal timestamp and marker from the member variables of the media stream class.

Parameters

data	Data to write
length	Length of data to read.
written	Length of data actually written

Reimplemented in OpalVideoMediaStream, OpalLocalMediaStream, OpalFileMediaStream, OpalRawMediaStream, OpalLineMediaStream, OpalNullMediaStream, and OpalIAX2MediaStream.

virtual PBoolean OpalMediaStream::WritePacket ( RTP_DataFrame &  packet )

virtual

Write an RTP frame of data to the sink media stream. The default behaviour simply calls WriteData() on the data portion of the RTP_DataFrame and and sets the internal timestamp and marker from the member variables of the media stream class.

Reimplemented in OpalUDPMediaStream, OpalMixerMediaStream, OpalLocalMediaStream, OpalRTPMediaStream, OpalLineMediaStream, OpalMSRPMediaStream, OpalH224MediaStream, and OpalT140MediaStream.

virtual PBoolean OpalMediaStream::WritePackets ( RTP_DataFrameList &  packets )

virtual

Write a list of RTP frames of data to the sink media stream. The default behaviour simply calls WritePacket() on each of the elements in the list.

Friends And Related Function Documentation

friend class OpalMediaPatch

friend

Field Documentation

OpalConnection& OpalMediaStream::connection

protected

Referenced by GetConnection().

PString OpalMediaStream::identifier

protected

Referenced by GetID().

PINDEX OpalMediaStream::m_defaultDataSize

protected

Referenced by GetDataSize().

PINDEX OpalMediaStream::m_frameSize

protected

unsigned OpalMediaStream::m_frameTime

protected

bool OpalMediaStream::m_isOpen

protected

bool OpalMediaStream::m_isSource

protected

Referenced by IsSink(), and IsSource().

OpalMediaPatchPtr OpalMediaStream::m_mediaPatch

protected

Referenced by GetPatch().

bool OpalMediaStream::m_paused

protected

Referenced by IsPaused().

RTP_DataFrame::PayloadTypes OpalMediaStream::m_payloadType

protected

WORD OpalMediaStream::m_sequenceNumber

protected

bool OpalMediaStream::marker

protected

Referenced by GetMarker(), and SetMarker().

OpalMediaFormat OpalMediaStream::mediaFormat

protected

unsigned OpalMediaStream::sessionID

protected

Referenced by GetSessionID().

unsigned OpalMediaStream::timestamp

protected

Referenced by GetTimestamp(), and SetTimestamp().

---

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

• mediastrm.h