class H323Codec

This class embodies the implementation of a specific codec instance used to transfer data via the logical channels opened and managed by the H323 control channel.

Inheritance:


Public Methods

[more]virtual BOOL Open ( H323Connection & connection )
Open the codec.
[more]virtual void Close ()
Close the codec
[more]virtual BOOL Read ( BYTE* buffer, unsigned & length, RTP_DataFrame & rtpFrame )
Encode the data from the appropriate device.
[more]virtual BOOL Write ( const BYTE* buffer, unsigned length, const RTP_DataFrame & frame, unsigned & written )
Decode the data and output it to appropriate device.
[more]virtual unsigned GetFrameRate () const
Get the frame rate in RTP timestamp units
[more]virtual void OnFlowControl ( long bitRateRestriction )
Limit bit flow for the logical channel.
[more]virtual void OnMiscellaneousCommand ( const H245_MiscellaneousCommand_type & type )
Process a miscellaneous command on the logical channel.
[more]virtual void OnMiscellaneousIndication ( const H245_MiscellaneousIndication_type & type )
Process a miscellaneous indication on the logical channel.
[more]virtual BOOL AttachChannel ( PChannel* channel, BOOL autoDelete = TRUE )
Attach the raw data channel for use by codec.
[more]virtual PChannel* SwapChannel ( PChannel* newChannel, BOOL autoDelete = TRUE )
Attach a new channel and returns the previous one, without neither deleting it nor closing it.
[more]virtual BOOL CloseRawDataChannel ()
Close the raw data channel, described in H323Codec::AttachChannel
[more]PChannel* GetRawDataChannel ()
Return a pointer to the raw data channel, which can then be used to access the recording/playing device.
[more]virtual BOOL IsRawDataChannelNative () const
Return flag indicating raw channel is native.
[more]BOOL ReadRaw ( void* data, PINDEX size, PINDEX & length )
Read from the raw data channel
[more]BOOL WriteRaw ( void* data, PINDEX length )
Write from the raw data channel
[more]BOOL AttachLogicalChannel (H323Channel* channel)
Attach the logical channel, for use by the codec.
[more]void AddFilter ( const PNotifier & notifier )
Add a filter to the codec.


Documentation

This class embodies the implementation of a specific codec instance used to transfer data via the logical channels opened and managed by the H323 control channel.

An application may create a descendent off this class and override functions as required for descibing a codec.

ovirtual BOOL Open( H323Connection & connection )
Open the codec. This will open the codec for encoding or decoding, it is called after the logical channel have been established and the background threads to drive them have been started. This is primarily used to delay allocation of resources until the last millisecond.

A descendent class may be created by the application and it may cast the connection parameter to the application defined descendent of H323Connection to obtain information needed to open the codec.

The default behaviour does nothing.

Parameters:
connection - Connection between the endpoints

ovirtual void Close() = 0
Close the codec

ovirtual BOOL Read( BYTE* buffer, unsigned & length, RTP_DataFrame & rtpFrame ) = 0
Encode the data from the appropriate device. This will encode data for transmission. The exact size and description of the data placed in the buffer is codec dependent but should be less than OpalMediaFormat::GetFrameSize() in length.

The length parameter is filled with the actual length of the encoded data, often this will be the same as OpalMediaFormat::GetFrameSize().

This function is called every GetFrameRate() timestamp units, so MUST take less than (or equal to) that amount of time to complete. It should always return the amount of data that corresponds to the GetFrameRate() timestamp units as well.

A returned length of zero indicates that time has passed but there is no data encoded. This is typically used for silence detection in an audio codec.

Parameters:
buffer - Buffer of encoded data
length - Actual length of encoded data buffer
rtpFrame - RTP data frame

ovirtual BOOL Write( const BYTE* buffer, unsigned length, const RTP_DataFrame & frame, unsigned & written ) = 0
Decode the data and output it to appropriate device. This will decode a single frame of received data. The exact size and description of the data required in the buffer is codec dependent but should be at least than OpalMediaFormat::GetFrameSize() in length.

It is expected this function anunciates the data. That is, for example with audio data, the sound is output on a speaker.

This function is called every GetFrameRate() timestamp units, so MUST take less than that amount of time to complete!

Parameters:
buffer - Buffer of encoded data
length - Length of encoded data buffer
frame - Entire RTP frame
written - Number of bytes used from data buffer

ovirtual unsigned GetFrameRate() const
Get the frame rate in RTP timestamp units

ovirtual void OnFlowControl( long bitRateRestriction )
Limit bit flow for the logical channel. The default behaviour does nothing.
Parameters:
bitRateRestriction - Bit rate limitation

ovirtual void OnMiscellaneousCommand( const H245_MiscellaneousCommand_type & type )
Process a miscellaneous command on the logical channel. The default behaviour does nothing.
Parameters:
type - Command to process

ovirtual void OnMiscellaneousIndication( const H245_MiscellaneousIndication_type & type )
Process a miscellaneous indication on the logical channel. The default behaviour does nothing.
Parameters:
type - Indication to process

ovirtual BOOL AttachChannel( PChannel* channel, BOOL autoDelete = TRUE )
Attach the raw data channel for use by codec. Note the channel provided will be deleted on destruction of the codec.

The channel connects the codec (audio or video) with hardware to read/write data. Thus, the video codec provides a pointer to the data, which the renderer/grabber then accesses to display/grab the image from/to.

Parameters:
channel - Channel to read/write raw codec data
autoDelete - Channel is to be automatically deleted

ovirtual PChannel* SwapChannel( PChannel* newChannel, BOOL autoDelete = TRUE )
Attach a new channel and returns the previous one, without neither deleting it nor closing it. This method is used to, for example, when swapping to or from a hold media channel
Parameters:
newChannel - Channel to read/write raw codec data
autoDelete - Channel is to be automatically deleted

ovirtual BOOL CloseRawDataChannel()
Close the raw data channel, described in H323Codec::AttachChannel

oPChannel* GetRawDataChannel()
Return a pointer to the raw data channel, which can then be used to access the recording/playing device. (or testing if channel is attached).

ovirtual BOOL IsRawDataChannelNative() const
Return flag indicating raw channel is native. For audio codecs, FALSE typically means that the format is PCM-16. For video codecs, FALSE typically means that the format is YUV411P.

The default behaviour returns FALSE.

oBOOL ReadRaw( void* data, PINDEX size, PINDEX & length )
Read from the raw data channel

oBOOL WriteRaw( void* data, PINDEX length )
Write from the raw data channel

oBOOL AttachLogicalChannel(H323Channel* channel)
Attach the logical channel, for use by the codec. The channel provided is not deleted on destruction, it is just used.

The logical channel provides a means for the codec to send control messages. E.G. the receive video codec wants to receive a frame update.

ovoid AddFilter( const PNotifier & notifier )
Add a filter to the codec. The call back function is executed just after reading from, or just before writing to, the raw data channel. The callback is passed the H323Codec::FilterInfo structure containing the data that is being read or written.

To use define: PDECLARE_NOTIFIER(H323Codec::FilterInfo, YourClass, YourFunction); and void YourClass::YourFunction(H323Codec::FilterInfo & info, INT) { DO something with data } and to connect to a codec: BOOL YourClass::OnStartLogicalChannel(H323Channel & channel) { H323Codec * codec = channel.GetCodec(); codec->AddFilter(PCREATE_NOTIFIER(YourFunction)); } for example. Other places can be used to set the filter.


Direct child classes:
H323VideoCodec
H323AudioCodec

Alphabetic index HTML hierarchy of classes or Java



This page was generated with the help of DOC++.