OpalConnection Class Reference

#include <connection.h>

Inheritance diagram for OpalConnection:


Basic operations
enum	Phases { UninitialisedPhase, SetUpPhase, ProceedingPhase, AlertingPhase, ConnectedPhase, EstablishedPhase, ForwardingPhase, ReleasingPhase, ReleasedPhase, NumPhases }
virtual bool	IsNetworkConnection () const =0
Phases	GetPhase () const
void	SetPhase (Phases phaseToSet)
CallEndReason	GetCallEndReason () const
PString	GetCallEndReasonText () const
virtual void	SetCallEndReason (CallEndReason reason)
void	ClearCall (CallEndReason reason=EndedByLocalUser)
virtual void	ClearCallSynchronous (PSyncPoint *sync, CallEndReason reason=EndedByLocalUser)
unsigned	GetQ931Cause () const
void	SetQ931Cause (unsigned v)
virtual bool	TransferConnection (const PString &remoteParty)
virtual bool	HoldConnection ()
virtual bool	RetrieveConnection ()
virtual bool	IsConnectionOnHold (bool fromRemote)
virtual void	OnHold (bool fromRemote, bool onHold)
static PString	GetCallEndReasonText (CallEndReason reason)
static void	SetCallEndReasonText (CallEndReasonCodes reasonCode, const PString &newText)
User input
enum	SendUserInputModes { SendUserInputAsQ931, SendUserInputAsString, SendUserInputAsTone, SendUserInputAsInlineRFC2833, SendUserInputAsSeparateRFC2833, SendUserInputAsProtocolDefault, NumSendUserInputModes }
virtual void	SetSendUserInputMode (SendUserInputModes mode)
virtual SendUserInputModes	GetSendUserInputMode () const
virtual SendUserInputModes	GetRealSendUserInputMode () const
virtual PBoolean	SendUserInputString (const PString &value)
virtual PBoolean	SendUserInputTone (char tone, unsigned duration=0)
virtual void	OnUserInputString (const PString &value)
virtual void	OnUserInputTone (char tone, unsigned duration)
void	SendUserInputHookFlash (unsigned duration=500)
virtual PString	GetUserInput (unsigned timeout=30)
virtual void	SetUserInput (const PString &input)
virtual PString	ReadUserInput (const char *terminators="#\r\n", unsigned lastDigitTimeout=4, unsigned firstDigitTimeout=30)
virtual PBoolean	PromptUserInput (PBoolean play)
Public Types
	EndedByLocalUser
	EndedByNoAccept
	Local endpoint application cleared call.
	EndedByAnswerDenied
	Local endpoint did not accept call OnIncomingCall()=PFalse.
	EndedByRemoteUser
	Local endpoint declined to answer call.
	EndedByRefusal
	Remote endpoint application cleared call.
	EndedByNoAnswer
	Remote endpoint refused call.
	EndedByCallerAbort
	Remote endpoint did not answer in required time.
	EndedByTransportFail
	Remote endpoint stopped calling.
	EndedByConnectFail
	Transport error cleared call.
	EndedByGatekeeper
	Transport connection failed to establish call.
	EndedByNoUser
	Gatekeeper has cleared call.
	EndedByNoBandwidth
	Call failed as could not find user (in GK).
	EndedByCapabilityExchange
	Call failed as could not get enough bandwidth.
	EndedByCallForwarded
	Could not find common capabilities.
	EndedBySecurityDenial
	Call was forwarded using FACILITY message.
	EndedByLocalBusy
	Call failed a security check and was ended.
	EndedByLocalCongestion
	Local endpoint busy.
	EndedByRemoteBusy
	Local endpoint congested.
	EndedByRemoteCongestion
	Remote endpoint busy.
	EndedByUnreachable
	Remote endpoint congested.
	EndedByNoEndPoint
	Could not reach the remote party.
	EndedByHostOffline
	The remote party is not running an endpoint.
	EndedByTemporaryFailure
	The remote party host off line.
	EndedByQ931Cause
	The remote failed temporarily app may retry.
	EndedByDurationLimit
	The remote ended the call with unmapped Q.931 cause code.
	EndedByInvalidConferenceID
	Call cleared due to an enforced duration limit.
	EndedByNoDialTone
	Call cleared due to invalid conference ID.
	EndedByNoRingBackTone
	Call cleared due to missing dial tone.
	EndedByOutOfService
	Call cleared due to missing ringback tone.
	EndedByAcceptingCallWaiting
	Call cleared because the line is out of service,.
	EndedByGkAdmissionFailed
	Call cleared because another call is answered.
	NumCallEndReasons
	Call cleared because gatekeeper admission request failed.
	AnswerCallNow
	AnswerCallDenied
	Answer the call continuing with the connection.
	AnswerCallPending
	Refuse the call sending a release complete.
	AnswerCallDeferred
	Send an Alerting PDU and wait for AnsweringCall().
	AnswerCallAlertWithMedia
	As for AnswerCallPending but does not send Alerting PDU.
	AnswerCallDeferredWithMedia
	As for AnswerCallPending but starts media channels.
	AnswerCallProgress
	As for AnswerCallDeferred but starts media channels.
	AnswerCallNowAndReleaseCurrent
	Answer the call with a h323 progress, or sip 183 session in progress, or ...
	NumAnswerCallResponses
	Answer the call and destroy the current call.
	FastStartOptionDisable = 0x0001
	FastStartOptionEnable = 0x0002
	FastStartOptionMask = 0x0003
	H245TunnelingOptionDisable = 0x0004
	H245TunnelingOptionEnable = 0x0008
	H245TunnelingOptionMask = 0x000c
	H245inSetupOptionDisable = 0x0010
	H245inSetupOptionEnable = 0x0020
	H245inSetupOptionMask = 0x0030
	DetectInBandDTMFOptionDisable = 0x0040
	DetectInBandDTMFOptionEnable = 0x0080
	DetectInBandDTMFOptionMask = 0x00c0
	RTPAggregationDisable = 0x0100
	RTPAggregationEnable = 0x0200
	RTPAggregationMask = 0x0300
	SendDTMFAsDefault = 0x0000
	SendDTMFAsString = 0x0400
	SendDTMFAsTone = 0x0800
	SendDTMFAsRFC2833 = 0x0c00
	SendDTMFMask = 0x0c00
	UninitialisedPhase
	Indicates the OpalConnection instance has just been constructed.
	SetUpPhase
	In the process of sending/receiving the initial INVITE packet.
	ProceedingPhase
	The remote is now responsible for completing the call.
	AlertingPhase
	The remote says there is a phone ringing, somewhere.
	ConnectedPhase
	There is agreement on having a call, usually means billing will apply.
	EstablishedPhase
	Media is flowing, control streams are all operational.
	ForwardingPhase
	Connection is in the process of being forwarded.
	ReleasingPhase
	Hangup packet has been sent/received, media and control not yet stopped.
	ReleasedPhase
	Media and control streams have been terminated.
	NumPhases
	Number of available phases. Can be used to indicate an unknown phase.
	SendUserInputAsQ931
	SendUserInputAsString
	SendUserInputAsTone
	SendUserInputAsInlineRFC2833
	SendUserInputAsSeparateRFC2833
	SendUserInputAsProtocolDefault
	NumSendUserInputModes
