OpalMediaPatch Class Reference

#include <patch.h>

Inheritance diagram for OpalMediaPatch:

Collaboration diagram for OpalMediaPatch:

Data Structures
class	Filter
class	Sink

Public Member Functions
Construction
	OpalMediaPatch (OpalMediaStream &source)
	~OpalMediaPatch ()
Overrides from PObject
void	PrintOn (ostream &strm) const
Operations
virtual void	Start ()
virtual bool	OnStartMediaPatch ()
virtual void	Close ()
PBoolean	AddSink (const OpalMediaStreamPtr &stream)
void	RemoveSink (const OpalMediaStream &stream)
OpalMediaStream &	GetSource () const
OpalMediaStreamPtr	GetSink (PINDEX i=0) const
OpalMediaFormat	GetSinkFormat (PINDEX i=0) const
void	AddFilter (const PNotifier &filter, const OpalMediaFormat &stage=OpalMediaFormat())
bool	RemoveFilter (const PNotifier &filter, const OpalMediaFormat &stage=OpalMediaFormat())
virtual void	FilterFrame (RTP_DataFrame &frame, const OpalMediaFormat &mediaFormat)
virtual bool	UpdateMediaFormat (const OpalMediaFormat &mediaFormat)
virtual bool	ExecuteCommand (const OpalMediaCommand &command)
virtual bool	InternalSetPaused (bool pause, bool fromUser)
virtual PBoolean	PushFrame (RTP_DataFrame &frame)
bool	SetBypassPatch (const OpalMediaPatchPtr &patch)
bool	IsBypassed () const
virtual OpalTranscoder *	GetAndLockSinkTranscoder (PINDEX i=0) const
virtual void	UnLockSinkTranscoder () const
virtual bool	ResetTranscoders ()
bool	EnableJitterBuffer (bool enab=true)
virtual void	GetStatistics (OpalMediaStatistics &statistics, bool fromSink) const

Protected Member Functions
	PDECLARE_NOTIFIER (OpalMediaCommand, OpalMediaPatch, InternalOnMediaCommand1)
void	InternalOnMediaCommand2 (OpalMediaCommand *command)
bool	CanStart () const
virtual void	Main ()
void	StopThread ()
bool	DispatchFrame (RTP_DataFrame &frame)
bool	DispatchFrameLocked (RTP_DataFrame &frame, bool bypassing)
	PDECLARE_MUTEX (m_patchThreadMutex)

Protected Attributes
OpalMediaStream &	m_source
PList< Sink >	m_sinks
PList< Filter >	m_filters
OpalMediaPatchPtr	m_bypassToPatch
OpalMediaPatchPtr	m_bypassFromPatch
PSyncPoint	m_bypassEnded
PThread *	m_patchThread
PThreadIdentifier	m_patchThreadId
bool	m_transcoderChanged

Detailed Description

Media stream "patch cord". This class is the thread of control that transfers data from one "source" OpalMediStream to one or more other "sink" OpalMediStream instances. It may use zero, one or two intermediary software codecs for each sink stream in order to match the media data formats the streams are capabile of doing natively.

Note the thread is not actually started straight away. It is expected that the Start() function is called on the patch when the creator code is ready for it to begin. For example all sink streams have been added.

Constructor & Destructor Documentation

OpalMediaPatch::OpalMediaPatch

(

OpalMediaStream &

source

)

Create a new patch. Note the thread is not started here.

Parameters

source

Source media stream

OpalMediaPatch::~OpalMediaPatch

(

)

Destroy patch.

Member Function Documentation

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

Add a filter to the media pipeline. Use PDECLARE_NOTIFIER(RTP_DataFrame, YourClass, YourFunction) for the filter function notifier.

Parameters

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

PBoolean OpalMediaPatch::AddSink

(

const OpalMediaStreamPtr &

stream

)

Add another "sink" OpalMediaStream to patch. The stream must not be a ReadOnly media stream for the patch to be able to write to it.

Parameters

stream

Media stream to add.

bool OpalMediaPatch::CanStart ( ) const

protected

virtual void OpalMediaPatch::Close ( )

virtual

Close the patch. This is an internal function that closes all of the sink streams and waits for the the thread to terminate. It is called when the source stream is called.

Reimplemented in OpalPassiveMediaPatch.

bool OpalMediaPatch::DispatchFrame ( RTP_DataFrame &  frame )

protected

bool OpalMediaPatch::DispatchFrameLocked ( RTP_DataFrame &  frame, bool  bypassing  )

protected

bool OpalMediaPatch::EnableJitterBuffer

(

bool

enab = true

)

virtual bool OpalMediaPatch::ExecuteCommand ( const OpalMediaCommand &  command )

virtual

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 source or sinks and the sinks transcoders.

Returns

true if command is handled.

Parameters

command

Command to execute.

