#include <connection.h>

Inheritance diagram for OpalConnection:

Collaboration diagram for OpalConnection:

Data Structures
struct	CallEndReason

class	StringOptions

class	ZeroTime

Public Types
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
	P_DECLARE_TRACED_ENUM_EX (CallEndReasonCodes, NumCallEndReasons, EndedByLocalUser, 0, 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, EndedByMediaFailed, EndedByCallCompletedElsewhere, EndedByCertificateAuthority, EndedByIllegalAddress, EndedByCustomCode)

	P_DECLARE_TRACED_ENUM (AnswerCallResponse, AnswerCallNow, AnswerCallDenied, AnswerCallPending, AnswerCallDeferred, AnswerCallAlertWithMedia, AnswerCallDeferredWithMedia, AnswerCallProgress, AnswerCallNowAndReleaseCurrent)

const StringOptions &	GetStringOptions () const
	Get the string options associated with this connection. More...

StringOptions &	GetStringOptions ()

void	SetStringOptions (const StringOptions &options, bool overwrite)
	Set the string options associated with this connection. More...

virtual void	OnApplyStringOptions ()
	Call back for connection to act on changed string options. More...

virtual void	EnableRecording ()

virtual void	DisableRecording ()

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 ()

virtual PBoolean	OnSetUpConnection ()

virtual void	OnProceeding ()

virtual void	OnAlerting ()

virtual PBoolean	SetAlerting (const PString &calleeName, PBoolean withMedia)

virtual AnswerCallResponse	OnAnswerCall (const PString &callerName)

virtual void	AnsweringCall (AnswerCallResponse response)

virtual void	OnConnected ()

virtual PBoolean	SetConnected ()

virtual void	OnEstablished ()

virtual bool	OnTransferNotify (const PStringToString &info, const OpalConnection *transferringConnection)

virtual void	Release (CallEndReason reason=EndedByLocalUser, bool synchronous=false)

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, const OpalConnection *otherConnection, OpalMediaFormatList &mediaFormats) const

virtual PStringArray	GetMediaCryptoSuites () const

virtual unsigned	GetNextSessionID (const OpalMediaType &mediaType, bool isSource)

virtual bool	RequireSymmetricMediaStreams () const

virtual OpalMediaType::AutoStartMode	GetAutoStart (const OpalMediaType &mediaType) const

virtual void	AutoStartMediaStreams (bool transfer=false)

virtual OpalMediaStreamPtr	OpenMediaStream (const OpalMediaFormat &mediaFormat, unsigned sessionID, bool isSource)

bool	CloseMediaStream (unsigned sessionId, bool source)

bool	CloseMediaStream (OpalMediaStreamPtr stream)

bool	RemoveMediaStream (OpalMediaStream &strm)

virtual void	StartMediaStreams ()

virtual void	CloseMediaStreams ()

virtual void	PauseMediaStreams (bool paused)

virtual void	OnPauseMediaStream (OpalMediaStream &strm, bool 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	OnFailedMediaStream (bool fromRemote, const PString &reason)

virtual void	OnPatchMediaStream (PBoolean isSource, OpalMediaPatch &patch)

virtual void	OnStartMediaPatch (OpalMediaPatch &patch)

virtual void	OnStopMediaPatch (OpalMediaPatch &patch)

virtual bool	OnMediaFailed (unsigned sessionId, bool source)

bool	AllMediaFailed () const

virtual bool	OnMediaCommand (OpalMediaStream &stream, const OpalMediaCommand &command)

virtual bool	ExecuteMediaCommand (const OpalMediaCommand &command, unsigned sessionID=0, const OpalMediaType &mediaType=OpalMediaType()) const

virtual bool	GetMediaTransportAddresses (OpalConnection &otherConnection, const OpalMediaType &mediaType, OpalTransportAddressArray &transports) const

virtual bool	SendVideoUpdatePicture (unsigned sessionID=0, bool force=false) const

void	SendVideoUpdatePictureCallback (unsigned sessionID, bool force)

virtual void	OnRxIntraFrameRequest (const OpalMediaSession &session, bool force)

virtual PBoolean	SetAudioVolume (PBoolean source, unsigned percentage)

virtual PBoolean	GetAudioVolume (PBoolean source, unsigned &percentage)

virtual bool	SetAudioMute (bool source, bool mute)

virtual bool	GetAudioMute (bool source, bool &mute)

virtual unsigned	GetAudioSignalLevel (PBoolean source)

Bandwidth Management
OpalBandwidth	GetBandwidthAvailable (OpalBandwidth::Direction dir) const

virtual bool	SetBandwidthAvailable (OpalBandwidth::Direction dir, OpalBandwidth availableBandwidth)

virtual bool	SetBandwidthAllocated (OpalBandwidth::Direction dir, OpalBandwidth newBandwidth)

virtual OpalBandwidth	GetBandwidthUsed (OpalBandwidth::Direction dir) const

virtual bool	SetBandwidthUsed (OpalBandwidth::Direction dir, OpalBandwidth releasedBandwidth, OpalBandwidth requiredBandwidth)

User input
	P_DECLARE_TRACED_ENUM (SendUserInputModes, SendUserInputAsQ931, SendUserInputAsString, SendUserInputAsTone, SendUserInputAsRFC2833, SendUserInputAsInlineRFC2833=SendUserInputAsRFC2833, SendUserInputInBand, SendUserInputAsProtocolDefault)

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)