enum	CallEndReasonCodes { EndedByLocalUser, EndedByNoAccept, EndedByAnswerDenied, EndedByRemoteUser, EndedByRefusal, EndedByNoAnswer, EndedByCallerAbort, EndedByTransportFail, EndedByConnectFail, EndedByGatekeeper, EndedByNoUser, EndedByNoBandwidth, EndedByCapabilityExchange, EndedByCallForwarded, EndedBySecurityDenial, EndedByLocalBusy, EndedByLocalCongestion, EndedByRemoteBusy, EndedByRemoteCongestion, EndedByUnreachable, EndedByNoEndPoint, EndedByHostOffline, EndedByTemporaryFailure, EndedByQ931Cause, EndedByDurationLimit, EndedByInvalidConferenceID, EndedByNoDialTone, EndedByNoRingBackTone, EndedByOutOfService, EndedByAcceptingCallWaiting, EndedByGkAdmissionFailed, NumCallEndReasons }
enum	AnswerCallResponse { AnswerCallNow, AnswerCallDenied, AnswerCallPending, AnswerCallDeferred, AnswerCallAlertWithMedia, AnswerCallDeferredWithMedia, AnswerCallProgress, AnswerCallNowAndReleaseCurrent, NumAnswerCallResponses }
enum	Options { FastStartOptionDisable = 0x0001, FastStartOptionEnable = 0x0002, FastStartOptionMask = 0x0003, H245TunnelingOptionDisable = 0x0004, H245TunnelingOptionEnable = 0x0008, H245TunnelingOptionMask = 0x000c, H245inSetupOptionDisable = 0x0010, H245inSetupOptionEnable = 0x0020, H245inSetupOptionMask = 0x0030, DetectInBandDTMFOptionDisable = 0x0040, DetectInBandDTMFOptionEnable = 0x0080, DetectInBandDTMFOptionMask = 0x00c0, RTPAggregationDisable = 0x0100, RTPAggregationEnable = 0x0200, RTPAggregationMask = 0x0300, SendDTMFAsDefault = 0x0000, SendDTMFAsString = 0x0400, SendDTMFAsTone = 0x0800, SendDTMFAsRFC2833 = 0x0c00, SendDTMFMask = 0x0c00 }
Public Member Functions
virtual bool	GarbageCollection ()
const StringOptions &	GetStringOptions () const
	Get the string options associated with this connection.
void	SetStringOptions (const StringOptions &options, bool overwrite)
	Set the string options associated with this connection.
virtual void	ApplyStringOptions (OpalConnection::StringOptions &stringOptions)
virtual void	OnApplyStringOptions ()
virtual void	EnableRecording ()
virtual void	DisableRecording ()
virtual bool	TransmitInternalIM (const OpalMediaFormat &format, RTP_IMFrame &body)
virtual void	OnReceiveInternalIM (const OpalMediaFormat &format, RTP_IMFrame &body)
virtual bool	TransmitExternalIM (const OpalMediaFormat &format, RTP_IMFrame &body)
virtual bool	OnReceiveExternalIM (const OpalMediaFormat &format, RTP_IMFrame &body)
RFC4103Context &	GetRFC4103Context (PINDEX i)
Construction
	OpalConnection (OpalCall &call, OpalEndPoint &endpoint, const PString &token, unsigned options=0, OpalConnection::StringOptions *stringOptions=NULL)
	~OpalConnection ()
Overrides from PObject
void	PrintOn (ostream &strm) const
Call progress functions
virtual PBoolean	OnIncomingConnection (unsigned int options, OpalConnection::StringOptions *stringOptions)
virtual PBoolean	SetUpConnection ()=0
virtual PBoolean	OnSetUpConnection ()
virtual void	OnProceeding ()
virtual void	OnAlerting ()
virtual PBoolean	SetAlerting (const PString &calleeName, PBoolean withMedia)=0
virtual AnswerCallResponse	OnAnswerCall (const PString &callerName)
virtual void	AnsweringCall (AnswerCallResponse response)
virtual void	OnConnected ()
virtual PBoolean	SetConnected ()
virtual void	OnEstablished ()
virtual void	Release (CallEndReason reason=EndedByLocalUser)
virtual void	OnReleased ()
Additional signalling functions
virtual PString	GetDestinationAddress ()
virtual PBoolean	ForwardCall (const PString &forwardParty)
PSafePtr< OpalConnection >	GetOtherPartyConnection () const
template<class cls>
PSafePtr< cls >	GetOtherPartyConnectionAs () const
Media Stream Management
virtual OpalMediaFormatList	GetMediaFormats () const
virtual OpalMediaFormatList	GetLocalMediaFormats ()
virtual void	AdjustMediaFormats (bool local, OpalMediaFormatList &mediaFormats, OpalConnection *otherConnection) const
virtual unsigned	GetNextSessionID (const OpalMediaType &mediaType, bool isSource)
virtual OpalMediaType::AutoStartMode	GetAutoStart (const OpalMediaType &mediaType) const
virtual void	AutoStartMediaStreams (bool force=false)
virtual bool	SwitchFaxMediaStreams (bool enableFax)
virtual void	OnSwitchedFaxMediaStreams (bool enabledFax)
virtual OpalMediaStreamPtr	OpenMediaStream (const OpalMediaFormat &mediaFormat, unsigned sessionID, bool isSource)
virtual bool	CloseMediaStream (unsigned sessionId, bool source)
virtual bool	CloseMediaStream (OpalMediaStream &stream)
bool	RemoveMediaStream (OpalMediaStream &strm)
virtual void	StartMediaStreams ()
virtual void	CloseMediaStreams ()
virtual void	PauseMediaStreams (PBoolean paused)
virtual OpalMediaStream *	CreateMediaStream (const OpalMediaFormat &mediaFormat, unsigned sessionID, PBoolean isSource)
OpalMediaStreamPtr	GetMediaStream (const PString &streamID, bool source) const
OpalMediaStreamPtr	GetMediaStream (unsigned sessionId, bool source) const
OpalMediaStreamPtr	GetMediaStream (const OpalMediaType &mediaType, bool source, OpalMediaStreamPtr previous=NULL) const
virtual PBoolean	OnOpenMediaStream (OpalMediaStream &stream)
virtual void	OnClosedMediaStream (const OpalMediaStream &stream)
virtual void	OnPatchMediaStream (PBoolean isSource, OpalMediaPatch &patch)
virtual void	OnStartMediaPatch (OpalMediaPatch &patch)
virtual void	OnStopMediaPatch (OpalMediaPatch &patch)
	PDECLARE_NOTIFIER (OpalMediaCommand, OpalConnection, OnMediaCommand)
