OpalConnection Class Reference

#include <connection.h>

Inheritance diagram for OpalConnection:
IAX2Connection OpalLineConnection OpalLocalConnection OpalRTPConnection OpalFaxConnection OpalIVRConnection OpalMixerConnection OpalPCSSConnection H323Connection SIPConnection

Data Structures

struct  AutoStartInfo
class  AutoStartMap
struct  CallEndReason
class  StringOptions
class  ZeroTime

Public Types

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 StringOptionsGetStringOptions () 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 OnApplyStringOptions ()
 Call back for connection to act on changed string options.
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 ()=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 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< OpalConnectionGetOtherPartyConnection () 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 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 (bool paused)
virtual void OnPauseMediaStream (OpalMediaStream &strm, bool paused)
virtual OpalMediaStreamCreateMediaStream (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)
virtual bool OnMediaCommand (OpalMediaStream &stream, const OpalMediaCommand &command)
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, bool force=false) 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=false)
virtual unsigned GetBandwidthUsed () const
virtual PBoolean SetBandwidthUsed (unsigned releasedBandwidth, unsigned requiredBandwidth)
Member variable access



OpalEndPointGetEndPoint () const
OpalCallGetCall () 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 OpalProductInfoGetProductInfo () 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 & GetRedirectingParty () const
void SetRedirectingParty (const PString &party)
const PString GetRemotePartyCallbackURL () const
PCaselessString GetRemoteApplication () const
const OpalProductInfoGetRemoteProductInfo () 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)
virtual PString GetCallInfo () const
unsigned GetMinAudioJitterDelay () const
unsigned GetMaxAudioJitterDelay () const
void SetAudioJitterDelay (unsigned minDelay, unsigned maxDelay)
OpalSilenceDetectorGetSilenceDetector () const
OpalEchoCancelerGetEchoCanceler () const
virtual PString GetIdentifier () const
virtual PINDEX GetMaxRtpPayloadSize () const
virtual OpalTransportGetTransport () const
 PDICTIONARY (MediaAddressesDict, POrdinalKey, OpalTransportAddress)
MediaAddressesDict & GetMediaTransportAddresses ()
unsigned GetVideoUpdateRequestsSent () const

Protected Types

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)
 PDECLARE_NOTIFIER (RTP_DataFrame, OpalConnection, OnDetectInBandDTMF)
 PDECLARE_NOTIFIER (RTP_DataFrame, OpalConnection, OnSendInBandDTMF)

Protected Attributes

OpalCallownerCall
OpalEndPointendpoint
PString callToken
PBoolean originating
OpalProductInfo productInfo
PString localPartyName
PString displayName
PString remotePartyName
PString remotePartyURL
OpalProductInfo remoteProductInfo
PString remotePartyNumber
PString remotePartyAddress
PString m_redirectingParty
CallEndReason callEndReason
PString m_calledPartyNumber
PString m_calledPartyName
SendUserInputModes sendUserInputMode
PString userInputString
PSyncPoint userInputAvailable
OpalSilenceDetectorsilenceDetector
OpalEchoCancelerechoCanceler
OpalMediaFormat m_filterMediaFormat
OpalMediaFormatList m_localMediaFormats
MediaAddressesDict mediaTransportAddresses
PSafeList< OpalMediaStreammediaStreams
unsigned minAudioJitterDelay
unsigned maxAudioJitterDelay
unsigned bandwidthAvailable
PDTMFDecoder m_dtmfDecoder
bool m_detectInBandDTMF
unsigned m_dtmfScaleMultiplier
unsigned m_dtmfScaleDivisor
PNotifier m_dtmfDetectNotifier
bool m_sendInBandDTMF
OpalMediaFormat m_dtmfSendFormat
PBYTEArray m_inBandDTMF
PINDEX m_emittedInBandDTMF
PMutex m_inBandMutex
PNotifier m_dtmfSendNotifier
StringOptions m_stringOptions
PString m_recordingFilename
PNotifier m_recordAudioNotifier
PNotifier m_recordVideoNotifier
unsigned m_VideoUpdateRequestsSent
AutoStartMap m_autoStartInfo
enum OpalConnection:: { ... }  m_faxMediaStreamsSwitchState
ZeroTime m_phaseTime [NumPhases]

Basic operations



