# OpalMediaStream Class Reference

`#include <mediastrm.h>`

Inheritance diagram for OpalMediaStream:

[legend]
Collaboration diagram for OpalMediaStream:
[legend]

## Construction

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

## Public Member Functions

virtual bool | InternalUpdateMediaFormat (const OpalMediaFormat &mediaFormat)
Overrides from PObject
void | PrintOn (ostream &strm) const
Operations
virtual OpalMediaFormat | GetMediaFormat () const
virtual bool | SetMediaFormat (const OpalMediaFormat &mediaFormat)
bool | UpdateMediaFormat (const OpalMediaFormat &mediaFormat)
virtual PBoolean | ExecuteCommand (const OpalMediaCommand &command)
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
virtual bool | SetPaused (bool pause, bool fromPatch=false)
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

## 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
PString | identifier
OpalMediaFormat | mediaFormat
bool | m_paused
bool | m_isSource
bool | m_isOpen
PINDEX | defaultDataSize
unsigned | timestamp
bool | marker
OpalMediaPatchPtr | m_mediaPatch
RTP_DataFrame::PayloadTypes | m_payloadType
unsigned | m_frameTime
PINDEX | m_frameSize

## Friends

class | OpalMediaPatch

## 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/disabled. Returns false if no jitter buffer exists for the media stream.

The default behaviour does nothing and returns false.

virtual PBoolean OpalMediaStream::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 OpalMediaPatch.

Returns:
  true if command is handled.

Parameters:

  command | Command to execute.

Reimplemented in OpalVideoMediaStream.

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

OpalMediaPatchPtr 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]`

virtual void OpalMediaStream::InternalClose | ( |  | ) | `[protected, pure 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 OpalIVRMediaStream, OpalLocalMediaStream, OpalMixerMediaStream, OpalIAX2MediaStream, OpalMSRPMediaStream, OpalT140MediaStream, OpalLineMediaStream, OpalNullMediaStream, OpalRTPMediaStream, OpalRawMediaStream, OpalVideoMediaStream, and OpalFaxMediaStream.

virtual bool OpalMediaStream::InternalSetJitterBuffer | ( | const OpalJitterBuffer::Init & | init | ) | const`[protected, virtual]`

Reimplemented in OpalMixerMediaStream, and OpalRTPMediaStream.

OpalMediaPatchPtr OpalMediaStream::InternalSetPatchPart1 | ( | OpalMediaPatch * | newPatch | ) | `[protected]`

void OpalMediaStream::InternalSetPatchPart2 | ( | const OpalMediaPatchPtr & | oldPatch | ) | `[protected]`

virtual bool OpalMediaStream::InternalUpdateMediaFormat | ( | const OpalMediaFormat & | mediaFormat | ) | `[virtual]`

Reimplemented in OpalNullMediaStream, OpalVideoMediaStream, and OpalFaxMediaStream.

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.

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

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

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

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 | ( |  | ) | const`[virtual]`

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

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

virtual bool OpalMediaStream::SetPaused | ( | bool | pause,
|  | bool | fromPatch = `false` |
| ) |  |  | `[virtual]`

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
  fromPatch | Is being called from OpalMediaPatch

Reimplemented in OpalNullMediaStream, and 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.

bool OpalMediaStream::UpdateMediaFormat | ( | const OpalMediaFormat & | mediaFormat | ) |

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

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

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]`

Reimplemented in OpalIAX2MediaStream.

PINDEX OpalMediaStream::defaultDataSize `[protected]`

PString OpalMediaStream::identifier `[protected]`

PINDEX OpalMediaStream::m_frameSize `[protected]`

unsigned OpalMediaStream::m_frameTime `[protected]`

bool OpalMediaStream::m_isOpen `[protected]`

bool OpalMediaStream::m_isSource `[protected]`

OpalMediaPatchPtr OpalMediaStream::m_mediaPatch `[protected]`

bool OpalMediaStream::m_paused `[protected]`

RTP_DataFrame::PayloadTypes OpalMediaStream::m_payloadType `[protected]`

bool OpalMediaStream::marker `[protected]`

OpalMediaFormat OpalMediaStream::mediaFormat `[protected]`

unsigned OpalMediaStream::sessionID `[protected]`

unsigned OpalMediaStream::timestamp `[protected]`

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

- mediastrm.h