virtual void	AttachRFC2833HandlerToPatch (PBoolean isSource, OpalMediaPatch &patch)
virtual PBoolean	IsMediaBypassPossible (unsigned sessionID) const
virtual PBoolean	CreateVideoInputDevice (const OpalMediaFormat &mediaFormat, PVideoInputDevice *&device, PBoolean &autoDelete)
virtual PBoolean	CreateVideoOutputDevice (const OpalMediaFormat &mediaFormat, PBoolean preview, PVideoOutputDevice *&device, PBoolean &autoDelete)
virtual bool	SendVideoUpdatePicture (unsigned sessionID=0, int firstGOB=-1, int firstMB=-1, int numBlocks=0) const
virtual PBoolean	SetAudioVolume (PBoolean source, unsigned percentage)
virtual unsigned	GetAudioSignalLevel (PBoolean source)
Bandwidth Management
unsigned	GetBandwidthAvailable () const
virtual PBoolean	SetBandwidthAvailable (unsigned newBandwidth, PBoolean force=PFalse)
virtual unsigned	GetBandwidthUsed () const
virtual PBoolean	SetBandwidthUsed (unsigned releasedBandwidth, unsigned requiredBandwidth)
Member variable access
OpalEndPoint &	GetEndPoint () const
OpalCall &	GetCall () const
const PString &	GetToken () const
PBoolean	IsOriginating () const
PTime	GetSetupUpTime () const
PTime	GetAlertingTime () const
PTime	GetConnectionStartTime () const
PTime	GetConnectionEndTime () const
const OpalProductInfo &	GetProductInfo () const
void	SetProductInfo (const OpalProductInfo &info)
virtual PString	GetPrefixName () const
const PString &	GetLocalPartyName () const
virtual void	SetLocalPartyName (const PString &name)
virtual PString	GetLocalPartyURL () const
const PString &	GetDisplayName () const
void	SetDisplayName (const PString &name)
virtual bool	IsPresentationBlocked () const
const PString &	GetRemotePartyName () const
void	SetRemotePartyName (const PString &name)
const PString &	GetRemotePartyNumber () const
const PString &	GetRemotePartyAddress () const
void	SetRemotePartyAddress (const PString &addr)
virtual PString	GetRemotePartyURL () const
const PString	GetRemotePartyCallbackURL () const
PCaselessString	GetRemoteApplication () const
const OpalProductInfo &	GetRemoteProductInfo () const
const PString &	GetCalledPartyName () const
const PString &	GetCalledPartyNumber () const
virtual PString	GetCalledPartyURL ()
void	CopyPartyNames (const OpalConnection &other)
virtual PString	GetAlertingType () const
virtual bool	SetAlertingType (const PString &info)
unsigned	GetMinAudioJitterDelay () const
unsigned	GetMaxAudioJitterDelay () const
void	SetAudioJitterDelay (unsigned minDelay, unsigned maxDelay)
OpalSilenceDetector *	GetSilenceDetector () const
virtual PString	GetIdentifier () const
virtual PINDEX	GetMaxRtpPayloadSize () const
virtual OpalTransport &	GetTransport () const
	PDICTIONARY (MediaAddressesDict, POrdinalKey, OpalTransportAddress)
MediaAddressesDict &	GetMediaTransportAddresses ()
unsigned	GetVideoUpdateRequestsSent () const
Protected Types
	e_NotSwitchingFaxMediaStreams
	e_SwitchingToFaxMediaStreams
	e_SwitchingFromFaxMediaStreams
enum	{ e_NotSwitchingFaxMediaStreams, e_SwitchingToFaxMediaStreams, e_SwitchingFromFaxMediaStreams }
Protected Member Functions
void	OnConnectedInternal ()
	PDECLARE_NOTIFIER (PThread, OpalConnection, OnReleaseThreadMain)
	PDECLARE_NOTIFIER (RTP_DataFrame, OpalConnection, OnRecordAudio)
	PDECLARE_NOTIFIER (RTP_DataFrame, OpalConnection, OnRecordVideo)
void	OnStartRecording (OpalMediaPatch *patch)
void	OnStopRecording (OpalMediaPatch *patch)
Protected Attributes
RFC4103Context	m_rfc4103Context [2]
OpalCall &	ownerCall
OpalEndPoint &	endpoint
PString	callToken
PBoolean	originating
PTime	setupTime
PTime	alertingTime
PTime	connectedTime
PTime	callEndTime
OpalProductInfo	productInfo
PString	localPartyName
PString	displayName
PString	remotePartyName
PString	remotePartyURL
OpalProductInfo	remoteProductInfo
PString	remotePartyNumber
PString	remotePartyAddress
CallEndReason	callEndReason
bool	synchronousOnRelease
PString	m_calledPartyNumber
PString	m_calledPartyName
SendUserInputModes	sendUserInputMode
PString	userInputString
PSyncPoint	userInputAvailable
OpalSilenceDetector *	silenceDetector
MediaAddressesDict	mediaTransportAddresses
PSafeList< OpalMediaStream >	mediaStreams
unsigned	minAudioJitterDelay
unsigned	maxAudioJitterDelay
unsigned	bandwidthAvailable
StringOptions	m_connStringOptions
PString	m_recordingFilename
PNotifier	m_recordAudioNotifier
PNotifier	m_recordVideoNotifier
unsigned	m_VideoUpdateRequestsSent
AutoStartMap	m_autoStartInfo
enum OpalConnection:: { ... }	m_faxMediaStreamsSwitchState
Data Structures
struct	AutoStartInfo
class	AutoStartMap
struct	CallEndReason
class	StringOptions

Detailed Description

This is the base class for connections to an endpoint. A particular protocol will have a descendant class from this to implement the specific semantics of that protocols connection.

A connection is part of a call, and will be "owned" by an OpalCall object. It is also attached to the creator endpoint to do any protocol specific management of the connection. However the deletion of the connection is done by a special thread in the OpalManager class. A connnection should never be deleted directly.

The connection is also in charge of creating media streams. It may do this in respose to an explicit call to OpenMediaStream or implicitly due to requests in the underlying protocol.

When media streams are created they must make requests for bandwidth which is managed by the connection.

Member Enumeration Documentation

anonymous enum [protected]

Enumerator:

e_NotSwitchingFaxMediaStreams
e_SwitchingToFaxMediaStreams
e_SwitchingFromFaxMediaStreams

enum OpalConnection::AnswerCallResponse

Enumerator:

AnswerCallNow
AnswerCallDenied	Answer the call continuing with the connection.
AnswerCallPending	Refuse the call sending a release complete.
AnswerCallDeferred	Send an Alerting PDU and wait for AnsweringCall().
AnswerCallAlertWithMedia	As for AnswerCallPending but does not send Alerting PDU.
AnswerCallDeferredWithMedia	As for AnswerCallPending but starts media channels.
AnswerCallProgress	As for AnswerCallDeferred but starts media channels.
AnswerCallNowAndReleaseCurrent	Answer the call with a h323 progress, or sip 183 session in progress, or ...
NumAnswerCallResponses	Answer the call and destroy the current call.

enum OpalConnection::CallEndReasonCodes

Call/Connection ending reasons. NOTE: if anything is added to this, you also need to add the field to the tables in connection.cxx and h323pdu.cxx.

Enumerator:

EndedByLocalUser
EndedByNoAccept	Local endpoint application cleared call.
EndedByAnswerDenied	Local endpoint did not accept call OnIncomingCall()=PFalse.
EndedByRemoteUser	Local endpoint declined to answer call.
EndedByRefusal	Remote endpoint application cleared call.
EndedByNoAnswer	Remote endpoint refused call.
EndedByCallerAbort	Remote endpoint did not answer in required time.
EndedByTransportFail	Remote endpoint stopped calling.
EndedByConnectFail	Transport error cleared call.
EndedByGatekeeper	Transport connection failed to establish call.
EndedByNoUser	Gatekeeper has cleared call.
EndedByNoBandwidth	Call failed as could not find user (in GK).
EndedByCapabilityExchange	Call failed as could not get enough bandwidth.
EndedByCallForwarded	Could not find common capabilities.
EndedBySecurityDenial	Call was forwarded using FACILITY message.
EndedByLocalBusy	Call failed a security check and was ended.
EndedByLocalCongestion	Local endpoint busy.
EndedByRemoteBusy	Local endpoint congested.
EndedByRemoteCongestion	Remote endpoint busy.
EndedByUnreachable	Remote endpoint congested.
EndedByNoEndPoint	Could not reach the remote party.
EndedByHostOffline	The remote party is not running an endpoint.
EndedByTemporaryFailure	The remote party host off line.
EndedByQ931Cause	The remote failed temporarily app may retry.
EndedByDurationLimit	The remote ended the call with unmapped Q.931 cause code.
EndedByInvalidConferenceID	Call cleared due to an enforced duration limit.
EndedByNoDialTone	Call cleared due to invalid conference ID.
EndedByNoRingBackTone	Call cleared due to missing dial tone.
EndedByOutOfService	Call cleared due to missing ringback tone.
EndedByAcceptingCallWaiting	Call cleared because the line is out of service,.
EndedByGkAdmissionFailed	Call cleared because another call is answered.
NumCallEndReasons	Call cleared because gatekeeper admission request failed.