void	OnUserInputStringCallback (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="YX#\r\n", unsigned lastDigitTimeout=4, unsigned firstDigitTimeout=30)

virtual PBoolean	PromptUserInput (PBoolean play)

Miscellaneous
virtual bool	GetConferenceState (OpalConferenceState *state) const

virtual bool	RequestPresentationRole (bool release)

virtual bool	OnChangedPresentationRole (const PString &newChairURI, bool request)

virtual bool	HasPresentationRole () const

virtual bool	GarbageCollection ()

Member variable access
OpalEndPoint &	GetEndPoint () const

OpalCall &	GetCall () const

const PString &	GetToken () const

PBoolean	IsOriginating () const

const PTime &	GetPhaseTime (Phases phase) const

const PTime &	GetSetupUpTime () const

const PTime &	GetAlertingTime () const

const PTime &	GetConnectionStartTime () const

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

virtual OpalTransportAddress	GetRemoteAddress () const

virtual PString	GetRemotePartyURL () const

virtual PString	GetRemoteIdentity () const

P_DEPRECATED PString	GetRemotePartyAddress () const

P_DEPRECATED const PString	GetRemotePartyCallbackURL () const

PCaselessString	GetRemoteApplication () const

const OpalProductInfo &	GetRemoteProductInfo () const

const PString &	GetRedirectingParty () const

void	SetRedirectingParty (const PString &party)

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)

virtual PString	GetCallInfo () const

unsigned	GetMinAudioJitterDelay () const

unsigned	GetMaxAudioJitterDelay () const

void	SetAudioJitterDelay (unsigned minDelay, unsigned maxDelay)

OpalSilenceDetector *	GetSilenceDetector () const

virtual PString	GetIdentifier () const

virtual PINDEX	GetMaxRtpPayloadSize () const

unsigned	GetVideoUpdateRequestsSent () const

unsigned	GetVideoUpdateRequestsReceived () const

Protected Member Functions
void	OnConnectedInternal ()

void	InternalSetAsOriginating ()

bool	InternalRelease (CallEndReason reason)

void	InternalOnReleased ()

	PDECLARE_NOTIFIER (RTP_DataFrame, OpalConnection, OnRecordAudio)

	PDECLARE_NOTIFIER (RTP_DataFrame, OpalConnection, OnRecordVideo)

void	OnStartRecording (OpalMediaPatch *patch)

void	OnStopRecording (OpalMediaPatch *patch)

Protected Attributes
OpalCall &	ownerCall

OpalEndPoint &	endpoint

PString	callToken

PBoolean	m_originating

OpalProductInfo	productInfo

PString	localPartyName

PString	displayName

PString	remotePartyName

PString	m_remotePartyURL

OpalProductInfo	remoteProductInfo

PString	remotePartyNumber

PString	m_redirectingParty

CallEndReason	callEndReason

PString	m_calledPartyNumber

PString	m_calledPartyName

SendUserInputModes	sendUserInputMode

PString	userInputString

PSyncPoint	userInputAvailable

OpalSilenceDetector *	silenceDetector

OpalMediaFormat	m_filterMediaFormat

OpalMediaFormatList	m_localMediaFormats

PSafeList< OpalMediaStream >	mediaStreams

unsigned	m_minAudioJitterDelay

unsigned	m_maxAudioJitterDelay

OpalBandwidth	m_rxBandwidthAvailable

OpalBandwidth	m_txBandwidthAvailable

StringOptions	m_stringOptions

PString	m_recordingFilename

PNotifier	m_recordAudioNotifier

PNotifier	m_recordVideoNotifier

unsigned	m_VideoUpdateRequestsSent

unsigned	m_VideoUpdateRequestsReceived

OpalMediaType::AutoStartMap	m_autoStartInfo

ZeroTime	m_phaseTime [NumPhases]

std::set< unsigned >	m_mediaSessionFailed

Basic operations
virtual bool	IsNetworkConnection () const =0

	P_DECLARE_TRACED_ENUM (Phases, UninitialisedPhase, SetUpPhase, ProceedingPhase, AlertingPhase, ConnectedPhase, EstablishedPhase, ForwardingPhase, ReleasingPhase, ReleasedPhase)

