# OpalFaxConnection Class Reference

`#include <t38proto.h>`

Inheritance diagram for OpalFaxConnection:

[legend]
Collaboration diagram for OpalFaxConnection:
[legend]

## Public Member Functions

Construction
| OpalFaxConnection (OpalCall &call, OpalFaxEndPoint &endpoint, const PString &filename, bool receiving, bool disableT38, OpalConnection::StringOptions *stringOptions=NULL)
| ~OpalFaxConnection ()
Overrides from OpalLocalConnection
virtual PString | GetPrefixName () const
virtual OpalMediaFormatList | GetMediaFormats () const
virtual void | AdjustMediaFormats (bool local, const OpalConnection *otherConnection, OpalMediaFormatList &mediaFormats) const
virtual void | OnEstablished ()
virtual void | OnReleased ()
virtual OpalMediaStream * | CreateMediaStream (const OpalMediaFormat &mediaFormat, unsigned sessionID, PBoolean isSource)
virtual void | OnStartMediaPatch (OpalMediaPatch &patch)
virtual void | OnClosedMediaStream (const OpalMediaStream &stream)
virtual PBoolean | SendUserInputTone (char tone, unsigned duration)
virtual void | OnUserInputTone (char tone, unsigned duration)
virtual bool | SwitchFaxMediaStreams (bool toT38)
virtual void | OnSwitchedFaxMediaStreams (bool toT38, bool success)
virtual bool | OnSwitchingFaxMediaStreams (bool toT38)
virtual void | OnApplyStringOptions ()
| Call back for connection to act on changed string options.
New operations
virtual void | OnFaxCompleted (bool failed)
virtual void | GetStatistics (OpalMediaStatistics &statistics) const
const PString & | GetFileName () const
bool | IsReceive () const

## Protected Member Functions

| PDECLARE_NOTIFIER (PTimer, OpalFaxConnection, OnSwitchTimeout)
void | InternalOpenFaxStreams ()
void | InternalOnFaxCompleted ()
void | SetFaxMediaFormatOptions (OpalMediaFormat &mediaFormat) const

## Protected Attributes

OpalFaxEndPoint & | m_endpoint
PString | m_filename
bool | m_receiving
bool | m_disableT38
unsigned | m_switchTime
OpalMediaFormat | m_tiffFileFormat
PTimer | m_switchTimer
OpalMediaStatistics | m_finalStatistics
PAtomicBoolean | m_completed

## Detailed Description

Fax Connection. There are six modes of operation: Mode receiving disableT38 filename TIFF -> T.38 false false "something.tif" T.38 -> TIFF true false "something.tif" TIFF -> G.711 false true "something.tif" G.711 ->TIFF true true "something.tif" T.38 -> G.711 false don't care PString::Empty() G.711 -> T.38 true don't care PString::Empty()

If T.38 is involved then there is generally two stages to the setup, as indicated by the m_switchedToT38 flag. When false then we are in audio mode looking for CNG/CED tones. When true, then we are switching, or have switched, to T.38 operation. If the switch fails, then the m_disableT38 is set and we proceed in fall back mode.

## Constructor & Destructor Documentation

OpalFaxConnection::OpalFaxConnection | ( | OpalCall & | call,
|  | OpalFaxEndPoint & | endpoint,
|  | const PString & | filename,
|  | bool | receiving,
|  | bool | disableT38,
|  | OpalConnection::StringOptions * | stringOptions = `NULL` |
| ) |  |  |

Create a new endpoint.

Parameters:

  call | Owner calll for connection
  endpoint | Owner endpoint for connection
  filename | TIFF file name to send/receive
  receiving | True if receiving a fax
  disableT38 | True if want to force G.711
  stringOptions | Options to pass to connection

OpalFaxConnection::~OpalFaxConnection | ( |  | ) |

Destroy endpoint.

## Member Function Documentation

virtual void OpalFaxConnection::AdjustMediaFormats | ( | bool | local,
|  | const OpalConnection * | otherConnection,
|  | OpalMediaFormatList & | mediaFormats |
| ) |  |  | const`[virtual]`

Adjust media formats available on a connection. This is called by a connection after it has called OpalCall::GetMediaFormats() to get all media formats that it can use so that an application may remove or reorder the media formats before they are used to open media streams.

This function may also be executed by other connections in the call. If this happens then the "otherConnection" parameter will be non-NULL. The "local" parameter sense is relative to the "otherConnection" parameter, if NULL then it is relative to "this".

The default behaviour calls the OpalEndPoint function of the same name.

Reimplemented from OpalConnection.

virtual OpalMediaStream* OpalFaxConnection::CreateMediaStream | ( | const OpalMediaFormat & | mediaFormat,
|  | unsigned | sessionID,
|  | PBoolean | isSource |
| ) |  |  | `[virtual]`

Open a new media stream. This will create a media stream of an appropriate subclass as required by the underlying connection protocol. For instance H.323 would create an OpalRTPStream.

The sessionID parameter may not be needed by a particular media stream and may be ignored. In the case of an OpalRTPStream it us used.

Note that media streams may be created internally to the underlying protocol. This function is not the only way a stream can come into existance.

The default behaviour is pure.

Reimplemented from OpalLocalConnection.

const PString& OpalFaxConnection::GetFileName | ( |  | ) | const`[inline]`

Get the file to send/receive

virtual OpalMediaFormatList OpalFaxConnection::GetMediaFormats | ( |  | ) | const`[virtual]`

Get the data formats this connection is capable of operating. This provides a list of media data format names that a OpalMediaStream may be created in within this connection.

The default behaviour calls GetMediaFormats() on the endpoint.

Reimplemented from OpalConnection.

virtual PString OpalFaxConnection::GetPrefixName | ( |  | ) | const`[virtual]`

Get this connections protocol prefix for URLs.

Reimplemented from OpalConnection.

virtual void OpalFaxConnection::GetStatistics | ( | OpalMediaStatistics & | statistics | ) | const`[virtual]`

Get fax transmission/receipt statistics.

Parameters:

  statistics | Statistics for call

void OpalFaxConnection::InternalOnFaxCompleted | ( |  | ) | `[protected]`

void OpalFaxConnection::InternalOpenFaxStreams | ( |  | ) | `[protected]`

bool OpalFaxConnection::IsReceive | ( |  | ) | const`[inline]`

Get receive fax flag.

virtual void OpalFaxConnection::OnApplyStringOptions | ( |  | ) | `[virtual]`

Call back for connection to act on changed string options.

Reimplemented from OpalLocalConnection.

virtual void OpalFaxConnection::OnClosedMediaStream | ( | const OpalMediaStream & | stream | ) | `[virtual]`

Call back for closed a media stream.

The default behaviour calls the OpalEndPoint function of the same name.

Reimplemented from OpalConnection.

virtual void OpalFaxConnection::OnEstablished | ( |  | ) | `[virtual]`

A call back function whenever a connection is established. This indicates that a connection to an endpoint was established. This usually occurs after OnConnected() and indicates that the connection is both connected and has media flowing.

In the context of H.323 this means that the signalling and control channels are open and the TerminalCapabilitySet and MasterSlave negotiations are complete.

The default behaviour calls the OpalEndPoint function of the same name.

Reimplemented from OpalConnection.

virtual void OpalFaxConnection::OnFaxCompleted | ( | bool | failed | ) | `[virtual]`

Fax transmission/receipt completed. Default behaviour calls equivalent function on OpalFaxEndPoint.

Parameters:

  failed | Fax ended with failure

virtual void OpalFaxConnection::OnReleased | ( |  | ) | `[virtual]`

Clean up the termination of the connection. This function can do any internal cleaning up and waiting on background threads that may be using the connection object.

Note that there is not a one to one relationship with the OnEstablishedConnection() function. This function may be called without that function being called. For example if SetUpConnection() was used but the call never completed.

Classes that override this function should make sure they call the ancestor version for correct operation.

An application will not typically call this function as it is used by the OpalManager during a release of the connection.

The default behaviour calls the OpalEndPoint function of the same name.

Reimplemented from OpalConnection.

virtual void OpalFaxConnection::OnStartMediaPatch | ( | OpalMediaPatch & | patch | ) | `[virtual]`

Call back when media stream patch thread starts.

Default behaviour calls OpalManager function of same name.

Reimplemented from OpalConnection.

virtual void OpalFaxConnection::OnSwitchedFaxMediaStreams | ( | bool | toT38,
|  | bool | success |
| ) |  |  | `[virtual]`

virtual bool OpalFaxConnection::OnSwitchingFaxMediaStreams | ( | bool | toT38 | ) | `[virtual]`

virtual void OpalFaxConnection::OnUserInputTone | ( | char | tone,
|  | unsigned | duration |
| ) |  |  | `[virtual]`

Call back for remote enpoint has sent user input. If duration is zero then this indicates the beginning of the tone. If duration is non-zero then it indicates the end of the tone output.

The default behaviour calls the OpalEndPoint function of the same name.

Reimplemented from OpalConnection.

OpalFaxConnection::PDECLARE_NOTIFIER | ( | PTimer | ,
|  | OpalFaxConnection | ,
|  | OnSwitchTimeout |  |
| ) |  |  | `[protected]`

virtual PBoolean OpalFaxConnection::SendUserInputTone | ( | char | tone,
|  | unsigned | duration |
| ) |  |  | `[virtual]`

Send a user input indication to the remote endpoint. This sends DTMF emulation user input. If something more sophisticated than the simple tones that can be sent using the SendUserInput() function.

A duration of zero indicates that no duration is to be indicated. A non-zero logical channel indicates that the tone is to be syncronised with the logical channel at the rtpTimestamp value specified.

The tone parameter must be one of "0123456789#*ABCD!" where '!' indicates a hook flash. If tone is a ' ' character then a signalUpdate PDU is sent that updates the last tone indication sent. See the H.245 specifcation for more details on this.

The default behaviour sends the tone using RFC2833.

Reimplemented from OpalConnection.

void OpalFaxConnection::SetFaxMediaFormatOptions | ( | OpalMediaFormat & | mediaFormat | ) | const`[protected]`

virtual bool OpalFaxConnection::SwitchFaxMediaStreams | ( | bool | toT38 | ) | `[virtual]`

## Field Documentation

PAtomicBoolean OpalFaxConnection::m_completed `[protected]`

bool OpalFaxConnection::m_disableT38 `[protected]`

OpalFaxEndPoint& OpalFaxConnection::m_endpoint `[protected]`

PString OpalFaxConnection::m_filename `[protected]`

OpalMediaStatistics OpalFaxConnection::m_finalStatistics `[protected]`

bool OpalFaxConnection::m_receiving `[protected]`

unsigned OpalFaxConnection::m_switchTime `[protected]`

PTimer OpalFaxConnection::m_switchTimer `[protected]`

OpalMediaFormat OpalFaxConnection::m_tiffFileFormat `[protected]`

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

- t38proto.h