enum OpalConnection::Options

Connection options

Enumerator:

FastStartOptionDisable
FastStartOptionEnable
FastStartOptionMask
H245TunnelingOptionDisable
H245TunnelingOptionEnable
H245TunnelingOptionMask
H245inSetupOptionDisable
H245inSetupOptionEnable
H245inSetupOptionMask
DetectInBandDTMFOptionDisable
DetectInBandDTMFOptionEnable
DetectInBandDTMFOptionMask
RTPAggregationDisable
RTPAggregationEnable
RTPAggregationMask
SendDTMFAsDefault
SendDTMFAsString
SendDTMFAsTone
SendDTMFAsRFC2833
SendDTMFMask

enum OpalConnection::Phases

Different phases of a call, which are used in all OpalConnection instances. These phases are fully described in the documentation page Connection handling in the OPAL library.

Enumerator:

UninitialisedPhase	Indicates the OpalConnection instance has just been constructed.
SetUpPhase	In the process of sending/receiving the initial INVITE packet.
ProceedingPhase	The remote is now responsible for completing the call.
AlertingPhase	The remote says there is a phone ringing, somewhere.
ConnectedPhase	There is agreement on having a call, usually means billing will apply.
EstablishedPhase	Media is flowing, control streams are all operational.
ForwardingPhase	Connection is in the process of being forwarded.
ReleasingPhase	Hangup packet has been sent/received, media and control not yet stopped.
ReleasedPhase	Media and control streams have been terminated.
NumPhases	Number of available phases. Can be used to indicate an unknown phase.

enum OpalConnection::SendUserInputModes

Enumerator:

SendUserInputAsQ931
SendUserInputAsString
SendUserInputAsTone
SendUserInputAsInlineRFC2833
SendUserInputAsSeparateRFC2833
SendUserInputAsProtocolDefault
NumSendUserInputModes

Constructor & Destructor Documentation

OpalConnection::OpalConnection	(	OpalCall &	call,
		OpalEndPoint &	endpoint,
		const PString &	token,
		unsigned	options = `0`,
		OpalConnection::StringOptions *	stringOptions = `NULL`
	)

Create a new connection.

Parameters:

call	Owner calll for connection
endpoint	Owner endpoint for connection
token	Token to identify the connection
options	Connection options
stringOptions	more complex options

OpalConnection::~OpalConnection ( )

Destroy connection.

Member Function Documentation

virtual void OpalConnection::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.

Parameters:

local	Media formats a local ones to be presented to remote
mediaFormats	Media formats to use
otherConnection	Other connection we are adjusting media for

Reimplemented in OpalRTPConnection, and OpalFaxConnection.

virtual void OpalConnection::AnsweringCall ( AnswerCallResponse response ) [virtual]

Indicate the result of answering an incoming call. This should only be called if the OnAnswerCall() callback function has returned a AnswerCallPending or AnswerCallDeferred response.

Note sending further AnswerCallPending responses via this function will have the result of notification PDUs being sent to the remote endpoint (if possible). In this way multiple notification PDUs may be sent.

Sending a AnswerCallDeferred response would have no effect.

Parameters:

response

Answer response to incoming call

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

Reimplemented in H323Connection, OpalMixerConnection, and OpalFaxConnection.

virtual void OpalConnection::AttachRFC2833HandlerToPatch	(	PBoolean	isSource,
		OpalMediaPatch &	patch
	)			`[virtual]`

Attaches the RFC 2833 handler to the media patch This method may be called from subclasses, e.g. within OnPatchMediaStream()

Reimplemented in OpalRTPConnection.

virtual void OpalConnection::AutoStartMediaStreams ( bool force = false ) [virtual]

Open source media streams, if needed.

Parameters:

force

Force re-open even if already open

void OpalConnection::ClearCall ( CallEndReason reason = EndedByLocalUser )

Clear a current call. This hangs up the current call. This will release all connections currently in the call by calling the OpalCall::Clear() function.

Note that this function will return quickly as the release and disposal of the connections is done by another thread.

Parameters:

reason

Reason for call clearing

virtual void OpalConnection::ClearCallSynchronous	(	PSyncPoint *	sync,
		CallEndReason	reason = `EndedByLocalUser`
	)			`[virtual]`

Clear a current connection, synchronously

Parameters:

reason

Reason for call clearing

virtual bool OpalConnection::CloseMediaStream ( OpalMediaStream & stream ) [virtual]

Request close of a specific media stream. Note that this is usually asymchronous, the OnClosedMediaStream() function is called when the stream is really closed.

Parameters:

stream

Stream to close

Reimplemented in H323Connection, and SIPConnection.

virtual bool OpalConnection::CloseMediaStream	(	unsigned	sessionId,
		bool	source
	)			`[virtual]`

Request close of a media stream by session. Note that this is usually asymchronous, the OnClosedMediaStream() function is called when the stream is really closed.

Parameters:

sessionId	Session ID to search for.
source	Indicates the direction of stream.

virtual void OpalConnection::CloseMediaStreams ( ) [virtual]

Request close all media streams on connection.

void OpalConnection::CopyPartyNames ( const OpalConnection & other )

virtual OpalMediaStream* OpalConnection::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.

Parameters:

mediaFormat	Media format for stream
sessionID	Session number for stream
isSource	Is a source stream

Reimplemented in IAX2Connection, OpalLineConnection, OpalIVRConnection, OpalLocalConnection, OpalMixerConnection, OpalRTPConnection, and OpalFaxConnection.

virtual PBoolean OpalConnection::CreateVideoInputDevice	(	const OpalMediaFormat &	mediaFormat,
		PVideoInputDevice *&	device,
		PBoolean &	autoDelete
	)			`[virtual]`

Create an PVideoInputDevice for a source media stream.

Parameters:

mediaFormat	Media format for stream
device	Created device
autoDelete	Flag for auto delete device

virtual PBoolean OpalConnection::CreateVideoOutputDevice	(	const OpalMediaFormat &	mediaFormat,
		PBoolean	preview,
		PVideoOutputDevice *&	device,
		PBoolean &	autoDelete
	)			`[virtual]`

Create an PVideoOutputDevice for a sink media stream or the preview display for a source media stream.

Parameters:

mediaFormat	Media format for stream
preview	Flag indicating is a preview output
device	Created device
autoDelete	Flag for auto delete device

virtual void OpalConnection::DisableRecording ( ) [virtual]

virtual void OpalConnection::EnableRecording ( ) [virtual]

virtual PBoolean OpalConnection::ForwardCall ( const PString & forwardParty ) [virtual]

Forward incoming call to specified address. This would typically be called from within the OnIncomingCall() function when an application wishes to redirct an unwanted incoming call.