__inline Phases	GetPhase () const

__inline bool	IsEstablished () const
	Return true if connection is in the established phase. More...

__inline bool	IsReleased () const
	Return true if connection is in the established phase. More...

void	SetPhase (Phases phaseToSet)

CallEndReason	GetCallEndReason () const

PString	GetCallEndReasonText () const

virtual void	SetCallEndReason (CallEndReason reason)

void	ClearCall (CallEndReason reason=EndedByLocalUser, PSyncPoint *sync=NULL)

virtual void	ClearCallSynchronous (PSyncPoint *sync, CallEndReason reason=EndedByLocalUser)

unsigned	GetQ931Cause () const

void	SetQ931Cause (unsigned v)

virtual bool	TransferConnection (const PString &remoteParty)

virtual bool	HoldRemote (bool placeOnHold)

virtual bool	IsOnHold (bool fromRemote) const

virtual void	OnHold (bool fromRemote, bool onHold)

static PString	GetCallEndReasonText (CallEndReason reason)

static void	SetCallEndReasonText (CallEndReasonCodes reasonCode, const PString &newText)

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

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

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	Option bit map to be passed to connection
stringOptions	Options to be passed to connection

OpalConnection::~OpalConnection ( )

Destroy connection.

Member Function Documentation

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

Parameters

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

Reimplemented in OpalRTPConnection.

bool OpalConnection::AllMediaFailed ( ) const

Indicate all media sessions have failed.

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

Reimplemented in H323Connection, and IAX2Connection.

virtual void OpalConnection::AutoStartMediaStreams ( bool transfer = false )

virtual

Open source media streams, if needed.

Parameters

transfer Executing an internal transfer

void OpalConnection::ClearCall	(	CallEndReason	reason = `EndedByLocalUser`,
		PSyncPoint *	sync = `NULL`
	)

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.

If sync is not NULL then it is signalled when the calls are cleared.

Parameters

reason Reason for call clearing

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

virtual

Clear a current connection, synchronously. This hangs up the connection to a remote endpoint. Note that this function is always synchronous. If sync is NULL then a local PSyncPoint is used.

Parameters

sync	Synchronisation object to signal
reason	Reason for call clearing

bool OpalConnection::CloseMediaStream	(	unsigned	sessionId,
		bool	source
	)

Close of a media stream by session.

Parameters

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

bool OpalConnection::CloseMediaStream ( OpalMediaStreamPtr stream )

Close of a media stream.

Parameters

stream Stream to close.

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 OpalMixerConnection, OpalLocalConnection, OpalPCSSConnection, OpalLineConnection, SIPConnection, OpalIVRConnection, IAX2Connection, and OpalRTPConnection.

virtual void OpalConnection::DisableRecording ( )

virtual

virtual void OpalConnection::EnableRecording ( )

virtual

virtual bool OpalConnection::ExecuteMediaCommand	(	const OpalMediaCommand &	command,
		unsigned	sessionID = `0`,
		const OpalMediaType &	mediaType = `OpalMediaType()`
	)		const

virtual

Execute media commands. Calls the SendIntraFrameRequest on the rtp session

Returns: true if command is handled.

Parameters

command	Media command to be executed
sessionID	Session for media stream, 0 is use first `mediaType` stream
mediaType	Media type to search for in open streams

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 true if the call is to be forwarded, false 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, SIPConnection, and IAX2Connection.

virtual bool OpalConnection::GarbageCollection ( )

virtual

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

Reimplemented in SIPConnection, and OpalRTPConnection.

const PTime& OpalConnection::GetAlertingTime ( ) const

inline

Get the time at which the ALERTING/18x 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 SIPConnection, and H323Connection.

virtual bool OpalConnection::GetAudioMute	(	bool	source,
		bool &	mute
	)

virtual

Get the mute state for the audio media channel.

Parameters

source	true for source (microphone), false for sink (speaker)
mute	Flag for muted audio

Reimplemented in OpalPCSSConnection.

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 OpalPCSSConnection, and OpalLineConnection.

virtual PBoolean OpalConnection::GetAudioVolume	(	PBoolean	source,
		unsigned &	percentage
	)

virtual

Get the volume (gain) for the audio media channel. The volume range is 0 == muted, 100 == LOUDEST.

Parameters

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

Reimplemented in OpalPCSSConnection.

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

OpalBandwidth OpalConnection::GetBandwidthAvailable ( OpalBandwidth::Direction dir ) const

Get the available rx and/or tx bandwidth in bits/sec.

Parameters

dir	Bandwidth direction

virtual OpalBandwidth OpalConnection::GetBandwidthUsed ( OpalBandwidth::Direction dir ) const