virtual void OpalMediaPatch::FilterFrame ( RTP_DataFrame &  frame, const OpalMediaFormat &  mediaFormat  )

virtual

Filter a frame. Calls all filter functions.

virtual OpalTranscoder* OpalMediaPatch::GetAndLockSinkTranscoder ( PINDEX  i = 0 ) const

virtual

Get the transcoder used within a sink stream

OpalMediaStreamPtr OpalMediaPatch::GetSink

(

PINDEX

i = 0

)

const

Get the media stream for a sink stream

OpalMediaFormat OpalMediaPatch::GetSinkFormat

(

PINDEX

i = 0

)

const

Get the media format for a sink stream

OpalMediaStream& OpalMediaPatch::GetSource ( ) const

inline

Get the current source stream for patch.

References m_source.

virtual void OpalMediaPatch::GetStatistics ( OpalMediaStatistics &  statistics, bool  fromSink  ) const

virtual

void OpalMediaPatch::InternalOnMediaCommand2 ( OpalMediaCommand *  command )

protected

virtual bool OpalMediaPatch::InternalSetPaused ( bool  pause, bool  fromUser  )

virtual

Set streams to paused.

Parameters

pause	Indicate that the stream should be paused
fromUser	Pause is from user, not internal logic

bool OpalMediaPatch::IsBypassed ( ) const

inline

References m_bypassFromPatch, and m_bypassToPatch.

virtual void OpalMediaPatch::Main ( )

protectedvirtual

Called from the associated patch thread

virtual bool OpalMediaPatch::OnStartMediaPatch ( )

virtual

Indicate the patch has started. Typically called from the beginning of the patch thread.

Default behaviour make sure jitter buffer is created.

Returns bool indicating all media streams are asynchronous so the patch should assure no thread startvation

OpalMediaPatch::PDECLARE_MUTEX ( m_patchThreadMutex  )

protected

OpalMediaPatch::PDECLARE_NOTIFIER ( OpalMediaCommand  , OpalMediaPatch  , InternalOnMediaCommand1    )

protected

void OpalMediaPatch::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

virtual PBoolean OpalMediaPatch::PushFrame ( RTP_DataFrame &  frame )

virtual

Push a frame out to all the sink streams, transcoding as necessary.

Parameters

frame

Frame to push

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

Remove a filter from the media pipeline.

Parameters

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

void OpalMediaPatch::RemoveSink

(

const OpalMediaStream &

stream

)

Add existing "sink" OpalMediaStream to patch. If the stream is not a sink of this patch then this function does nothing.

Parameters

stream

Media stream to remove

virtual bool OpalMediaPatch::ResetTranscoders ( )

virtual

bool OpalMediaPatch::SetBypassPatch

(

const OpalMediaPatchPtr &

patch

)

Set bypass patch instance.

This can be useful for back to back calls that happen to be the same media format and you wish to avoid double decoding and encoding of media. Note this scenario is not the same as two OpalConnections within the same OpalCall, but two completely independent OpalCall where one connection is to be bypassed. For example, two OpalCall instances might have two SIPConnection instances and two OpalMixerConnection instances connected via a single OpalMixerNode. Now while there are ONLY two calls in the node, it is a waste to decode the audio, add to mixer and re-encode it again. In practice this is identical to just bypassing the mixer node completely, until a third party is added, then we need to switch back to normal (non-bypassed) operation.

Note it is up to the caller to assure the patch instance lifetimes are correct for the bypass.

Returns

true if bypass was set, false if conflict with another bypass.

virtual void OpalMediaPatch::Start ( )

virtual

Start the patch. The default implementation simply starts the patch thread, which in turn calls Main()

Reimplemented in OpalPassiveMediaPatch.

void OpalMediaPatch::StopThread ( )

protected

virtual void OpalMediaPatch::UnLockSinkTranscoder ( ) const

virtual

virtual bool OpalMediaPatch::UpdateMediaFormat ( const OpalMediaFormat &  mediaFormat )

virtual

Update the source/sink 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 then a OpalMediaFormat::Merge() is performed.

The default behaviour updates the source/sink media stream and the output side of any relevant transcoders.

Parameters

mediaFormat

New media format

Field Documentation

PSyncPoint OpalMediaPatch::m_bypassEnded

protected

OpalMediaPatchPtr OpalMediaPatch::m_bypassFromPatch

protected

Referenced by IsBypassed().

OpalMediaPatchPtr OpalMediaPatch::m_bypassToPatch

protected

Referenced by IsBypassed().

PList<Filter> OpalMediaPatch::m_filters

protected

PThread* OpalMediaPatch::m_patchThread

protected

PThreadIdentifier OpalMediaPatch::m_patchThreadId

protected

PList<Sink> OpalMediaPatch::m_sinks

protected

OpalMediaStream& OpalMediaPatch::m_source

protected

Referenced by GetSource().

bool OpalMediaPatch::m_transcoderChanged

protected

---

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

• patch.h