The return value is PTrue if the call is to be forwarded, PFalse otherwise. Note that if the call is forwarded the current connection is cleared with teh ended call code of EndedByCallForwarded.

Parameters:

forwardParty

Party to forward call to.

Reimplemented in H323Connection, IAX2Connection, and SIPConnection.

virtual bool OpalConnection::GarbageCollection ( ) [virtual]

Execute garbage collection for endpoint. Returns PTrue if all garbage has been collected. Default behaviour deletes the objects in the connectionsActive list.

PTime OpalConnection::GetAlertingTime ( ) const [inline]

Get the time at which the ALERTING was received

virtual PString OpalConnection::GetAlertingType ( ) const [virtual]

Get alerting type information of an incoming call. The type of "distinctive ringing" for the call. The string is protocol dependent, so the caller would need to be aware of the type of call being made. Some protocols may ignore the field completely.

For SIP this corresponds to the string contained in the "Alert-Info" header field of the INVITE. This is typically a URI for the ring file.

For H.323 this must be a string representation of an integer from 0 to 7 which will be contained in the Q.931 SIGNAL (0x34) Information Element.

Default behaviour returns an empty string.

Reimplemented in H323Connection, and SIPConnection.

virtual unsigned OpalConnection::GetAudioSignalLevel ( PBoolean source ) [virtual]

Get the average signal level (0..32767) for the audio media channel. A return value of UINT_MAX indicates no valid signal, eg no audio channel opened.

Parameters:

source

true for source (microphone), false for sink (speaker)

Reimplemented in OpalLineConnection.

virtual OpalMediaType::AutoStartMode OpalConnection::GetAutoStart ( const OpalMediaType & mediaType ) const [virtual]

Indicate whether a particular media type can auto-start. This is typically used for things like video or fax to contol if on initial connection, that media type is opened straight away. Streams of that type may be opened later, during the call, by using the OpalCall::OpenSourceMediaStreams() function.

Parameters:

mediaType

media type to check

unsigned OpalConnection::GetBandwidthAvailable ( ) const [inline]

Get the available bandwidth in 100's of bits/sec.

virtual unsigned OpalConnection::GetBandwidthUsed ( ) const [virtual]

Get the bandwidth currently used. This totals the bandwidth used by open streams and returns the total bandwidth used in 100's of bits/sec

Reimplemented in H323Connection.

OpalCall& OpalConnection::GetCall ( ) const [inline]

Get the owner call for this connection.

const PString& OpalConnection::GetCalledPartyName ( ) const [inline]

Get the called alias name (for incoming calls). This is useful for gateway applications where the destination name may not be the same as the local name.

Note that if the called party is anm E.164 address and there are no alternative names, such as aliases in H.323, then this field will be empty.

const PString& OpalConnection::GetCalledPartyNumber ( ) const [inline]

Get the called E.164 number (for incoming calls). This is useful for gateway applications where the destination number may not be the same as the local number.

Note that if the incoming call does not contain a legal E.164 number in it's addressing then this will return an empty string.

virtual PString OpalConnection::GetCalledPartyURL ( ) [virtual]

Get the fulll URL being indicated by the remote for incoming calls. This may not have any relation to the local name of the endpoint.

The default behaviour returns GetDestinationAddress() normalised to a URL. The remote may provide a full URL, if it does not then the prefix for the endpoint is prepended to the destination address.

Reimplemented in SIPConnection.

CallEndReason OpalConnection::GetCallEndReason ( ) const [inline]

Get the reason for this connection shutting down. Note that this function is only generally useful in the H323EndPoint::OnConnectionCleared() function. This is due to the connection not being cleared before that, and the object not even exiting after that.

If the call is still active then this will return NumCallEndReasons.

PString OpalConnection::GetCallEndReasonText ( ) const [inline]

static PString OpalConnection::GetCallEndReasonText ( CallEndReason reason ) [static]

Get the reason for this connection shutting down as text.

PTime OpalConnection::GetConnectionEndTime ( ) const [inline]

Get the time at which the connection was cleared

PTime OpalConnection::GetConnectionStartTime ( ) const [inline]

Get the time at which the connection was established

virtual PString OpalConnection::GetDestinationAddress ( ) [virtual]

Get the destination address of an incoming connection. This will, for example, collect a phone number from a POTS line, or get the fields from the H.225 SETUP pdu in a H.323 connection, or INVITE for SIP connection.

The default behaviour returns "*", which by convention means any address the endpoint/connection can get to.

Reimplemented in H323Connection, OpalLineConnection, and SIPConnection.

const PString& OpalConnection::GetDisplayName ( ) const [inline]

Get the local display name.

OpalEndPoint& OpalConnection::GetEndPoint ( ) const [inline]

Get the owner endpoint for this connection.

Reimplemented in H323Connection, and SIPConnection.

virtual PString OpalConnection::GetIdentifier ( ) const [virtual]

Get the protocol-specific unique identifier for this connection. Default behaviour just returns the connection token.

Reimplemented in H323Connection, and SIPConnection.

virtual OpalMediaFormatList OpalConnection::GetLocalMediaFormats ( ) [virtual]

Get the list of data formats used for making calls

The default behaviour is to call GetMediaFormats() on the owner call.

const PString& OpalConnection::GetLocalPartyName ( ) const [inline]

Get the local name/alias.

virtual PString OpalConnection::GetLocalPartyURL ( ) const [virtual]

Get the local name/alias.

Reimplemented in OpalIVRConnection, and SIPConnection.

unsigned OpalConnection::GetMaxAudioJitterDelay ( ) const [inline]

Get the default maximum audio delay jitter parameter. Defaults to 250ms.

virtual PINDEX OpalConnection::GetMaxRtpPayloadSize ( ) const [virtual]

Get the maximum transmitted RTP payload size. This function allows a user to override the value returned on a connection by connection basis, for example knowing the connection is on a LAN with ethernet MTU the payload size could be increased.

Defaults to the value returned by the OpalManager function of the same name.

virtual OpalMediaFormatList OpalConnection::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 in H323Connection, IAX2Connection, OpalLineConnection, OpalIVRConnection, OpalMixerConnection, SIPConnection, and OpalFaxConnection.

OpalMediaStreamPtr OpalConnection::GetMediaStream	(	const OpalMediaType &	mediaType,
		bool	source,
		OpalMediaStreamPtr	previous = `NULL`
	)			const

Get a media stream. Locates a stream given a media type. The source flag may be used to distinguish which stream durection to return.

If mediaType is empty (i.e. OpalMediaType()), then the first source/sink stream of any type, session or id is returned.

The previous parameter may be used to enumerate multiple stream of the same type and direction. If NULL then the first stream is returned.

Parameters:

mediaType	Media type to search for.
source	Indicates the direction of stream.
previous	Previous stream to start search from

OpalMediaStreamPtr OpalConnection::GetMediaStream	(	unsigned	sessionId,
		bool	source
	)			const

Get a media stream. Locates a stream given a RTP session ID. Each session would usually have two media streams associated with it, so the source flag may be used to distinguish which channel to return.

Parameters:

sessionId	Session ID to search for.
source	Indicates the direction of stream.

OpalMediaStreamPtr OpalConnection::GetMediaStream	(	const PString &	streamID,
		bool	source
	)			const

Get a media stream. Locates a stream given an identifier string.

If streamID is an empty string, then the first source/sink stream of any type, session or id is returned.

Parameters:

streamID	Stream ID to search for.
source	Indicates the direction of stream.

MediaAddressesDict& OpalConnection::GetMediaTransportAddresses ( ) [inline]