virtual

Get the rx and/or tx bandwidth currently used. This totals the bandwidth used by open streams and returns that bandwidth used in bits/sec

Parameters

dir	Bandwidth direction

Reimplemented in H323Connection.

OpalCall& OpalConnection::GetCall ( ) const

inline

Get the owner call for this connection.

References callToken.

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 OpalEndPoint::OnClearedCall() function. This is due to the connection not being cleared before that, and the object not even existing after that.

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

static PString OpalConnection::GetCallEndReasonText ( CallEndReason reason )

static

Get the reason for this connection shutting down as text.

PString OpalConnection::GetCallEndReasonText ( ) const

inline

Referenced by OpalCall::GetCallEndReasonText().

virtual PString OpalConnection::GetCallInfo ( ) const

virtual

Get call information of an incoming call. This is protocol dependent information provided about the call. The details are outside the scope of this help.

For SIP this corresponds to the string contained in the "Call-Info" header field of the INVITE.

Reimplemented in SIPConnection.

virtual bool OpalConnection::GetConferenceState ( OpalConferenceState * state ) const

virtual

Get Conference state information. This obtains the state information about a conference this connection is directly a part of. If the connection type does not embody a conference then false is returned.

The state parameter, if non-NULL, is illed with the state of the conference. When NULL, this just indicates that the connection is part of a conference with the return value.

Default behaviour is to return false which indicates this connection is not part of a conference.

Parameters

state Optional conference state information

Reimplemented in OpalMixerConnection.

const PTime& OpalConnection::GetConnectionEndTime ( ) const

inline

Get the time at which the connection was cleared

References productInfo.

const PTime& OpalConnection::GetConnectionStartTime ( ) const

inline

Get the time at which the connection was started. This is where the H.323 CONNECT or SIP 200 OK is received and generally indicates the start of te billable period for a call.

References m_phaseTime.

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 OpalLineConnection, H323Connection, and SIPConnection.

const PString& OpalConnection::GetDisplayName ( ) const

inline

Get the local display name.

References displayName.

OpalEndPoint& OpalConnection::GetEndPoint ( ) const

inline

Get the owner endpoint for this connection.

References ownerCall.

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 SIPConnection, and OpalIVRConnection.

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 PStringArray OpalConnection::GetMediaCryptoSuites ( ) const

virtual

Get media security methods in priority order. Returns an array of names for security methods, e.g. { "Clear", "AES_CM_128_HMAC_SHA1_80", "AES_CM_128_HMAC_SHA1_32" }.

Reimplemented in H323Connection.

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 OpalMixerConnection, OpalLineConnection, SIPConnection, H323Connection, OpalIVRConnection, and IAX2Connection.

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.

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

virtual bool OpalConnection::GetMediaTransportAddresses	(	OpalConnection &	otherConnection,
		const OpalMediaType &	mediaType,
		OpalTransportAddressArray &	transports
	)		const

virtual

Get transports for the media session on the connection. This is primarily used by the media bypass feature controlled by the OpalManager::GetMediaTransferMode() function. It allows one side of the call to get the transport address of the media on the other side, so it can pass it on, bypassing the local host.

Returns: true if a transport address is available and may be used to pass on to a remote system for direct access.

Parameters

otherConnection	Other half of call needing media transport addresses
mediaType	Media type for session to return information
transports	Information on media session

Reimplemented in SIPConnection, H323Connection, and OpalRTPConnection.

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.

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

const PTime& OpalConnection::GetPhaseTime ( Phases phase ) const

inline

Get the time at which the phase of the call was entered.

References m_phaseTime.

virtual PString OpalConnection::GetPrefixName ( ) const

virtual

Get this connections protocol prefix for URLs.

Reimplemented in OpalLineConnection, SIPConnection, and H323Connection.

const OpalProductInfo& OpalConnection::GetProductInfo ( ) const

inline

Get the product info for all endpoints.

References productInfo.

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

inlinevirtual

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, and SIPConnection.

const PString& OpalConnection::GetRedirectingParty ( ) const

inline

Get the redirecting party. This is the party that caused an incoming call to arrive at this endpoint.

virtual OpalTransportAddress OpalConnection::GetRemoteAddress ( ) const

inlinevirtual

Get the remote transport address

Reimplemented in H323Connection, and SIPConnection.

PCaselessString OpalConnection::GetRemoteApplication ( ) const

inline

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

References remoteProductInfo.

virtual PString OpalConnection::GetRemoteIdentity ( ) const

inlinevirtual

Get the remote identity. Under some circumstances the "identity" of the remote party, may be different from the name, number or URL for that user. For example, this would be the P-Asserted-Identity field in SIP.

Reimplemented in SIPConnection.

References GetRemotePartyURL().