enum  Phases {
  UninitialisedPhase, SetUpPhase, ProceedingPhase, AlertingPhase,
  ConnectedPhase, EstablishedPhase, ForwardingPhase, ReleasingPhase,
  ReleasedPhase, NumPhases
}
virtual bool IsNetworkConnection () const =0
__inline Phases GetPhase () const
__inline bool IsEstablished () const
 Return true if connection is in the established phase.
__inline bool IsReleased () const
 Return true if connection is in the established phase.
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 Hold (bool fromRemote, bool placeOnHold)
virtual bool IsOnHold (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, SendUserInputAsRFC2833,
  SendUserInputInBand, SendUserInputAsProtocolDefault, NumSendUserInputModes, SendUserInputAsInlineRFC2833 = SendUserInputAsRFC2833
}
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)

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

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()=false.

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.

Connection options

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

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 

Has just sent/received the initial SETUP/INVITE packet.

ProceedingPhase 

The receipt of SETUP/INVITE has been acknowledged.

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 established, 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.

Enumerator:
SendUserInputAsQ931 
SendUserInputAsString 
SendUserInputAsTone 
SendUserInputAsRFC2833 
SendUserInputInBand 
SendUserInputAsProtocolDefault 
NumSendUserInputModes 
SendUserInputAsInlineRFC2833 

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
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::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:
sync Synchronisation object to signal
reason Reason for call clearing
virtual bool OpalConnection::CloseMediaStream ( OpalMediaStream stream  )  [virtual]

Close of a specific media stream.

Parameters:
stream Stream to close

Reimplemented in H323Connection, and SIPConnection.

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

Close of a media stream by session.

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

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.

const PTime& OpalConnection::GetAlertingTime (  )  const [inline]

Get the time at which the ALERTING/18x was received

References AlertingPhase, and m_phaseTime.

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, and 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
unsigned OpalConnection::GetBandwidthAvailable (  )  const [inline]

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

References bandwidthAvailable.

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.

References ownerCall.

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.

References m_calledPartyName.

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.

References m_calledPartyNumber.

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.

References callEndReason.

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

Get the reason for this connection shutting down as text.

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.

const PTime& OpalConnection::GetConnectionEndTime (  )  const [inline]

Get the time at which the connection was cleared

References m_phaseTime, and ReleasingPhase.

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

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

Get the local display name.

References displayName.

OpalEchoCanceler* OpalConnection::GetEchoCanceler (  )  const [inline]

Get the echo canceler active on connection.

References echoCanceler.

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

Get the owner endpoint for this connection.

Reimplemented in H323Connection, and SIPConnection.

References endpoint.

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.

References localPartyName.

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.

References maxAudioJitterDelay.

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

References minAudioJitterDelay.

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.

Referenced by GetOtherPartyConnectionAs().

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

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

References GetOtherPartyConnection().

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

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.

References callEndReason, and OpalConnection::CallEndReason::q931.

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

References GetSendUserInputMode().

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

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

References m_redirectingParty.

PCaselessString OpalConnection::GetRemoteApplication (  )  const [inline]

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

References OpalProductInfo::AsString(), and remoteProductInfo.

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.

References remotePartyAddress.

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

References GetRemotePartyURL().

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.

References remotePartyNumber.

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.

Referenced by GetRemotePartyCallbackURL().

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

Get the remote product info.

References remoteProductInfo.

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

Get the user input indication transmission mode.

References sendUserInputMode.

Referenced by GetRealSendUserInputMode().

const PTime& OpalConnection::GetSetupUpTime (  )  const [inline]

Get the time at which the connection was begun

References m_phaseTime, and SetUpPhase.

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

Get the silence detector active on connection.

References silenceDetector.

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

Get the string options associated with this connection.

References m_stringOptions.

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

Get the token for this connection.

References callToken.

Referenced by H323Connection::GetCallToken().

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.

References m_VideoUpdateRequestsSent.

virtual bool OpalConnection::Hold ( bool  fromRemote,
bool  placeOnHold 
) [virtual]

Put the current connection on hold, suspending all media streams. 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 teh command/request is for going on hold or retrieving from hold.

Parameters:
fromRemote Flag for if remote has us on hold, or we have them
placeOnHold Flag for setting on or off hold

Reimplemented in H323Connection, IAX2Connection, and SIPConnection.

__inline bool OpalConnection::IsEstablished (  )  const [inline]