unsigned OpalConnection::GetMinAudioJitterDelay ( ) const [inline]

Get the default maximum audio jitter delay parameter. Defaults to 50ms

virtual unsigned OpalConnection::GetNextSessionID	(	const OpalMediaType &	mediaType,
		bool	isSource
	)			`[virtual]`

Get next available session ID for the media type.

Default behaviour returns zero indicating that this connection type does not care what the session ID is, and the other connection in the call should be asked. If neither care, then teh default of the media type is used.

Parameters:

mediaType	Media type of stream being opened
isSource	Stream is a source/sink

Reimplemented in H323Connection, and OpalRTPConnection.

PSafePtr<OpalConnection> OpalConnection::GetOtherPartyConnection ( ) const

Get the other connection in the call, if there is one.

template<class cls>

PSafePtr<cls> OpalConnection::GetOtherPartyConnectionAs ( ) const [inline]

Get the other connection in the call, if there is one.

Phases OpalConnection::GetPhase ( ) const [inline]

Get the phase of the connection. This indicates the current phase of the connection sequence. Whether all phases and the transitions between phases is protocol dependent.

virtual PString OpalConnection::GetPrefixName ( ) const [virtual]

Get this connections protocol prefix for URLs.

Reimplemented in H323Connection, OpalLineConnection, SIPConnection, and OpalFaxConnection.

const OpalProductInfo& OpalConnection::GetProductInfo ( ) const [inline]

Get the product info for all endpoints.

unsigned OpalConnection::GetQ931Cause ( ) const [inline]

Get the Q.931 cause code (Q.850) that terminated this call. See Q931::CauseValues for common values.

virtual SendUserInputModes OpalConnection::GetRealSendUserInputMode ( ) const [inline, virtual]

Get the real user input indication transmission mode. This will return the user input mode that will actually be used for transmissions. It will be the value of GetSendUserInputMode() provided the remote endpoint is capable of that mode.

Reimplemented in H323Connection, IAX2Connection, and SIPConnection.

PCaselessString OpalConnection::GetRemoteApplication ( ) const [inline]

Get the remote application description. This is for backward compatibility and has been supercedded by GeREmoteProductInfo();

const PString& OpalConnection::GetRemotePartyAddress ( ) const [inline]

Get the remote party address. This is typically a URL like sip:user@hostname, though it may be just a host address. It should not be used as a "call back" address, use the GetRemotePartyURL() function for that purpose.

const PString OpalConnection::GetRemotePartyCallbackURL ( ) const [inline]

const PString& OpalConnection::GetRemotePartyName ( ) const [inline]

Get the remote party display name.

const PString& OpalConnection::GetRemotePartyNumber ( ) const [inline]

Get the remote party number, if there was one one. If the remote party has indicated an E.1164 number as one of its aliases or some other field such as Q.931 Calling-Party-Number, then this function will return that number.

Note if none of the remote names are a legal E.164 number then an empty string is returned.

virtual PString OpalConnection::GetRemotePartyURL ( ) const [virtual]

Get the remote party address as URL. This will return the "best guess" at an address to use in a to call the user again later. Note that under some circumstances this may be different to the value GetRemotePartyAddress() value returns. In particular if a gatekeeper is involved.

Reimplemented in H323Connection.

const OpalProductInfo& OpalConnection::GetRemoteProductInfo ( ) const [inline]

Get the remote product info.

RFC4103Context& OpalConnection::GetRFC4103Context ( PINDEX i ) [inline]

Used for creating IM messages. 0 = used for sending internal 1 = used for sending external

virtual SendUserInputModes OpalConnection::GetSendUserInputMode ( ) const [inline, virtual]

Get the user input indication transmission mode.

PTime OpalConnection::GetSetupUpTime ( ) const [inline]

Get the time at which the connection was begun

OpalSilenceDetector* OpalConnection::GetSilenceDetector ( ) const [inline]

Get the silence detector active on connection.

const StringOptions& OpalConnection::GetStringOptions ( ) const [inline]

Get the string options associated with this connection.

const PString& OpalConnection::GetToken ( ) const [inline]

Get the token for this connection.

virtual OpalTransport& OpalConnection::GetTransport ( ) const [inline, virtual]

Reimplemented in H323Connection, and SIPConnection.

virtual PString OpalConnection::GetUserInput ( unsigned timeout = 30 ) [virtual]

Get a user input indication string, waiting until one arrives.

Parameters:

timeout

Timeout in seconds on input

unsigned OpalConnection::GetVideoUpdateRequestsSent ( ) const [inline]

Get Video Update requests statistic.

virtual bool OpalConnection::HoldConnection ( ) [virtual]

Put the current connection on hold, suspending all media streams.

Reimplemented in H323Connection, IAX2Connection, and SIPConnection.

virtual bool OpalConnection::IsConnectionOnHold ( bool fromRemote ) [virtual]

Return true if the current connection is on hold. The bool parameter indicates if we are testing if the remote system has us on hold, or we have them on hold.

Parameters:

fromRemote

Test if remote has us on hold, or we have them

Reimplemented in H323Connection, IAX2Connection, and SIPConnection.

virtual PBoolean OpalConnection::IsMediaBypassPossible ( unsigned sessionID ) const [virtual]

See if the media can bypass the local host.

The default behaviour returns PFalse indicating that media bypass is not possible.

Parameters:

sessionID

Session ID for media channel

Reimplemented in OpalRTPConnection.