P_DEPRECATED PString OpalConnection::GetRemotePartyAddress ( ) const

inline

References OpalProductInfo::AsString(), and remoteProductInfo.

P_DEPRECATED const PString OpalConnection::GetRemotePartyCallbackURL ( ) const

inline

const PString& OpalConnection::GetRemotePartyName ( ) const

inline

Get the remote party display name.

References remotePartyName.

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.

Referenced by GetRemoteIdentity().

const OpalProductInfo& OpalConnection::GetRemoteProductInfo ( ) const

inline

Get the remote product info.

virtual SendUserInputModes OpalConnection::GetSendUserInputMode ( ) const

inlinevirtual

Get the user input indication transmission mode.

const PTime& OpalConnection::GetSetupUpTime ( ) const

inline

Get the time at which the connection was begun

References m_phaseTime.

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.

StringOptions& OpalConnection::GetStringOptions ( )

inline

const PString& OpalConnection::GetToken ( ) const

inline

Get the token for this connection.

References m_originating.

Referenced by H323Connection::GetCallToken().

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::GetVideoUpdateRequestsReceived ( ) const

inline

Get Video Update requests received statistic.

unsigned OpalConnection::GetVideoUpdateRequestsSent ( ) const

inline

Get Video Update requests sent statistic.

References m_VideoUpdateRequestsReceived.

virtual bool OpalConnection::HasPresentationRole ( ) const

virtual

Indicate current presentation token ownership.

Default behaviour returns false.

Reimplemented in H323Connection.

virtual bool OpalConnection::HoldRemote ( bool placeOnHold )

virtual

Put the current connection on hold, suspending media streams. The streams from the remote are always paused. The streams from the local to the remote are conditionally paused depending on underlying logic for "music on hold" functionality.

The fromRemote parameter indicates if we a putting the remote on hold (false) or it is a request for the remote to put us on hold (true).

The /p placeOnHold parameter indicates of the command/request is for going on hold or retrieving from hold.

Returns: true if hold request successfully initiated. The OnHold() call back must be monitored for final confirmation of hold state.

Parameters

placeOnHold Flag for setting on or off hold

Reimplemented in H323Connection, OpalLocalConnection, IAX2Connection, and SIPConnection.

void OpalConnection::InternalOnReleased ( )

protected

bool OpalConnection::InternalRelease ( CallEndReason reason )

protected

void OpalConnection::InternalSetAsOriginating ( )

protected

__inline bool OpalConnection::IsEstablished ( ) const

inline

Return true if connection is in the established phase.

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 OpalLocalConnection, OpalLineConnection, OpalIVRConnection, OpalIMConnection, SIPConnection, H323Connection, and IAX2Connection.

virtual bool OpalConnection::IsOnHold ( bool fromRemote ) const

virtual

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

Parameters

fromRemote Flag for if remote has us on hold, or we have them

Reimplemented in H323Connection, IAX2Connection, and SIPConnection.

PBoolean OpalConnection::IsOriginating ( ) const

inline

Get the call direction for this connection.

References m_phaseTime.

Referenced by H323Connection::HadAnsweredCall().

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.

__inline bool OpalConnection::IsReleased ( ) const

inline

Return true if connection is in the established phase.

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

Call back for connection to act on changed string options.

Reimplemented in OpalMixerConnection, OpalLocalConnection, SIPConnection, and H323Connection.

virtual bool OpalConnection::OnChangedPresentationRole	(	const PString &	newChairURI,
		bool	request
	)

virtual

Indicate presentation token change. The request parameter indicates if this is an "after the fact" indication has changed, or if the connection may reject the change and retain the token it already has.

Default behaviour returns true.

Parameters

newChairURI	URI for new confernce chair
request	Indicates change is requested

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

Reimplemented in OpalLocalConnection, OpalLineConnection, SIPConnection, and H323Connection.

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 OpalIMConnection, OpalIVRConnection, H323Connection, and IAX2Connection.

virtual void OpalConnection::OnFailedMediaStream	(	bool	fromRemote,
		const PString &	reason
	)

virtual

Call back for a media stream that failed to open.

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

Parameters

fromRemote	Flag indicating the attempt to open was from remote
reason	Reason for the open fail

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.

Reimplemented in OpalPCSSConnection.

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 true is returned then the connection continues. If false 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 OpalEndPoint 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

Reimplemented in OpalLocalConnection.

virtual bool OpalConnection::OnMediaCommand	(	OpalMediaStream &	stream,
		const OpalMediaCommand &	command
	)

virtual

Callback for media commands. Executes OnMediaCommand ont he other connection in call.

Returns: true if command is handled.

Parameters

stream	Stream command executed on
command	Media command being executed

Reimplemented in H323Connection, SIPConnection, and OpalRTPConnection.

virtual bool OpalConnection::OnMediaFailed	(	unsigned	sessionId,
		bool	source
	)

virtual

Call back when media stops unexpectedly. This allows the application to take some action when a "no media" condition is detected. For example clear the call.

The source indicates if the media is in a source OpalMediaStream of the conenction, for example on RTP connections (SIP/H.323) true indicates incoming media, fals indicates transmitted media.

The SetNoMediaTimeout() can be used to set the default time for a source stream (e.g. received RTP) to call this function.

Default behaviour releases the connection.

true if the specific media session is to be aborted.

Parameters

sessionId	Session ID of media that stopped.
source	Indicates the direction of stream.

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 SIPConnection, and OpalRTPConnection.

virtual void OpalConnection::OnPauseMediaStream	(	OpalMediaStream &	strm,
		bool	paused
	)

virtual

Pause media streams for connection.

Parameters

strm	Media stream paused/un-paused
paused	Flag for pausing/un-pausing

Reimplemented in SIPConnection.

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 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 OpalMixerConnection, OpalPCSSConnection, SIPConnection, OpalLineConnection, OpalIMConnection, H323Connection, IAX2Connection, and OpalRTPConnection.

virtual void OpalConnection::OnRxIntraFrameRequest	(	const OpalMediaSession &	session,
		bool	force
	)

virtual

Callback from the RTP session after an IntraFrameRequest is receieved. The default behaviour executes an OpalVideoUpdatePicture command on the connection's source video stream if it exists.

Parameters

session	Session with statistics
force	Force Intra frame, or just indicate picture loss

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

Reimplemented in OpalIMConnection.

virtual void OpalConnection::OnStartMediaPatch ( OpalMediaPatch & patch )

virtual

Call back when media stream patch thread starts.

Default behaviour calls OpalManager function of same name.

Parameters

patch Patch being started

Reimplemented in OpalMixerConnection, and OpalPCSSConnection.

void OpalConnection::OnStartRecording ( OpalMediaPatch * patch )

protected

virtual void OpalConnection::OnStopMediaPatch ( OpalMediaPatch & patch )

virtual

Call back when media stream patch thread stops.

Default behaviour calls OpalManager function of same name.

Parameters

patch Patch being stopped

void OpalConnection::OnStopRecording ( OpalMediaPatch * patch )

protected

virtual bool OpalConnection::OnTransferNotify	(	const PStringToString &	info,
		const OpalConnection *	transferringConnection
	)

virtual

A call back function to monitor the progress of a transfer. When a transfer operation is initiated, the Transfer() function will generally return immediately and the transfer may take some time. This call back can give an indication to the application of the progress of the transfer. the transfer.

For example in SIP, the OpalCall::Transfer() function will have sent a REFER request to the remote party. The remote party sends us NOTIFY requests about the progress of the REFER request.

An application can now make a decision during the transfer operation to short circuit the sequence, or let it continue. It can also determine if the transfer did not go through, and it should "take back" the call. Note no action is required to "take back" the call other than indicate to the user that they are back on.

A return value of false will immediately disconnect the current call.

The exact format of the info parameter is dependent on the protocol being used. As a minimum, it will always have a values info["result"] and info["party"].

The info["party"] indicates the part the connection is playing in the transfer. This will be: "A" party being transferred "B" party initiating the transfer of "A" "C" party "A" is being transferred to

The info["result"] will be at least one of the following: "success" Transfer completed successfully (party A or B) "incoming" New call was from a transfer (party C) "started" Transfer operation has started (party A) "progress" Transfer is in progress (party B) "blind" Transfer is blind, no further notification (party B) "error" Transfer could not begin (party B) "failed" Transfer started but did not complete (party A or B)

For SIP, there may be an additional info["state"] containing the NOTIFY subscription state, an info["code"] entry containing the 3 digit code returned in the NOTIFY body and info["Referred-By"] indicating the URI of party B. Other fields may also be present.

The default behaviour calls the OpalEndPoint function of the same name. The default action of that function is to return false, thereby releasing the connection if the info["result"] == "success".

Parameters

info	State of the transfer
transferringConnection	Connection performing transfer, maybe "this"

Reimplemented in OpalIVRConnection.

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

void OpalConnection::OnUserInputStringCallback ( PString value )

inline

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 greater than zero then it indicates the end of the tone output and how long the tone had run.

Note, there is no guarantee a zero value (start tone) will occur. There is also no guarantee this function is called at all, given how the remote may send user indications. For simple, "event" based, user indications the OnUserInputString() should be used. THis function is only for when a more precise representation of the tone, and it's duration, is required.

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

Parameters

tone	Received tone
duration	Duration of tone in milliseconds

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 OpalLocalConnection, SIPConnection, and H323Connection.

OpalConnection::P_DECLARE_TRACED_ENUM	(	AnswerCallResponse	,
		AnswerCallNow	,
		AnswerCallDenied	,
		AnswerCallPending	,
		AnswerCallDeferred	,
		AnswerCallAlertWithMedia	,
		AnswerCallDeferredWithMedia	,
		AnswerCallProgress	,
		AnswerCallNowAndReleaseCurrent
	)

OpalConnection::P_DECLARE_TRACED_ENUM	(	Phases	,
		UninitialisedPhase	,
		SetUpPhase	,
		ProceedingPhase	,
		AlertingPhase	,
		ConnectedPhase	,
		EstablishedPhase	,
		ForwardingPhase	,
		ReleasingPhase	,
		ReleasedPhase
	)

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.

OpalConnection::P_DECLARE_TRACED_ENUM	(	SendUserInputModes	,
		SendUserInputAsQ931	,
		SendUserInputAsString	,
		SendUserInputAsTone	,
		SendUserInputAsRFC2833	,
		SendUserInputAsInlineRFC2833	= `SendUserInputAsRFC2833`,
		SendUserInputInBand	,
		SendUserInputAsProtocolDefault
	)

OpalConnection::P_DECLARE_TRACED_ENUM_EX	(	CallEndReasonCodes	,
		NumCallEndReasons	,
		EndedByLocalUser	,
		0	,
		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	,
		EndedByMediaFailed	,
		EndedByCallCompletedElsewhere	,
		EndedByCertificateAuthority	,
		EndedByIllegalAddress	,
		EndedByCustomCode
	)

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.

virtual void OpalConnection::PauseMediaStreams ( bool paused )

virtual

Pause media streams for connection.

Parameters

paused Flag for pausing/un-pausing

OpalConnection::PDECLARE_NOTIFIER	(	RTP_DataFrame	,
		OpalConnection	,
		OnRecordAudio
	)

protected

OpalConnection::PDECLARE_NOTIFIER	(	RTP_DataFrame	,
		OpalConnection	,
		OnRecordVideo
	)

protected

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

Referenced by SIPConnection::PrintOn().

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 = `"YX#\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`,
		bool	synchronous = `false`
	)

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
synchronous	If true spawns thread to release connection

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

Parameters

strm	media stream to remove

virtual bool OpalConnection::RequestPresentationRole ( bool release )

virtual

Send request for presentation token. This requests the "presentation token" in H.239 terminology. It gives permission to start secondary video channels with "presentation" role. This is done via OpalCall::OpenSourceMediaStreams().

If called, and returns true, the OnChangedPresentationRole() should be monitored for being this connections GetLocalPartyURL() value, indicating success. Any other value indicates failure.

Default behaviour is to return false which indicates this connection is not part of a conference.

Parameters

release Indicate we are acquiring or releasing the token

Reimplemented in H323Connection.

virtual bool OpalConnection::RequireSymmetricMediaStreams ( ) const

virtual

Indicate connection requires symmetric media. Default behaviour returns false.

Reimplemented in 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, OpalMixerConnection, OpalLocalConnection, SIPConnection, OpalLineConnection, OpalIVRConnection, and IAX2Connection.

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

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.

A duration of zero indicates that a default duration (90ms) is to be used.

The default behaviour sends the tone using RFC2833.

Parameters

tone	DTMF tone code
duration	Duration of tone in milliseconds

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

virtual bool OpalConnection::SendVideoUpdatePicture	(	unsigned	sessionID = `0`,
		bool	force = `false`
	)		const

virtual

Send a Video Update Picture request to media stream. If force is set then a "force Intra frame" is sent, otherwise a "picture loss" is sent. The underlying protocol may or may not make a distinction.

Parameters

sessionID	Session for media stream, 0 is use first Video stream
force	Indicate is a picture loss or forced I-Frame

void OpalConnection::SendVideoUpdatePictureCallback	(	unsigned	sessionID,
		bool	force
	)

inline

virtual PBoolean OpalConnection::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 remoteendpoint is "ringing".

The default behaviour simply returns true.

Parameters

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

Reimplemented in OpalLocalConnection, OpalPCSSConnection, OpalLineConnection, SIPConnection, IAX2Connection, and H323Connection.

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 SIPConnection, and H323Connection.

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 bool OpalConnection::SetAudioMute	(	bool	source,
		bool	mute
	)

virtual

Set the mute state for the audio media channel.

Parameters

source	true for source (microphone), false for sink (speaker)
mute	Flag for muted audio

Reimplemented in OpalPCSSConnection.

virtual PBoolean OpalConnection::SetAudioVolume	(	PBoolean	source,
		unsigned	percentage
	)

virtual

Set the volume (gain) for the audio media channel. The volume range is 0 == muted, 100 == LOUDEST.