Return true if connection is in the established phase.

References EstablishedPhase.

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

See if the media can bypass the local host.

The default behaviour returns false 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, and SIPConnection.

virtual bool OpalConnection::IsOnHold ( bool  fromRemote  )  [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 originating.

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.

References ReleasingPhase.

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

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

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 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 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 bool OpalConnection::OnMediaCommand ( OpalMediaStream stream,
const OpalMediaCommand command 
) [virtual]

Callback for media commands. Calls the SendIntraFrameRequest on the rtp session

Returns:
true if command is handled.
Parameters:
stream Stream command executed on
command Media command being executed

Reimplemented in H323Connection, OpalRTPConnection, and SIPConnection.

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::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 H323Connection, IAX2Connection, OpalLineConnection, OpalMixerConnection, OpalRTPConnection, 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 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 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"
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 ( bool  paused  )  [virtual]

Pause media streams for connection.

Parameters:
paused Flag for pausing/un-pausing
OpalConnection::PDECLARE_NOTIFIER ( RTP_DataFrame  ,
OpalConnection  ,
OnSendInBandDTMF   
) [protected]
OpalConnection::PDECLARE_NOTIFIER ( RTP_DataFrame  ,
OpalConnection  ,
OnDetectInBandDTMF   
) [protected]
OpalConnection::PDECLARE_NOTIFIER ( RTP_DataFrame  ,
OpalConnection  ,
OnRecordVideo   
) [protected]
OpalConnection::PDECLARE_NOTIFIER ( RTP_DataFrame  ,
OpalConnection  ,
OnRecordAudio   
) [protected]
OpalConnection::PDECLARE_NOTIFIER ( PThread  ,
OpalConnection  ,
OnReleaseThreadMain   
) [protected]
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,
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
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

References SendUserInputTone().

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

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

Referenced by SendUserInputHookFlash().

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

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

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

Set the available bandwidth in 100's of bits/sec. Note if the force parameter is true 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, 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:
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, and SIPConnection.

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

Set the local display name.

References displayName.

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.

References productInfo.

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.

References callEndReason, and OpalConnection::CallEndReason::q931.

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.

References m_redirectingParty.

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

Set the remote party address.

References remotePartyAddress.

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

Set the remote party display name.

References remotePartyName.

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

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:
enableFax Enable FAX or return to audio mode

Reimplemented in H323Connection, and OpalFaxConnection.

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


Field Documentation

unsigned OpalConnection::bandwidthAvailable [protected]

Referenced by GetBandwidthAvailable().

PString OpalConnection::callToken [protected]

Referenced by GetToken().

PString OpalConnection::displayName [protected]

Referenced by GetDisplayName(), and SetDisplayName().

Referenced by GetEchoCanceler().

PString OpalConnection::localPartyName [protected]

Referenced by GetLocalPartyName().

PString OpalConnection::m_calledPartyName [protected]

Referenced by GetCalledPartyName().

Referenced by GetCalledPartyNumber().

PDTMFDecoder OpalConnection::m_dtmfDecoder [protected]
PNotifier OpalConnection::m_dtmfDetectNotifier [protected]
unsigned OpalConnection::m_dtmfScaleDivisor [protected]
PNotifier OpalConnection::m_dtmfSendNotifier [protected]
PBYTEArray OpalConnection::m_inBandDTMF [protected]
PMutex OpalConnection::m_inBandMutex [protected]
ZeroTime OpalConnection::m_phaseTime[NumPhases] [protected]

Referenced by GetStringOptions().

Referenced by GetMaxAudioJitterDelay().

MediaAddressesDict OpalConnection::mediaTransportAddresses [protected]

Referenced by GetMinAudioJitterDelay().

PBoolean OpalConnection::originating [protected]

Referenced by GetCall().

Referenced by GetProductInfo(), and SetProductInfo().

PString OpalConnection::remotePartyName [protected]
PString OpalConnection::remotePartyNumber [protected]

Referenced by GetRemotePartyNumber().

PString OpalConnection::remotePartyURL [protected]

Referenced by GetSendUserInputMode().

Referenced by GetSilenceDetector().

PSyncPoint OpalConnection::userInputAvailable [protected]
PString OpalConnection::userInputString [protected]

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

Generated on 5 Jun 2012 for OPAL by  doxygen 1.6.1