virtual bool OpalConnection::IsNetworkConnection ( ) const [pure 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.

As a rule a network connection would have different names returned by GetLocalPartyName() and GetRemotePartyName() functions. A non-network connection, for ease of use, has a unique value for GetLocalPartyName() but, for convenience, uses the GetRemotePartyName() for the other connection in the call for it's GetRemotePartyName().

Implemented in H323Connection, IAX2Connection, OpalLineConnection, OpalIVRConnection, OpalLocalConnection, SIPConnection, and OpalFaxConnection.

PBoolean OpalConnection::IsOriginating ( ) const [inline]

Get the call direction for this connection.

virtual bool OpalConnection::IsPresentationBlocked ( ) const [virtual]

Determine if remote presentation of Caller-ID is to be blocked. Applies to an outgoing call to a "network" based endpoint type. Corresponds to Q.931 Calling-Party-Number Information Elementin H.323. Will remove display name for SIP.

virtual void OpalConnection::OnAlerting ( ) [virtual]

Call back for remote party being alerted. This function is called after the connection is informed that the remote endpoint is "ringing". Generally some time after the SetUpConnection() function was called, this is function is called.

If an application overrides this function, it should generally call the ancestor version for correct operation.

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

virtual AnswerCallResponse OpalConnection::OnAnswerCall ( const PString & callerName ) [virtual]

Call back for answering an incoming call. This function is called after the connection has been acknowledged but before the connection is established

This gives the application time to wait for some event before signalling to the endpoint that the connection is to proceed. For example the user pressing an "Answer call" button.

If AnswerCallDenied is returned the connection is aborted and the connetion specific end call PDU is sent. If AnswerCallNow is returned then the connection proceeding, Finally if AnswerCallPending is returned then the protocol negotiations are paused until the AnsweringCall() function is called.

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

Parameters:

callerName

Name of caller

Reimplemented in H323Connection.

virtual void OpalConnection::OnApplyStringOptions ( ) [virtual]

virtual void OpalConnection::OnClosedMediaStream ( const OpalMediaStream & stream ) [virtual]

Call back for closed a media stream.

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

Parameters:

stream

Media stream being closed

virtual void OpalConnection::OnConnected ( ) [virtual]

A call back function whenever a connection is "connected". This indicates that a connection to an endpoint was connected. That is the endpoint received acknowledgement via whatever protocol it uses that the connection may now start media streams.

In the context of H.323 this means that the CONNECT pdu has been received.

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

When this method is called, we are effectively being told that the remote endpoint has accepted our call and is now sending media to us.

Reimplemented in IAX2Connection.

void OpalConnection::OnConnectedInternal ( ) [protected]

virtual void OpalConnection::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 in H323Connection, IAX2Connection, OpalIVRConnection, and OpalFaxConnection.

virtual void OpalConnection::OnHold	(	bool	fromRemote,
		bool	onHold
	)			`[virtual]`

Call back indicating result of last hold/retrieve operation. This also indicates if the local connection has been put on hold by the remote connection.

Parameters:

fromRemote	Indicates remote has held local connection
onHold	Indicates have just been held/retrieved.

virtual PBoolean OpalConnection::OnIncomingConnection	(	unsigned int	options,
		OpalConnection::StringOptions *	stringOptions
	)			`[virtual]`

Call back for an incoming call. This function is used for an application to control the answering of incoming calls.

If PTrue is returned then the connection continues. If PFalse then the connection is aborted.

Note this function should not block for any length of time. If the decision to answer the call may take some time eg waiting for a user to pick up the phone, then AnswerCallPending or AnswerCallDeferred should be returned.

If an application overrides this function, it should generally call the ancestor version to complete calls. Unless the application completely takes over that responsibility. Generally, an application would only intercept this function if it wishes to do some form of logging. For this you can obtain the name of the caller by using the function OpalConnection::GetRemotePartyName().

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

Note that the most explicit version of this override is made pure, so as to force descendant classes to implement it. This will only affect code that implements new descendants of OpalConnection - code that uses existing descendants will be unaffected

virtual PBoolean OpalConnection::OnOpenMediaStream ( OpalMediaStream & stream ) [virtual]

Call back when opening a media stream. This function is called when a connection has created a new media stream according to the logic of its underlying protocol.

The usual requirement is that media streams are created on all other connections participating in the call and all of the media streams are attached to an instance of an OpalMediaPatch object that will read from one of the media streams passing data to the other media streams.

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

Parameters:

stream

New media stream being opened

Reimplemented in OpalLineConnection.

virtual void OpalConnection::OnPatchMediaStream	(	PBoolean	isSource,
		OpalMediaPatch &	patch
	)			`[virtual]`

Call back when patching a media stream. This function is called when a connection has created a new media patch between two streams. This is usually called twice per media patch, once for the source stream and once for the sink stream.

Note this is not called within the context of the patch thread and is called before that thread has started.

Parameters:

isSource	Is source/sink call
patch	New patch

Reimplemented in OpalRTPConnection.

virtual void OpalConnection::OnProceeding ( ) [virtual]

Call back for remote party is now responsible for completing the call. This function is called when the remote system has been contacted and it has accepted responsibility for completing, or failing, the call. This is distinct from OnAlerting() in that it is not known at this time if anything is ringing. This indication may be used to distinguish between "transport" level error, in which case another host may be tried, and that finalising the call has moved "upstream" and the local system has no more to do but await a result.

If an application overrides this function, it should generally call the ancestor version for correct operation.

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

virtual bool OpalConnection::OnReceiveExternalIM	(	const OpalMediaFormat &	format,
		RTP_IMFrame &	body
	)			`[virtual]`

Called when this connection receives an IM from the other end of the connection

virtual void OpalConnection::OnReceiveInternalIM	(	const OpalMediaFormat &	format,
		RTP_IMFrame &	body
	)			`[virtual]`

Called when this connection receives an IM from the other connection in the call

virtual void OpalConnection::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 in H323Connection, IAX2Connection, OpalLineConnection, OpalMixerConnection, SIPConnection, and OpalFaxConnection.

virtual PBoolean OpalConnection::OnSetUpConnection ( ) [virtual]

Callback for outgoing connection, it is invoked after SetUpConnection This function allows the application to set up some parameters or to log some messages

virtual void OpalConnection::OnStartMediaPatch ( OpalMediaPatch & patch ) [virtual]

Call back when media stream patch thread starts.

Parameters:

patch

Patch being started

Reimplemented in OpalMixerConnection, and OpalFaxConnection.

void OpalConnection::OnStartRecording ( OpalMediaPatch * patch ) [protected]

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

Call back when media stream patch thread stops.

Parameters:

patch

Patch being stopped

Reimplemented in OpalIVRConnection, and OpalFaxConnection.

void OpalConnection::OnStopRecording ( OpalMediaPatch * patch ) [protected]

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

Indicate status of switch to/from FAX mode.

Default behaviour does nothing.

Parameters:

enabledFax

Enabled FAX or audio mode

Reimplemented in OpalFaxConnection.

virtual void OpalConnection::OnUserInputString ( const PString & value ) [virtual]

Call back for remote enpoint has sent user input as a string. This will be called irrespective of the source (H.245 string, H.245 signal or RFC2833).

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

Parameters:

value

String value of indication

virtual void OpalConnection::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 in OpalFaxConnection.

virtual OpalMediaStreamPtr OpalConnection::OpenMediaStream	(	const OpalMediaFormat &	mediaFormat,
		unsigned	sessionID,
		bool	isSource
	)			`[virtual]`

Open source or sink media stream for session.

Parameters:

mediaFormat	Media format to open
sessionID	Session to start stream on
isSource	Stream is a source/sink

Reimplemented in H323Connection, OpalLocalConnection, and SIPConnection.

virtual void OpalConnection::PauseMediaStreams ( PBoolean paused ) [virtual]

Pause media streams for connection.

OpalConnection::PDECLARE_NOTIFIER	(	RTP_DataFrame	,
		OpalConnection	,
		OnRecordVideo
	)			`[protected]`

OpalConnection::PDECLARE_NOTIFIER	(	RTP_DataFrame	,
		OpalConnection	,
		OnRecordAudio
	)			`[protected]`

OpalConnection::PDECLARE_NOTIFIER	(	PThread	,
		OpalConnection	,
		OnReleaseThreadMain
	)			`[protected]`

OpalConnection::PDECLARE_NOTIFIER	(	OpalMediaCommand	,
		OpalConnection	,
		OnMediaCommand
	)

Notifier function for OpalVideoUpdatePicture. Calls the SendIntraFrameRequest on the rtp session

OpalConnection::PDICTIONARY	(	MediaAddressesDict	,
		POrdinalKey	,
		OpalTransportAddress
	)

void OpalConnection::PrintOn ( ostream & strm ) const

Standard stream print function. The PObject class has a << operator defined that invokes this function polymorphically.

Parameters:

strm

Stream to output text representation

virtual PBoolean OpalConnection::PromptUserInput ( PBoolean play ) [virtual]

Play a prompt to the connection before rading user indication string.

For example the LID connection would play a dial tone.

The default behaviour does nothing.

Parameters:

play

Flag to start or stop playing the prompt

Reimplemented in OpalLineConnection.

virtual PString OpalConnection::ReadUserInput	(	const char *	terminators = `"#\r\n"`,
		unsigned	lastDigitTimeout = `4`,
		unsigned	firstDigitTimeout = `30`
	)			`[virtual]`

Read a sequence of user indications with timeouts.

Parameters:

terminators	Characters that can terminte input
lastDigitTimeout	Timeout on last digit in string
firstDigitTimeout	Timeout on receiving any digits

virtual void OpalConnection::Release ( CallEndReason reason = EndedByLocalUser ) [virtual]

Release the current connection. This removes the connection from the current call. The call may continue if there are other connections still active on it. If this was the last connection for the call then the call is disposed of as well.

Note that this function will return quickly as the release and disposal of the connections is done by another thread.

Parameters:

reason

Reason for call release

bool OpalConnection::RemoveMediaStream ( OpalMediaStream & strm )

Remove the specified media stream from the list of streams for this channel. This will automatically delete the stream if the stream was found in the stream list.

Returns true if the media stream was removed the list and deleted, else returns false if the media stream was unchanged

virtual bool OpalConnection::RetrieveConnection ( ) [virtual]

Retrieve the current connection from hold, activating all media streams.

Reimplemented in H323Connection, IAX2Connection, and SIPConnection.

void OpalConnection::SendUserInputHookFlash ( unsigned duration = 500 ) [inline]

Send a user input indication to the remote endpoint. This sends a Hook Flash emulation user input.

Parameters:

duration

Duration of tone in milliseconds

virtual PBoolean OpalConnection::SendUserInputString ( const PString & value ) [virtual]

Send a user input indication to the remote endpoint. This is for sending arbitrary strings as user indications.

The default behaviour is to call SendUserInputTone() for each character in the string.

Parameters:

value

String value of indication

Reimplemented in H323Connection, IAX2Connection, OpalLineConnection, OpalIVRConnection, and OpalLocalConnection.

virtual PBoolean OpalConnection::SendUserInputTone	(	char	tone,
		unsigned	duration = `0`
	)			`[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.

Parameters:

tone	DTMF tone code
duration	Duration of tone in milliseconds

Reimplemented in H323Connection, IAX2Connection, OpalRTPConnection, SIPConnection, and OpalFaxConnection.

virtual bool OpalConnection::SendVideoUpdatePicture	(	unsigned	sessionID = `0`,
		int	firstGOB = `-1`,
		int	firstMB = `-1`,
		int	numBlocks = `0`
	)			const `[virtual]`

Send a Video Update Picture request to media stream.

Parameters:

sessionID	Session for media stream, 0 is use first Video stream
firstGOB	First Group Of Blocks for update, -1 is use MB
firstMB	First Macro Block for update, -1 is use GOB
numBlocks	First Group Of Blocks for update, 0 is all

virtual PBoolean OpalConnection::SetAlerting	(	const PString &	calleeName,
		PBoolean	withMedia
	)			`[pure 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 remoteendpoint is "ringing".

The default behaviour is pure.

Parameters:

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

Implemented in H323Connection, IAX2Connection, OpalLineConnection, OpalLocalConnection, SIPConnection, and OpalFaxConnection.

virtual bool OpalConnection::SetAlertingType ( const PString & info ) [virtual]

Set alerting type information for outgoing call. The type of "distinctive ringing" for the call. The string is protocol dependent, so the caller would need to be aware of the type of call being made. Some protocols may ignore the field completely.

For SIP this corresponds to the string contained in the "Alert-Info" header field of the INVITE. This is typically a URI for the ring file.

For H.323 this must be a string representation of an integer from 0 to 7 which will be contained in the Q.931 SIGNAL (0x34) Information Element.

Default behaviour returns false.

Reimplemented in H323Connection, and SIPConnection.

void OpalConnection::SetAudioJitterDelay	(	unsigned	minDelay,
		unsigned	maxDelay
	)

Set the maximum audio delay jitter parameter.

Parameters:

minDelay	New minimum jitter buffer delay in milliseconds
maxDelay	New maximum jitter buffer delay in milliseconds

virtual PBoolean OpalConnection::SetAudioVolume	(	PBoolean	source,
		unsigned	percentage
	)			`[virtual]`

Set the volume (gain) for the audio media channel to the specified percentage.

Parameters:

source	true for source (microphone), false for sink (speaker)
percentage	Gain, 0=silent, 100=maximun

Reimplemented in OpalLineConnection.

virtual PBoolean OpalConnection::SetBandwidthAvailable	(	unsigned	newBandwidth,
		PBoolean	force = `PFalse`
	)			`[virtual]`

Set the available bandwidth in 100's of bits/sec. Note if the force parameter is PTrue this function will close down active media streams to meet the new bandwidth requirement.

Parameters:

newBandwidth	New bandwidth limit
force	Force bandwidth limit

Reimplemented in H323Connection.

virtual PBoolean OpalConnection::SetBandwidthUsed	(	unsigned	releasedBandwidth,
		unsigned	requiredBandwidth
	)			`[virtual]`

Set the used bandwidth in 100's of bits/sec. This is an internal function used by the OpalMediaStream bandwidth management code.

If there is insufficient bandwidth available, PFalse is returned. If sufficient bandwidth is available, then PTrue is returned and the amount of available bandwidth is reduced by the specified amount.

Parameters:

releasedBandwidth	Bandwidth to release
requiredBandwidth	Bandwidth required

virtual void OpalConnection::SetCallEndReason ( CallEndReason reason ) [virtual]

Set the call clearance reason. An application should have no cause to use this function. It is present for the H323EndPoint::ClearCall() function to set the clearance reason.

Parameters:

reason

Reason for clearance of connection.

static void OpalConnection::SetCallEndReasonText	(	CallEndReasonCodes	reasonCode,
		const PString &	newText
	)			`[static]`

Get the reason for this connection shutting down as text.

virtual PBoolean OpalConnection::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 in H323Connection, IAX2Connection, OpalLineConnection, OpalLocalConnection, SIPConnection, and OpalFaxConnection.

void OpalConnection::SetDisplayName ( const PString & name ) [inline]

Set the local display name.

virtual void OpalConnection::SetLocalPartyName ( const PString & name ) [virtual]

Set the local name/alias.

Reimplemented in H323Connection.

void OpalConnection::SetPhase ( Phases phaseToSet )

Set the phase of the connection. Note that this is primarily for internal use and calling from user code is likely to have very strange results.

Parameters:

phaseToSet

phaseToSet the phase to set

void OpalConnection::SetProductInfo ( const OpalProductInfo & info ) [inline]

Set the product info for all endpoints.

void OpalConnection::SetQ931Cause ( unsigned v ) [inline]

Set the outgoing Q.931 cause code (Q.850) that is sent for this call See Q931::CauseValues for common values.

void OpalConnection::SetRemotePartyAddress ( const PString & addr ) [inline]

Set the remote party address.

void OpalConnection::SetRemotePartyName ( const PString & name ) [inline]

Set the remote party display name.

virtual void OpalConnection::SetSendUserInputMode ( SendUserInputModes mode ) [virtual]

Set the user input indication transmission mode.

void OpalConnection::SetStringOptions	(	const StringOptions &	options,
		bool	overwrite
	)

Set the string options associated with this connection.

virtual PBoolean OpalConnection::SetUpConnection ( ) [pure 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 is pure.

Implemented in H323Connection, IAX2Connection, OpalLineConnection, OpalLocalConnection, SIPConnection, and OpalFaxConnection.

virtual void OpalConnection::SetUserInput ( const PString & input ) [virtual]

Set a user indication string. This allows the GetUserInput() function to unblock and return this string.

Parameters:

input

Input string

virtual void OpalConnection::StartMediaStreams ( ) [virtual]

Start all media streams for connection.

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

Switch to/from FAX mode.

Parameters: