OpalMediaStream Class Reference

#include <mediastrm.h>

Inheritance diagram for OpalMediaStream:


Construction
	~OpalMediaStream ()
	OpalMediaStream (OpalConnection &conn, const OpalMediaFormat &mediaFormat, unsigned sessionID, bool isSource)
Public Member Functions
Overrides from PObject
void	PrintOn (ostream &strm) const
Operations
virtual OpalMediaFormat	GetMediaFormat () const
virtual bool	UpdateMediaFormat (const OpalMediaFormat &mediaFormat, bool fromPatch=false)
virtual PBoolean	ExecuteCommand (const OpalMediaCommand &command)
virtual void	SetCommandNotifier (const PNotifier &notifier)
virtual PBoolean	Open ()
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 void	EnableJitterBuffer () 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
virtual void	SetPaused (bool pause)
bool	IsOpen () const
virtual PBoolean	SetPatch (OpalMediaPatch *patch)
virtual void	RemovePatch (OpalMediaPatch *patch)
OpalMediaPatch *	GetPatch () const
void	AddFilter (const PNotifier &Filter, const OpalMediaFormat &Stage=OpalMediaFormat())
bool	RemoveFilter (const PNotifier &Filter, const OpalMediaFormat &Stage)
virtual void	GetStatistics (OpalMediaStatistics &statistics, bool fromPatch=false) const
Protected Member Functions
void	IncrementTimestamp (PINDEX size)
Protected Attributes
OpalConnection &	connection
unsigned	sessionID
PString	identifier
OpalMediaFormat	mediaFormat
bool	paused
bool	isSource
bool	isOpen
PINDEX	defaultDataSize
unsigned	timestamp
bool	marker
unsigned	mismatchedPayloadTypes
OpalMediaPatch *	mediaPatch
PNotifier	commandNotifier
RTP_DataFrame::PayloadTypes	m_payloadType
unsigned	m_frameTime
PINDEX	m_frameSize

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.

Constructor & Destructor Documentation

OpalMediaStream::OpalMediaStream	(	OpalConnection &	conn,
		const OpalMediaFormat &	mediaFormat,
		unsigned	sessionID,
		bool	isSource
	)			`[protected]`

Construct a new media stream.

Parameters:

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()`
	)

Add a filter to the owning patch safely.

virtual PBoolean OpalMediaStream::Close ( ) [virtual]

Close the media stream.

The default does nothing.

Reimplemented in OpalH224MediaStream, OpalIAX2MediaStream, OpalMSRPMediaStream, OpalLineMediaStream, OpalRTPMediaStream, OpalRawMediaStream, OpalVideoMediaStream, OpalUDPMediaStream, and OpalMixerMediaStream.

virtual void OpalMediaStream::EnableJitterBuffer ( ) const [virtual]

Enable jitter buffer for the media stream.

The default behaviour does nothing.

Reimplemented in OpalRTPMediaStream.

virtual PBoolean OpalMediaStream::ExecuteCommand ( const OpalMediaCommand & command ) [virtual]

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

The default behaviour passes the command on to the OpalMediaPatch.

Parameters:

command

Command to execute.

OpalConnection& OpalMediaStream::GetConnection ( ) const [inline]

Get the owner 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.

PString OpalMediaStream::GetID ( ) const [inline]

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

bool OpalMediaStream::GetMarker ( ) const [inline]

Get the marker bit of last read.

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".

OpalMediaPatch* OpalMediaStream::GetPatch ( ) const [inline]

Get the patch thread that is using the stream.

unsigned OpalMediaStream::GetSessionID ( ) const [inline]

Get the session number of the stream.

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.

void OpalMediaStream::IncrementTimestamp ( PINDEX size ) [protected]

bool OpalMediaStream::IsOpen ( ) const [inline]

Returns true if the media stream is open.

bool OpalMediaStream::IsPaused ( ) const [inline]

Get the paused state for stream.

bool OpalMediaStream::IsSink ( ) const [inline]

Determine of media stream is a source or a sink.

bool OpalMediaStream::IsSource ( ) const [inline]

Determine of media stream is a source or a sink.

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 OpalH224MediaStream, OpalIAX2MediaStream, OpalIMMediaStream, OpalLineMediaStream, OpalIVRMediaStream, OpalLocalMediaStream, OpalNullMediaStream, OpalRTPMediaStream, OpalFileMediaStream, OpalVideoMediaStream, OpalUDPMediaStream, and OpalMixerMediaStream.

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 OpalIAX2MediaStream, OpalMSRPMediaStream, OpalLineMediaStream, OpalIVRMediaStream, OpalRTPMediaStream, OpalVideoMediaStream, and OpalMixerMediaStream.

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 OpalLineMediaStream, OpalLocalMediaStream, OpalNullMediaStream, OpalRawMediaStream, OpalFileMediaStream, and OpalVideoMediaStream.

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 OpalH224MediaStream, OpalIAX2MediaStream, OpalIMMediaStream, OpalMSRPMediaStream, OpalLineMediaStream, OpalLocalMediaStream, OpalRTPMediaStream, and OpalUDPMediaStream.

bool OpalMediaStream::RemoveFilter	(	const PNotifier &	Filter,
		const OpalMediaFormat &	Stage
	)

Remove a filter from the owning patch safely.

virtual void OpalMediaStream::RemovePatch ( OpalMediaPatch * patch ) [virtual]

Remove the patch thread that is using this stream. This function is useful in case of streams which can be accessed by multiple instances of OpalMediaPatch.

The default behaviour simply sets patchThread to NULL.

virtual PBoolean OpalMediaStream::RequiresPatchThread ( ) const [virtual]

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

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 void OpalMediaStream::SetCommandNotifier ( const PNotifier & notifier ) [virtual]

Set a notifier to receive commands generated by the transcoder. The commands are highly context sensitive, for example VideoFastUpdate would only apply to a video transcoder.

The default behaviour passes the command on to the OpalMediaPatch and sets the member variable commandNotifier.

Parameters:

notifier

Command to execute.

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 OpalLineMediaStream, OpalRTPMediaStream, and OpalVideoMediaStream.

void OpalMediaStream::SetMarker ( bool m ) [inline]

Set marker bit for next write.

virtual PBoolean OpalMediaStream::SetPatch ( OpalMediaPatch * patch ) [virtual]

Set the patch thread that is using this stream.

Parameters:

patch

Media patch thread

Reimplemented in OpalRTPMediaStream.

virtual void OpalMediaStream::SetPaused ( bool pause ) [virtual]

Set the paused state for stream. This will stop reading/writing data from the stream.

Parameters:

pause

Indicate that the stream should be paused

Reimplemented in OpalRTPMediaStream.

void OpalMediaStream::SetSessionID ( unsigned id ) [inline]

Get the session number of the stream.

void OpalMediaStream::SetTimestamp ( unsigned ts ) [inline]

Set timestamp for next write.

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 OpalIAX2MediaStream.

virtual bool OpalMediaStream::UpdateMediaFormat	(	const OpalMediaFormat &	mediaFormat,
		bool	fromPatch = `false`
	)			`[virtual]`

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 then a OpalMediaFormat::Merge() is performed.

The default behaviour updates the mediaFormat member variable and pases the value on to the OpalMediaPatch.

Parameters:

mediaFormat	New media format
fromPatch	Is being called from OpalMediaPatch

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 OpalIAX2MediaStream, OpalLineMediaStream, OpalLocalMediaStream, OpalNullMediaStream, OpalRawMediaStream, OpalFileMediaStream, and OpalVideoMediaStream.

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 OpalH224MediaStream, OpalIMMediaStream, OpalMSRPMediaStream, OpalLineMediaStream, OpalLocalMediaStream, OpalRTPMediaStream, OpalUDPMediaStream, and OpalMixerMediaStream.