Parameters

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

Reimplemented in OpalPCSSConnection, and OpalLineConnection.

virtual bool OpalConnection::SetBandwidthAllocated	(	OpalBandwidth::Direction	dir,
		OpalBandwidth	newBandwidth
	)

virtual

Set the total rx and/or tx bandwidth in bits/sec.

Returns: false if more bandwidth is currently in use than the requested total.

Parameters

dir	Bandwidth direction
newBandwidth	New bandwidth limit

virtual bool OpalConnection::SetBandwidthAvailable	(	OpalBandwidth::Direction	dir,
		OpalBandwidth	availableBandwidth
	)

virtual

Set the available rx and/or tx bandwidth in bits/sec.

Parameters

dir	Bandwidth direction
availableBandwidth	New bandwidth limit

virtual bool OpalConnection::SetBandwidthUsed	(	OpalBandwidth::Direction	dir,
		OpalBandwidth	releasedBandwidth,
		OpalBandwidth	requiredBandwidth
	)

virtual

Set the used rx and/or tx bandwidth in bits/sec. This is an internal function used by the OpalMediaStream bandwidth management code.

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

Parameters

dir	Bandwidth direction
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 OpalLocalConnection, OpalLineConnection, SIPConnection, H323Connection, and IAX2Connection.

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::SetRedirectingParty ( const PString & party )

inline

Set the redirecting party. This is the party that caused an incoming call to arrive at this endpoint.

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 ( )

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 calls OnIncomingConnection() and OpalCall::OnSetUp() if it is first conenction in the call.

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

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::TransferConnection ( const PString & remoteParty )

virtual

Initiate the transfer of an existing call (connection) to a new remote party.

If remoteParty is a valid call token, then the remote party is transferred to that party (consultation transfer) and both calls are cleared.

Parameters

remoteParty Remote party to transfer the existing call to

Reimplemented in H323Connection, OpalPCSSConnection, SIPConnection, OpalIVRConnection, and IAX2Connection.

Field Documentation

CallEndReason OpalConnection::callEndReason

protected

PString OpalConnection::callToken

protected

Referenced by GetCall().

PString OpalConnection::displayName

protected

Referenced by GetDisplayName().

OpalEndPoint& OpalConnection::endpoint

protected

PString OpalConnection::localPartyName

protected

OpalMediaType::AutoStartMap OpalConnection::m_autoStartInfo

protected

PString OpalConnection::m_calledPartyName

protected

PString OpalConnection::m_calledPartyNumber

protected

OpalMediaFormat OpalConnection::m_filterMediaFormat

protected

OpalMediaFormatList OpalConnection::m_localMediaFormats

protected

unsigned OpalConnection::m_maxAudioJitterDelay

protected

std::set<unsigned> OpalConnection::m_mediaSessionFailed

protected

unsigned OpalConnection::m_minAudioJitterDelay

protected

PBoolean OpalConnection::m_originating

protected

Referenced by GetToken().

ZeroTime OpalConnection::m_phaseTime[NumPhases]

protected

Referenced by GetConnectionStartTime(), GetPhaseTime(), GetSetupUpTime(), and IsOriginating().

PNotifier OpalConnection::m_recordAudioNotifier

protected

PString OpalConnection::m_recordingFilename

protected

PNotifier OpalConnection::m_recordVideoNotifier

protected

PString OpalConnection::m_redirectingParty

protected

PString OpalConnection::m_remotePartyURL

protected

OpalBandwidth OpalConnection::m_rxBandwidthAvailable

protected

StringOptions OpalConnection::m_stringOptions

protected

OpalBandwidth OpalConnection::m_txBandwidthAvailable

protected

unsigned OpalConnection::m_VideoUpdateRequestsReceived

protected

Referenced by GetVideoUpdateRequestsSent().

unsigned OpalConnection::m_VideoUpdateRequestsSent

protected

PSafeList<OpalMediaStream> OpalConnection::mediaStreams

protected

OpalCall& OpalConnection::ownerCall

protected

Referenced by GetEndPoint().

OpalProductInfo OpalConnection::productInfo

protected

Referenced by GetConnectionEndTime(), and GetProductInfo().

PString OpalConnection::remotePartyName

protected

Referenced by GetRemotePartyName().

PString OpalConnection::remotePartyNumber

protected

OpalProductInfo OpalConnection::remoteProductInfo

protected

Referenced by GetRemoteApplication(), and GetRemotePartyAddress().

SendUserInputModes OpalConnection::sendUserInputMode

protected

OpalSilenceDetector* OpalConnection::silenceDetector

protected

PSyncPoint OpalConnection::userInputAvailable

protected

PString OpalConnection::userInputString

protected

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

connection.h

Data Structures

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Basic operations

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation