OpalMediaPatch Class Reference

#include <patch.h>

Inheritance diagram for OpalMediaPatch:

[legend]
Collaboration diagram for OpalMediaPatch:
[legend]

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)
OpalMediaStreamGetSource () 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 PBoolean ExecuteCommand (const OpalMediaCommand &command, PBoolean fromSink)
virtual bool SetPaused (bool pause)
virtual PBoolean PushFrame (RTP_DataFrame &frame)
bool SetBypassPatch (const OpalMediaPatchPtr &patch)
virtual OpalTranscoderGetAndLockSinkTranscoder (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)
virtual void Main ()
void StopThread ()
bool DispatchFrame (RTP_DataFrame &frame)

Protected Attributes

OpalMediaStreamsource
PList< Sinksinks
PList< Filterfilters
OpalMediaPatchPtr m_bypassToPatch
OpalMediaPatchPtr m_bypassFromPatch
PSyncPoint m_bypassEnded
PThread * patchThread
PMutex patchThreadMutex

Data Structures

class  Filter
class  Sink

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.

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.

bool OpalMediaPatch::DispatchFrame ( RTP_DataFrame frame  )  [protected]

bool OpalMediaPatch::EnableJitterBuffer ( bool  enab = true  ) 

virtual PBoolean OpalMediaPatch::ExecuteCommand ( const OpalMediaCommand command,
PBoolean  fromSink 
) [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.
fromSink  Flag for source or sink

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.

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

void OpalMediaPatch::InternalOnMediaCommand2 ( OpalMediaCommand command  )  [protected]

virtual void OpalMediaPatch::Main (  )  [protected, virtual]

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_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 bool OpalMediaPatch::SetPaused ( bool  pause  )  [virtual]

Set streams to paused.

Parameters:
pause  Indicate that the stream should be paused

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

PList<Filter> OpalMediaPatch::filters [protected]

PSyncPoint OpalMediaPatch::m_bypassEnded [protected]

OpalMediaPatchPtr OpalMediaPatch::m_bypassFromPatch [protected]

OpalMediaPatchPtr OpalMediaPatch::m_bypassToPatch [protected]

PThread* OpalMediaPatch::patchThread [protected]

PMutex OpalMediaPatch::patchThreadMutex [protected]

PList<Sink> OpalMediaPatch::sinks [protected]

OpalMediaStream& OpalMediaPatch::source [protected]


The documentation for this class was generated from the following file:
Generated on 21 Jun 2013 for OPAL by  doxygen 1.4.7