OpalFaxConnection Class Reference

#include <t38proto.h>

Inheritance diagram for OpalFaxConnection:


Public Member Functions
Construction
	OpalFaxConnection (OpalCall &call, OpalFaxEndPoint &endpoint, const PString &filename, bool receiving, bool disableT38, OpalConnection::StringOptions *stringOptions=NULL)
	~OpalFaxConnection ()
Overrides from OpalConnection
virtual PString	GetPrefixName () const
virtual bool	IsNetworkConnection () const
virtual void	ApplyStringOptions (OpalConnection::StringOptions &stringOptions)
virtual OpalMediaFormatList	GetMediaFormats () const
virtual void	AdjustMediaFormats (bool local, OpalMediaFormatList &mediaFormats, OpalConnection *otherConnection) const
virtual PBoolean	SetUpConnection ()
virtual PBoolean	SetAlerting (const PString &calleeName, PBoolean withMedia)
virtual PBoolean	SetConnected ()
virtual void	OnEstablished ()
virtual void	OnReleased ()
virtual OpalMediaStream *	CreateMediaStream (const OpalMediaFormat &mediaFormat, unsigned sessionID, PBoolean isSource)
virtual void	OnStartMediaPatch (OpalMediaPatch &patch)
virtual void	OnStopMediaPatch (OpalMediaPatch &patch)
virtual PBoolean	SendUserInputTone (char tone, unsigned duration)
virtual void	OnUserInputTone (char tone, unsigned duration)
virtual bool	SwitchFaxMediaStreams (bool enableFax)
virtual void	OnSwitchedFaxMediaStreams (bool enabledFax)
New operations
virtual void	AcceptIncoming ()
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, OnSendCNGCED)
	PDECLARE_NOTIFIER (PThread, OpalFaxConnection, OpenFaxStreams)
	PDECLARE_NOTIFIER (PThread, OpalFaxConnection, ReleaseConnection)
Protected Attributes
OpalFaxEndPoint &	m_endpoint
PString	m_filename
bool	m_receiving
PString	m_stationId
bool	m_disableT38
PTimeInterval	m_releaseTimeout
PTimeInterval	m_switchTimeout
OpalMediaFormat	m_tiffFileFormat
bool	m_awaitingSwitchToT38
PTimer	m_faxTimer
Friends
class	OpalFaxMediaStream

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

OpalFaxConnection::~OpalFaxConnection ( )

Destroy endpoint.

Member Function Documentation

virtual void OpalFaxConnection::AcceptIncoming ( ) [virtual]

Accept the incoming connection.

virtual void OpalFaxConnection::AdjustMediaFormats	(	bool	local,
		OpalMediaFormatList &	mediaFormats,
		OpalConnection *	otherConnection
	)			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 to adjust the media format list for other connections in the call. If this happens then the "otherConnection" parameter will be non-NULL.

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

Reimplemented from OpalConnection.

virtual void OpalFaxConnection::ApplyStringOptions ( OpalConnection::StringOptions & stringOptions ) [virtual]

Reimplemented from OpalConnection.

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

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

Reimplemented from OpalConnection.

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

virtual bool OpalFaxConnection::IsNetworkConnection ( ) const [inline, virtual]

Get indication of connection being to a "network". This indicates the if the connection may be regarded as a "network" connection. The distinction is about if there is a concept of a "remote" party being connected to and is best described by example: sip, h323, iax and pstn are all "network" connections as they connect to something "remote". While pc, pots and ivr are not as the entity being connected to is intrinsically local.

Implements OpalConnection.

bool OpalFaxConnection::IsReceive ( ) const [inline]

Get receive fax flag.

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.

Reimplemented from OpalConnection.

virtual void OpalFaxConnection::OnStopMediaPatch ( OpalMediaPatch & patch ) [virtual]

Call back when media stream patch thread stops.

Reimplemented from OpalConnection.

virtual void OpalFaxConnection::OnSwitchedFaxMediaStreams ( bool enabledFax ) [virtual]

Indicate status of switch to/from FAX mode.

Default behaviour does nothing.

Reimplemented from OpalConnection.

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	(	PThread	,
		OpalFaxConnection	,
		ReleaseConnection
	)			`[protected]`

OpalFaxConnection::PDECLARE_NOTIFIER	(	PThread	,
		OpalFaxConnection	,
		OpenFaxStreams
	)			`[protected]`

OpalFaxConnection::PDECLARE_NOTIFIER	(	PTimer	,
		OpalFaxConnection	,
		OnSendCNGCED
	)			`[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.

virtual PBoolean OpalFaxConnection::SetAlerting	(	const PString &	calleeName,
		PBoolean	withMedia
	)			`[virtual]`

Indicate to remote endpoint an alert is in progress. If this is an incoming connection and the AnswerCallResponse is in a AnswerCallDeferred or AnswerCallPending state, then this function is used to indicate to that endpoint that an alert is in progress. This is usually due to another connection which is in the call (the B party) has received an OnAlerting() indicating that its remote endpoint is "ringing".

The default behaviour does nothing.

Parameters:

calleeName	Name of endpoint being alerted.
withMedia	Open media with alerting

Implements OpalConnection.

virtual PBoolean OpalFaxConnection::SetConnected ( ) [virtual]

Indicate to remote endpoint we are connected.

The default behaviour sets the phase to ConnectedPhase, sets the connection start time and then checks if there is any media channels opened and if so, moves on to the established phase, calling OnEstablished().

In other words, this method is used to handle incoming calls, and is an indication that we have accepted the incoming call.

Reimplemented from OpalConnection.

virtual PBoolean OpalFaxConnection::SetUpConnection ( ) [virtual]

Start an outgoing connection. This function will initiate the connection to the remote entity, for example in H.323 it sends a SETUP, in SIP it sends an INVITE etc.

The default behaviour does.

Implements OpalConnection.

virtual bool OpalFaxConnection::SwitchFaxMediaStreams ( bool enableFax ) [virtual]

Switch to/from FAX mode.

Reimplemented from OpalConnection.