OpalManager Class Reference

#include <manager.h>

List of all members.

Classes

class  CallDict
class  InterfaceMonitor
struct  PortInfo
class  RouteEntry

Public Member Functions

void GarbageCollection ()
virtual void OnNewConnection (OpalConnection &connection)
OpalRecordManagerGetRecordManager () const
virtual PBoolean StartRecording (const PString &callToken, const PFilePath &filename, bool mono=false)
virtual bool IsRecording (const PString &callToken)
virtual bool StopRecording (const PString &callToken)
virtual void AddIMMediaFormats (OpalMediaFormatList &mediaFormats, const OpalConnection *connection=NULL) const
virtual void OnApplyStringOptions (OpalConnection &conn, OpalConnection::StringOptions &stringOptions)
Construction
 OpalManager ()
 ~OpalManager ()
Endpoint management
void AttachEndPoint (OpalEndPoint *endpoint, const PString &prefix=PString::Empty())
void DetachEndPoint (const PString &prefix)
void DetachEndPoint (OpalEndPoint *endpoint)
OpalEndPointFindEndPoint (const PString &prefix)
PList< OpalEndPointGetEndPoints () const
void ShutDownEndpoints ()
Call management
virtual PBoolean SetUpCall (const PString &partyA, const PString &partyB, PString &token, void *userData=NULL, unsigned options=0, OpalConnection::StringOptions *stringOptions=NULL)
virtual void OnEstablishedCall (OpalCall &call)
virtual PBoolean HasCall (const PString &token)
PINDEX GetCallCount () const
virtual PBoolean IsCallEstablished (const PString &token)
PSafePtr< OpalCallFindCallWithLock (const PString &token, PSafetyMode mode=PSafeReadWrite)
virtual PBoolean ClearCall (const PString &token, OpalConnection::CallEndReason reason=OpalConnection::EndedByLocalUser, PSyncPoint *sync=NULL)
virtual PBoolean ClearCallSynchronous (const PString &token, OpalConnection::CallEndReason reason=OpalConnection::EndedByLocalUser)
virtual void ClearAllCalls (OpalConnection::CallEndReason reason=OpalConnection::EndedByLocalUser, PBoolean wait=PTrue)
virtual void OnClearedCall (OpalCall &call)
virtual OpalCallCreateCall (void *userData)
virtual OpalCallCreateCall ()
OpalCallInternalCreateCall ()
virtual void DestroyCall (OpalCall *call)
PString GetNextCallToken ()
Connection management
virtual PBoolean MakeConnection (OpalCall &call, const PString &party, void *userData=NULL, unsigned int options=0, OpalConnection::StringOptions *stringOptions=NULL)
virtual PBoolean OnIncomingConnection (OpalConnection &connection, unsigned options, OpalConnection::StringOptions *stringOptions)
virtual PBoolean OnIncomingConnection (OpalConnection &connection, unsigned options)
virtual PBoolean OnIncomingConnection (OpalConnection &connection)
virtual bool OnRouteConnection (PStringSet &routesTried, const PString &a_party, const PString &b_party, OpalCall &call, unsigned options, OpalConnection::StringOptions *stringOptions)
virtual void OnProceeding (OpalConnection &connection)
virtual void OnAlerting (OpalConnection &connection)
virtual
OpalConnection::AnswerCallResponse 
OnAnswerCall (OpalConnection &connection, const PString &caller)
virtual void OnConnected (OpalConnection &connection)
virtual void OnEstablished (OpalConnection &connection)
virtual void OnReleased (OpalConnection &connection)
virtual void OnHold (OpalConnection &connection, bool fromRemote, bool onHold)
virtual void OnHold (OpalConnection &connection)
virtual PBoolean OnForwarded (OpalConnection &connection, const PString &remoteParty)
Media Streams management
virtual void AdjustMediaFormats (const OpalConnection &connection, OpalMediaFormatList &mediaFormats) const
virtual PBoolean IsMediaBypassPossible (const OpalConnection &source, const OpalConnection &destination, unsigned sessionID) const
virtual PBoolean OnOpenMediaStream (OpalConnection &connection, OpalMediaStream &stream)
virtual void OnRTPStatistics (const OpalConnection &connection, const RTP_Session &session)
virtual void OnClosedMediaStream (const OpalMediaStream &stream)
virtual OpalMediaPatchCreateMediaPatch (OpalMediaStream &source, PBoolean requiresPatchThread=PTrue)
virtual void DestroyMediaPatch (OpalMediaPatch *patch)
virtual PBoolean OnStartMediaPatch (const OpalMediaPatch &patch)
User indications
virtual void OnUserInputString (OpalConnection &connection, const PString &value)
virtual void OnUserInputTone (OpalConnection &connection, char tone, int duration)
virtual PString ReadUserInput (OpalConnection &connection, const char *terminators="#\r\n", unsigned lastDigitTimeout=4, unsigned firstDigitTimeout=30)
Member variable access
const OpalProductInfoGetProductInfo () const
void SetProductInfo (const OpalProductInfo &info, bool updateAll=true)
const PString & GetDefaultUserName () const
void SetDefaultUserName (const PString &name, bool updateAll=true)
const PString & GetDefaultDisplayName () const
void SetDefaultDisplayName (const PString &name, bool updateAll=true)
virtual PBoolean IsLocalAddress (const PIPSocket::Address &remoteAddress) const
virtual PBoolean IsRTPNATEnabled (OpalConnection &connection, const PIPSocket::Address &localAddr, const PIPSocket::Address &peerAddr, const PIPSocket::Address &signalAddr, PBoolean incoming)
virtual PBoolean TranslateIPAddress (PIPSocket::Address &localAddress, const PIPSocket::Address &remoteAddress)
const PString & GetTranslationHost () const
bool SetTranslationHost (const PString &host)
const PIPSocket::Address & GetTranslationAddress () const
void SetTranslationAddress (const PIPSocket::Address &address)
virtual PNatMethod * GetNatMethod (const PIPSocket::Address &remoteAddress=PIPSocket::GetDefaultIpAny()) const
PSTUNClient::NatTypes SetSTUNServer (const PString &server)
const PString & GetSTUNServer () const
PSTUNClient * GetSTUNClient () const
WORD GetTCPPortBase () const
WORD GetTCPPortMax () const
void SetTCPPorts (unsigned tcpBase, unsigned tcpMax)
WORD GetNextTCPPort ()
WORD GetUDPPortBase () const
WORD GetUDPPortMax () const
void SetUDPPorts (unsigned udpBase, unsigned udpMax)
WORD GetNextUDPPort ()
WORD GetRtpIpPortBase () const
WORD GetRtpIpPortMax () const
void SetRtpIpPorts (unsigned udpBase, unsigned udpMax)
WORD GetRtpIpPortPair ()
BYTE GetRtpIpTypeofService () const
void SetRtpIpTypeofService (unsigned tos)
PINDEX GetMaxRtpPayloadSize () const
void SetMaxRtpPayloadSize (PINDEX size, bool mtu=false)
unsigned GetMinAudioJitterDelay () const
unsigned GetMaxAudioJitterDelay () const
void SetAudioJitterDelay (unsigned minDelay, unsigned maxDelay)
const PStringArray & GetMediaFormatOrder () const
void SetMediaFormatOrder (const PStringArray &order)
const PStringArray & GetMediaFormatMask () const
void SetMediaFormatMask (const PStringArray &mask)
virtual void SetSilenceDetectParams (const OpalSilenceDetector::Params &params)
const OpalSilenceDetector::ParamsGetSilenceDetectParams () const
virtual void SetEchoCancelParams (const OpalEchoCanceler::Params &params)
const OpalEchoCanceler::ParamsGetEchoCancelParams () const
PBoolean DetectInBandDTMFDisabled () const
void DisableDetectInBandDTMF (PBoolean mode)
const PTimeInterval & GetNoMediaTimeout () const
PBoolean SetNoMediaTimeout (const PTimeInterval &newInterval)
const PString & GetDefaultILSServer () const
void SetDefaultILSServer (const PString &server)

Protected Member Functions

void InternalClearAllCalls (OpalConnection::CallEndReason reason, bool wait, bool first)
 PDECLARE_NOTIFIER (PThread, OpalManager, GarbageMain)
friend OpalCall::OpalCall (OpalManager &mgr)

Protected Attributes

OpalProductInfo productInfo
PString defaultUserName
PString defaultDisplayName
BYTE rtpIpTypeofService
PINDEX rtpPayloadSizeMax
unsigned minAudioJitterDelay
unsigned maxAudioJitterDelay
PStringArray mediaFormatOrder
PStringArray mediaFormatMask
PBoolean disableDetectInBandDTMF
PTimeInterval noMediaTimeout
PString ilsServer
OpalSilenceDetector::Params silenceDetectParams
OpalEchoCanceler::Params echoCancelParams
struct OpalManager::PortInfo tcpPorts
struct OpalManager::PortInfo udpPorts
struct OpalManager::PortInfo rtpIpPorts
PString translationHost
PIPSocket::Address translationAddress
PString stunServer
PSTUNClient * stun
InterfaceMonitorinterfaceMonitor
RouteTable routeTable
PMutex routeTableMutex
PReadWriteMutex endpointsMutex
PList< OpalEndPointendpointList
std::map< PString, OpalEndPoint * > endpointMap
PAtomicInteger lastCallTokenID
OpalManager::CallDict activeCalls
PAtomicInteger m_clearingAllCallsCount
PMutex m_clearingAllCallsMutex
PSyncPoint m_allCallsCleared
PThread * garbageCollector
PSyncPoint garbageCollectExit
OpalRecordManagerm_recordManager

Friends

void OpalCall::OnReleased (OpalConnection &connection)

Other services

enum  MessageWaitingType {
  NoMessageWaiting, VoiceMessageWaiting, FaxMessageWaiting, PagerMessageWaiting,
  MultimediaMessageWaiting, TextMessageWaiting, NumMessageWaitingTypes
}
virtual void OnMWIReceived (const PString &party, MessageWaitingType type, const PString &extraInfo)
 PARRAY (RouteTable, RouteEntry)
virtual PBoolean AddRouteEntry (const PString &spec)
PBoolean SetRouteTable (const PStringArray &specs)
void SetRouteTable (const RouteTable &table)
const RouteTable & GetRouteTable () const
virtual PString ApplyRouteTable (const PString &source, const PString &destination, PINDEX &entry)


Detailed Description

This class is the central manager for OPAL. The OpalManager embodies the root of the tree of objects that constitute an OPAL system. It contains all of the endpoints that make up the system. Other entities such as media streams etc are in turn contained in these objects. It is expected that an application would only ever have one instance of this class, and also descend from it to override call back functions.

The manager is the eventual destination for call back indications from various other objects. It is possible, for instance, to get an indication of a completed call by creating a descendant of the OpalCall and overriding the OnClearedCall() virtual. However, this could quite unwieldy for all of the possible classes, so the default behaviour is to call the equivalent function on the OpalManager. This allows most applications to only have to create a descendant of the OpalManager and override virtual functions there to get all the indications it needs.


Member Enumeration Documentation

Enumerator:
NoMessageWaiting 
VoiceMessageWaiting 
FaxMessageWaiting 
PagerMessageWaiting 
MultimediaMessageWaiting 
TextMessageWaiting 
NumMessageWaitingTypes 


Constructor & Destructor Documentation

OpalManager::OpalManager (  ) 

Create a new manager.

OpalManager::~OpalManager (  ) 

Destroy the manager. This will clear all calls, then delete all endpoints still attached to the manager.


Member Function Documentation

virtual void OpalManager::AddIMMediaFormats ( OpalMediaFormatList mediaFormats,
const OpalConnection connection = NULL 
) const [virtual]

Parameters:
mediaFormats Media formats to use
connection Optional connection that is using formats

virtual PBoolean OpalManager::AddRouteEntry ( const PString &  spec  )  [virtual]

Add a route entry to the route table.

The specification string is of the form:

pattern '=' destination where:

pattern regular expression used to select route

destination destination for the call

The "pattern" string regex is compared against routing strings that are built as follows:

a_party '' b_party

where:

a_party name associated with a local connection i.e. "pots:vpb:1/2" or "h323:myname@myhost.com".

b_party destination specified by the call, which may be a full URI or a simple digit string

Note that all "pattern" strings have an implied '^' at the beginning and a '$' at the end. This forces the "pattern" to match the entire source string. For convenience, the sub-expression ".*\t" is inserted immediately after any ':' character if no '' is present.

Route entries are stored and searched in the route table in the order they are added.

The "destination" string is determines the endpoint used for the outbound leg of the route, when a match to the "pattern" is found. It can be a literal string, or can be constructed using various meta-strings that correspond to parts of the source. See below for a list of the available meta-strings

A "destination" starting with the string 'label:' causes the router to restart searching from the beginning of the route table using the new string as the "a_party". Thus, a route table with the folllwing entries:

"label:speeddial=h323:10.0.1.1" "pots:26=label:speeddial"

will produce the same result as the single entry "pots:26=h323:10.0.1.1".

If the "destination" parameter is of the form , then the file is read with each line consisting of a pattern=destination route specification.

"destination" strings without an equal sign or beginning with '#' are ignored.

Pattern Regex Examples: -----------------------

1) A local H.323 endpoint with with name of "myname@myhost.com" that receives a call with a destination h323Id of "boris" would generate:

"h323:myname@myhost.com\tboris"

2) A local SIP endpoint with with name of "fred@nurk.com" that receives a call with a destination of "sip:fred@nurk.com" would generate:

"sip:fred@nurk.com\tsip:fred@nurk.com"

3) Using line 0 of a PhoneJACK handset with a serial # of 01AB3F4 to dial the digits 2, 6 and # would generate:

"pots:Quicknet:01AB3F4:0\t26"

Destination meta-strings: -------------------------

The available meta-strings are:

<da> Replaced by the "b_party" string. For example "pc:.*\t.* = sip:<da>" directs calls to the SIP protocol. In this case there is a special condition where if the original destination had a valid protocol, eg h323:fred.com, then the entire string is replaced not just the <da> part.

<db> Same as <da>, but without the special condtion.

<du> Copy the "user" part of the "b_party" string. This is essentially the component after the : and before the '@', or the whole "b_party" string if these are not present.

<!du> The rest of the "b_party" string after the <du> section. The protocol is still omitted. This is usually the '@' and onward. Note if there is already an '@' in the destination before the <!du> and what is abour to replace it also has an '@' then everything between the @ and the <!du> (inclusive) is deleted, then the substitution is made so a legal URL can result.

<dn> Copy all valid consecutive E.164 digits from the "b_party" so pots:0061298765:1/2 becomes sip:0061298765@carrier.com

<dnX> As above but skip X digits, eg <dn2> skips 2 digits, so pots:00612198765 becomes sip:61298765@carrier.com

<!dn> The rest of the "b_party" after the <dn> or <dnX> sections.

<dn2ip> Translate digits separated by '*' characters to an IP address. e.g. 10*0*1*1 becomes 10.0.1.1, also 1234*10*0*1*1 becomes 1234.0.1.1 and 1234*10*0*1*1*1722 becomes 1234.0.1.1:1722.

Returns true if an entry was added.

Parameters:
spec Specification string to add

virtual void OpalManager::AdjustMediaFormats ( const OpalConnection connection,
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.

The default behaviour uses the mediaFormatOrder and mediaFormatMask member variables to adjust the mediaFormats list.

Parameters:
connection Connection that is about to use formats
mediaFormats Media formats to use

virtual PString OpalManager::ApplyRouteTable ( const PString &  source,
const PString &  destination,
PINDEX &  entry 
) [virtual]

Route the source address to a destination using the route table. The source parameter may be something like pots:vpb:1/2 or sip:fred@nurk.com.

The destination parameter is a partial URL, it does not include the protocol, but may be of the form user, or simply digits.

Parameters:
destination Source address, including endpoint protocol
entry Destination address read from source protocol

void OpalManager::AttachEndPoint ( OpalEndPoint endpoint,
const PString &  prefix = PString::Empty() 
)

Attach a new endpoint to the manager. This is an internal function called by the OpalEndPoint constructor.

Note that usually the endpoint is automatically "owned" by the manager. They should not be deleted directly. The DetachEndPoint() command should be used to do this.

Parameters:
endpoint EndPoint to add to the manager
prefix Prefix to use, if empty uses endpoint->GetPrefixName()

virtual void OpalManager::ClearAllCalls ( OpalConnection::CallEndReason  reason = OpalConnection::EndedByLocalUser,
PBoolean  wait = PTrue 
) [virtual]

Clear all current calls. This effectively executes OpalCall::Clear() on every call that the manager has active. This function can not be called from several threads at the same time.

Parameters:
reason Reason for call clearing
wait Flag to wait for calls to e cleared.

virtual PBoolean OpalManager::ClearCall ( const PString &  token,
OpalConnection::CallEndReason  reason = OpalConnection::EndedByLocalUser,
PSyncPoint *  sync = NULL 
) [virtual]

Clear a call. This finds the call by using the token then calls the OpalCall::Clear() function on it. All connections are released, and the connections and call are disposed of. Note that this function returns quickly and the disposal happens at some later time in a background thread. It is safe to call this function from anywhere.

Parameters:
token Token for identifying connection
reason Reason for call clearing
sync Sync point to wait on.

virtual PBoolean OpalManager::ClearCallSynchronous ( const PString &  token,
OpalConnection::CallEndReason  reason = OpalConnection::EndedByLocalUser 
) [virtual]

Clear a call. This finds the call by using the token then calls the OpalCall::Clear() function on it. All connections are released, and the connections and caller disposed of. Note that this function waits until the call has been cleared and all responses timeouts etc completed. Care must be used as to when it is called as deadlocks may result.

Parameters:
token Token for identifying connection
reason Reason for call clearing

virtual OpalCall* OpalManager::CreateCall (  )  [virtual]

virtual OpalCall* OpalManager::CreateCall ( void *  userData  )  [virtual]

Create a call object. This function allows an application to have the system create desccendants of the OpalCall class instead of instances of that class directly. The application can thus override call backs or add extra information that it wishes to maintain on a call by call basis.

The default behavious returns an instance of OpalCall.

Parameters:
userData user data passed to SetUpCall

virtual OpalMediaPatch* OpalManager::CreateMediaPatch ( OpalMediaStream source,
PBoolean  requiresPatchThread = PTrue 
) [virtual]

Create a OpalMediaPatch instance. This function allows an application to have the system create descendant class versions of the OpalMediPatch class. The application could use this to modify the default behaviour of a patch.

The default behaviour returns an instance of OpalMediaPatch.

Parameters:
source Source media stream

virtual void OpalManager::DestroyCall ( OpalCall call  )  [virtual]

Destroy a call object. This gets called from background thread that garbage collects all calls and connections. If an application has object lifetime issues with the threading, it can override this function and take responsibility for deleting the object at some later time.

The default behaviour simply calls "delete call".

virtual void OpalManager::DestroyMediaPatch ( OpalMediaPatch patch  )  [virtual]

Destroy a OpalMediaPatch instance.

The default behaviour simply calls delete patch.

void OpalManager::DetachEndPoint ( OpalEndPoint endpoint  ) 

void OpalManager::DetachEndPoint ( const PString &  prefix  ) 

Remove an endpoint from the manager. This will delete the endpoint object.

PBoolean OpalManager::DetectInBandDTMFDisabled (  )  const [inline]

void OpalManager::DisableDetectInBandDTMF ( PBoolean  mode  )  [inline]

Set the default H.245 tunneling mode.

Parameters:
mode New default mode

References disableDetectInBandDTMF.

PSafePtr<OpalCall> OpalManager::FindCallWithLock ( const PString &  token,
PSafetyMode  mode = PSafeReadWrite 
) [inline]

Find a call with the specified token. This searches the manager database for the call that contains the token as provided by functions such as SetUpCall().

Note the caller of this function MUST call the OpalCall::Unlock() function if this function returns a non-NULL pointer. If it does not then a deadlock can occur.

Parameters:
token Token to identify connection

References activeCalls.

Referenced by OpalEndPoint::GetConnectionWithLockAs().

OpalEndPoint* OpalManager::FindEndPoint ( const PString &  prefix  ) 

Find an endpoint instance that is using the specified prefix.

void OpalManager::GarbageCollection (  ) 

PINDEX OpalManager::GetCallCount (  )  const [inline]

Return the number of active calls.

References activeCalls.

const PString& OpalManager::GetDefaultDisplayName (  )  const [inline]

Get the default display name for all endpoints.

References defaultDisplayName.

const PString& OpalManager::GetDefaultILSServer (  )  const [inline]

Get the default ILS server to use for user lookup.

References ilsServer.

const PString& OpalManager::GetDefaultUserName (  )  const [inline]

Get the default username for all endpoints.

References defaultUserName.

const OpalEchoCanceler::Params& OpalManager::GetEchoCancelParams (  )  const [inline]

Get the default parameters for the silence detector.

References echoCancelParams.

PList<OpalEndPoint> OpalManager::GetEndPoints (  )  const

Get the endpoints attached to this manager.

unsigned OpalManager::GetMaxAudioJitterDelay (  )  const [inline]

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

References maxAudioJitterDelay.

PINDEX OpalManager::GetMaxRtpPayloadSize (  )  const [inline]

Get the maximum RTP payload size. Defaults to maximum safe MTU size (576 bytes as per RFC879) minus the typical size of the IP, UDP an RTP headers.

References rtpPayloadSizeMax.

const PStringArray& OpalManager::GetMediaFormatMask (  )  const [inline]

Get the default media format mask.

References mediaFormatMask.

const PStringArray& OpalManager::GetMediaFormatOrder (  )  const [inline]

Get the default media format order.

References mediaFormatOrder.

unsigned OpalManager::GetMinAudioJitterDelay (  )  const [inline]

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

References minAudioJitterDelay.

virtual PNatMethod* OpalManager::GetNatMethod ( const PIPSocket::Address &  remoteAddress = PIPSocket::GetDefaultIpAny()  )  const [virtual]

Return the NAT method to use. Returns NULL if address is a local address as per IsLocalAddress(). Always returns the NAT method if address is zero. Note, the pointer is NOT to be deleted by the user.

PString OpalManager::GetNextCallToken (  ) 

Get next unique token ID for calls. This is an internal function called by the OpalCall constructor.

WORD OpalManager::GetNextTCPPort (  ) 

Get the next TCP port number for H.245 channels

WORD OpalManager::GetNextUDPPort (  ) 

Get the next UDP port number for RAS channels

const PTimeInterval& OpalManager::GetNoMediaTimeout (  )  const [inline]

Get the amount of time with no media that should cause a call to clear

References noMediaTimeout.

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

Get the product info for all endpoints.

References productInfo.

OpalRecordManager& OpalManager::GetRecordManager (  )  const [inline]

References m_recordManager.

const RouteTable& OpalManager::GetRouteTable (  )  const [inline]

Get the active route table for the manager.

References routeTable.

WORD OpalManager::GetRtpIpPortBase (  )  const [inline]

Get the UDP port number base for RTP channels.

References OpalManager::OpalManager::PortInfo::base, and rtpIpPorts.

WORD OpalManager::GetRtpIpPortMax (  )  const [inline]

Get the max UDP port number for RTP channels.

References OpalManager::OpalManager::PortInfo::max, and rtpIpPorts.

WORD OpalManager::GetRtpIpPortPair (  ) 

Get the UDP port number pair for RTP channels.

BYTE OpalManager::GetRtpIpTypeofService (  )  const [inline]

Get the IP Type Of Service byte for media (eg RTP) channels.

References rtpIpTypeofService.

const OpalSilenceDetector::Params& OpalManager::GetSilenceDetectParams (  )  const [inline]

Get the default parameters for the silence detector.

References silenceDetectParams.

PSTUNClient* OpalManager::GetSTUNClient (  )  const [inline]

Return the STUN client instance in use.

References stun.

const PString& OpalManager::GetSTUNServer (  )  const [inline]

Get the current host name and optional port for the STUN server.

References stunServer.

WORD OpalManager::GetTCPPortBase (  )  const [inline]

Get the TCP port number base for H.245 channels

References OpalManager::OpalManager::PortInfo::base, and tcpPorts.

WORD OpalManager::GetTCPPortMax (  )  const [inline]

Get the TCP port number base for H.245 channels.

References OpalManager::OpalManager::PortInfo::max, and tcpPorts.

const PIPSocket::Address& OpalManager::GetTranslationAddress (  )  const [inline]

Get the translation address to use for TranslateIPAddress().

References translationAddress.

const PString& OpalManager::GetTranslationHost (  )  const [inline]

Get the translation host to use for TranslateIPAddress().

References translationHost.

WORD OpalManager::GetUDPPortBase (  )  const [inline]

Get the UDP port number base for RAS channels

References OpalManager::OpalManager::PortInfo::base, and udpPorts.

WORD OpalManager::GetUDPPortMax (  )  const [inline]

Get the UDP port number base for RAS channels.

References OpalManager::OpalManager::PortInfo::max, and udpPorts.

virtual PBoolean OpalManager::HasCall ( const PString &  token  )  [inline, virtual]

Determine if a call is active. Return PTrue if there is an active call with the specified token. Note that the call could clear any time (even milliseconds) after this function returns PTrue.

Parameters:
token Token for identifying call

References activeCalls.

void OpalManager::InternalClearAllCalls ( OpalConnection::CallEndReason  reason,
bool  wait,
bool  first 
) [protected]

OpalCall* OpalManager::InternalCreateCall (  ) 

virtual PBoolean OpalManager::IsCallEstablished ( const PString &  token  )  [virtual]

Determine if a call is established. Return PTrue if there is an active call with the specified token and that call has at least two parties with media flowing between them. Note that the call could clear any time (even milliseconds) after this function returns PTrue.

Parameters:
token Token for identifying call

virtual PBoolean OpalManager::IsLocalAddress ( const PIPSocket::Address &  remoteAddress  )  const [virtual]

Determine if the address is "local", ie does not need any address translation (fixed or via STUN) to access.

The default behaviour checks if remoteAddress is a RFC1918 private IP address: 10.x.x.x, 172.16.x.x or 192.168.x.x.

virtual PBoolean OpalManager::IsMediaBypassPossible ( const OpalConnection source,
const OpalConnection destination,
unsigned  sessionID 
) const [virtual]

See if the media can bypass the local host.

Parameters:
source Source connection
destination Destination connection
sessionID Session ID for media channel

virtual bool OpalManager::IsRecording ( const PString &  callToken  )  [virtual]

Indicate if recording is currently active on call.

Parameters:
callToken Call token for call to check if recording

virtual PBoolean OpalManager::IsRTPNATEnabled ( OpalConnection connection,
const PIPSocket::Address &  localAddr,
const PIPSocket::Address &  peerAddr,
const PIPSocket::Address &  signalAddr,
PBoolean  incoming 
) [virtual]

Determine if the RTP session needs to accommodate a NAT router. For endpoints that do not use STUN or something similar to set up all the correct protocol embeddded addresses correctly when a NAT router is between the endpoints, it is possible to still accommodate the call, with some restrictions. This function determines if the RTP can proceed with special NAT allowances.

The special allowance is that the RTP code will ignore whatever the remote indicates in the protocol for the address to send RTP data and wait for the first packet to arrive from the remote and will then proceed to send all RTP data back to that address AND port.

The default behaviour checks the values of the physical link (localAddr/peerAddr) against the signaling address the remote indicated in the protocol, eg H.323 SETUP sourceCallSignalAddress or SIP "To" or "Contact" fields, and makes a guess that the remote is behind a NAT router.

Parameters:
connection Connection being checked
localAddr Local physical address of connection
peerAddr Remote physical address of connection
signalAddr Remotes signaling address as indicated by protocol of connection
incoming Incoming/outgoing connection

virtual PBoolean OpalManager::MakeConnection ( OpalCall call,
const PString &  party,
void *  userData = NULL,
unsigned int  options = 0,
OpalConnection::StringOptions stringOptions = NULL 
) [virtual]

Set up a connection to a remote party. An appropriate protocol (endpoint) is determined from the party parameter. That endpoint is then called to create a connection and that connection is attached to the call provided.

If the endpoint is already occupied in a call then the endpoints list is further searched for additional endpoints that support the protocol. For example multiple pstn endpoints may be present for multiple LID's.

The general form for this party parameter is:

[proto:][alias@][transport$]address[:port]

where the various fields will have meanings specific to the endpoint type. For example, with H.323 it could be "h323:Fred@site.com" which indicates a user Fred at gatekeeper size.com. Whereas for the PSTN endpoint it could be "pstn:5551234" which is to call 5551234 on the first available PSTN line.

The default for the proto is the name of the protocol for the first endpoint attached to the manager. Other fields default to values on an endpoint basis.

This function usually returns almost immediately with the connection continuing to occur in a new background thread.

If PFalse is returned then the connection could not be established. For example if a PSTN endpoint is used and the associated line is engaged then it may return immediately. Returning a non-NULL value does not mean that the connection will succeed, only that an attempt is being made.

The default behaviour is pure.

Parameters:
call Owner of connection
party Party to call
userData user data to pass to connections
options options to pass to conneciton

virtual void OpalManager::OnAlerting ( OpalConnection connection  )  [virtual]

Call back for remote party being alerted on outgoing call. This function is called after the connection is informed that the remote endpoint is "ringing". This function is generally called some time after the MakeConnection() function was called.

If PFalse is returned the connection is aborted.

If an application overrides this function, it should generally call the ancestor version for correct operation. An application would typically 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 OnAlerting() on the connection's associated OpalCall object.

Parameters:
connection Connection that was established

virtual OpalConnection::AnswerCallResponse OpalManager::OnAnswerCall ( OpalConnection connection,
const PString &  caller 
) [virtual]

virtual void OpalManager::OnApplyStringOptions ( OpalConnection conn,
OpalConnection::StringOptions stringOptions 
) [virtual]

virtual void OpalManager::OnClearedCall ( OpalCall call  )  [virtual]

A call back function whenever a call is cleared. A call is cleared whenever there is no longer any connections attached to it. This function is called just before the call is deleted. However, it may be used to display information on the call after completion, eg the call parties and duration.

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

The default behaviour removes the call from the activeCalls dictionary.

Parameters:
call Connection that was established

virtual void OpalManager::OnClosedMediaStream ( const OpalMediaStream stream  )  [virtual]

Call back for closed a media stream.

The default behaviour does nothing.

Parameters:
stream Stream being closed

virtual void OpalManager::OnConnected ( OpalConnection connection  )  [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 OnConnected() on the connections associated OpalCall object.

Parameters:
connection Connection that was established

virtual void OpalManager::OnEstablished ( OpalConnection connection  )  [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 CONNECT pdu has been received and either fast start was in operation or the subsequent Open Logical Channels have occurred. For SIP it indicates the INVITE/OK/ACK sequence is complete.

The default behaviour calls the OnEstablished() on the connection's associated OpalCall object.

Parameters:
connection Connection that was established

virtual void OpalManager::OnEstablishedCall ( OpalCall call  )  [virtual]

A call back function whenever a call is completed. In telephony terminology a completed call is one where there is an established link between two parties.

This called from the OpalCall::OnEstablished() function.

The default behaviour does nothing.

Parameters:
call Call that was completed

virtual PBoolean OpalManager::OnForwarded ( OpalConnection connection,
const PString &  remoteParty 
) [virtual]

A call back function whenever a connection is forwarded.

The default behaviour does nothing.

Parameters:
connection Connection that was held
remoteParty The new remote party

virtual void OpalManager::OnHold ( OpalConnection connection  )  [virtual]

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

A call back function whenever a connection is "held" or "retrieved". This indicates that a connection to an endpoint was held, or retrieved, either locally or by the remote endpoint.

The default behaviour does nothing.

Parameters:
connection Connection that was held/retrieved
fromRemote Indicates remote has held local connection
onHold Indicates have just been held/retrieved.

virtual PBoolean OpalManager::OnIncomingConnection ( OpalConnection connection  )  [virtual]

Parameters:
connection Connection that is calling

virtual PBoolean OpalManager::OnIncomingConnection ( OpalConnection connection,
unsigned  options 
) [virtual]

Parameters:
connection Connection that is calling
options options for new connection (can't use default as overrides will fail)

virtual PBoolean OpalManager::OnIncomingConnection ( OpalConnection connection,
unsigned  options,
OpalConnection::StringOptions stringOptions 
) [virtual]

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

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

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

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

The default behaviour is to call OnRouteConnection to determine a B party for the connection.

If the call associated with the incoming call already had two parties and this connection is a third party for a conference call then AnswerCallNow is returned as a B party is not required.

Parameters:
connection Connection that is calling
options options for new connection (can't use default as overrides will fail)

virtual void OpalManager::OnMWIReceived ( const PString &  party,
MessageWaitingType  type,
const PString &  extraInfo 
) [virtual]

Callback called when Message Waiting Indication (MWI) is received

Parameters:
party Name of party MWI is for
type Type of message that is waiting
extraInfo Addition information on the MWI

virtual void OpalManager::OnNewConnection ( OpalConnection connection  )  [virtual]

Call back for a new connection has been constructed. This is called after CreateConnection has returned a new connection. It allows an application to make any custom adjustments to the connection before it begins to process the protocol. behind it.

Parameters:
connection New connection just created

virtual PBoolean OpalManager::OnOpenMediaStream ( OpalConnection connection,
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 achieves the above using the FindMatchingCodecs() to determine what (if any) software codecs are required, the OpalConnection::CreateMediaStream() function to open streams and the CreateMediaPatch() function to create a patch for all of the streams and codecs just produced.

Parameters:
connection Connection that owns the media stream
stream New media stream being opened

virtual void OpalManager::OnProceeding ( OpalConnection connection  )  [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 OnProceeding() on the connection's associated OpalCall object.

Parameters:
connection Connection that is proceeeding

virtual void OpalManager::OnReleased ( OpalConnection connection  )  [virtual]

A call back function whenever a connection is released. This function can do any internal cleaning up and waiting on background threads that may be using the connection object.

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 OnReleased() on the connection's associated OpalCall object. This indicates to the call that the connection has been released so it can release the last remaining connection and then returns PTrue.

Parameters:
connection Connection that was established

virtual bool OpalManager::OnRouteConnection ( PStringSet &  routesTried,
const PString &  a_party,
const PString &  b_party,
OpalCall call,
unsigned  options,
OpalConnection::StringOptions stringOptions 
) [virtual]

Route a connection to another connection from an endpoint.

The default behaviour gets the destination address from the connection and translates it into an address by using the routeTable member variable and uses MakeConnection() to start the B-party connection.

Parameters:
routesTried Set of routes already tried
a_party Source local address
b_party Destination indicated by source
call Call for new connection
options Options for new connection (can't use default as overrides will fail)

virtual void OpalManager::OnRTPStatistics ( const OpalConnection connection,
const RTP_Session session 
) [virtual]

Callback from the RTP session for statistics monitoring. This is called every so many packets on the transmitter and receiver threads of the RTP session indicating that the statistics have been updated.

The default behaviour does nothing.

Parameters:
connection Connection for the channel
session Session with statistics

virtual PBoolean OpalManager::OnStartMediaPatch ( const OpalMediaPatch patch  )  [virtual]

Call back for a media patch thread starting. This function is called within the context of the thread associated with the media patch. It may be used to do any last checks on if the patch should proceed.

The default behaviour simply returns PTrue.

Parameters:
patch Media patch being started

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

Call back for remote endpoint has sent user input as a string.

The default behaviour call OpalConnection::SetUserInput() which saves the value so the GetUserInput() function can return it.

Parameters:
connection Connection input has come from
value String value of indication

virtual void OpalManager::OnUserInputTone ( OpalConnection connection,
char  tone,
int  duration 
) [virtual]

Call back for remote enpoint has sent user input as tones. 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 OpalCall function of the same name.

Parameters:
connection Connection input has come from
tone Tone received
duration Duration of tone

OpalManager::OpalCall::OpalCall ( OpalManager mgr  )  [protected]

OpalManager::PARRAY ( RouteTable  ,
RouteEntry   
)

OpalManager::PDECLARE_NOTIFIER ( PThread  ,
OpalManager  ,
GarbageMain   
) [protected]

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

Read a sequence of user indications from connection with timeouts.

Parameters:
connection Connection to read input from
terminators Characters that can terminte input
lastDigitTimeout Timeout on last digit in string
firstDigitTimeout Timeout on receiving any digits

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

Set the maximum audio jitter delay parameter.

If minDelay is set to zero then both the minimum and maximum will be set to zero which will disable the jitter buffer entirely.

If maxDelay is zero, or just less that minDelay, then the maximum jitter is set to the minimum and this disables the adaptive jitter, a fixed value is used.

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

void OpalManager::SetDefaultDisplayName ( const PString &  name,
bool  updateAll = true 
)

Set the default display name for all endpoints.

Parameters:
name New name
updateAll Update all registered endpoints

void OpalManager::SetDefaultILSServer ( const PString &  server  )  [inline]

Set the default ILS server to use for user lookup.

References ilsServer.

void OpalManager::SetDefaultUserName ( const PString &  name,
bool  updateAll = true 
)

Set the default username for all endpoints.

Parameters:
name New name
updateAll Update all registered endpoints

virtual void OpalManager::SetEchoCancelParams ( const OpalEchoCanceler::Params params  )  [inline, virtual]

Set the default parameters for the echo cancelation.

References echoCancelParams.

void OpalManager::SetMaxRtpPayloadSize ( PINDEX  size,
bool  mtu = false 
) [inline]

Get the maximum RTP payload size. Defaults to maximum safe MTU size (576 bytes as per RFC879) minus the typical size of the IP, UDP an RTP headers.

References rtpPayloadSizeMax.

void OpalManager::SetMediaFormatMask ( const PStringArray &  mask  ) 

Set the default media format mask.

void OpalManager::SetMediaFormatOrder ( const PStringArray &  order  ) 

Set the default media format order.

Parameters:
order New order

PBoolean OpalManager::SetNoMediaTimeout ( const PTimeInterval &  newInterval  ) 

Set the amount of time with no media that should cause a call to clear

Parameters:
newInterval New timeout for media

void OpalManager::SetProductInfo ( const OpalProductInfo info,
bool  updateAll = true 
)

Set the product info for all endpoints.

Parameters:
info New information
updateAll Update all registered endpoints

void OpalManager::SetRouteTable ( const RouteTable &  table  ) 

Set a route table for the manager. Note that this will make a copy of the table and not maintain a reference.

Parameters:
table New table to set for routing

PBoolean OpalManager::SetRouteTable ( const PStringArray &  specs  ) 

Parse a route table specification list for the manager. This removes the current routeTable and calls AddRouteEntry for every string in the array.

Returns PTrue if at least one entry was added.

Parameters:
specs Array of specification strings.

void OpalManager::SetRtpIpPorts ( unsigned  udpBase,
unsigned  udpMax 
)

Set the UDP port number base and max for RTP channels.

void OpalManager::SetRtpIpTypeofService ( unsigned  tos  )  [inline]

Set the IP Type Of Service byte for media (eg RTP) channels.

References rtpIpTypeofService.

virtual void OpalManager::SetSilenceDetectParams ( const OpalSilenceDetector::Params params  )  [inline, virtual]

Set the default parameters for the silence detector.

References silenceDetectParams.

PSTUNClient::NatTypes OpalManager::SetSTUNServer ( const PString &  server  ) 

Set the STUN server address, is of the form host[:port] Note that if the STUN server is found then the translationAddress is automatically set to the router address as determined by STUN.

void OpalManager::SetTCPPorts ( unsigned  tcpBase,
unsigned  tcpMax 
)

Set the TCP port number base and max for H.245 channels.

void OpalManager::SetTranslationAddress ( const PIPSocket::Address &  address  ) 

Set the translation address to use for TranslateIPAddress().

bool OpalManager::SetTranslationHost ( const PString &  host  ) 

Set the translation host to use for TranslateIPAddress().

void OpalManager::SetUDPPorts ( unsigned  udpBase,
unsigned  udpMax 
)

Set the TCP port number base and max for H.245 channels.

virtual PBoolean OpalManager::SetUpCall ( const PString &  partyA,
const PString &  partyB,
PString &  token,
void *  userData = NULL,
unsigned  options = 0,
OpalConnection::StringOptions stringOptions = NULL 
) [virtual]

Set up a call between two parties. This is used to initiate a call. Incoming calls are "answered" using a different mechanism.

The A party and B party strings indicate the protocol and address of the party to call in the style of a URL. The A party is the initiator of the call and the B party is the remote system being called. See the MakeConnection() function for more details on the format of these strings.

The token returned is a unique identifier for the call that allows an application to gain access to the call at later time. This is necesary as any pointer being returned could become invalid (due to being deleted) at any time due to the multithreaded nature of the OPAL system.

Parameters:
partyA The A party of call
partyB The B party of call
token Token for call
userData user data passed to Call and Connection
options options passed to connection
stringOptions complex string options passed to call

void OpalManager::ShutDownEndpoints (  ) 

Shut down all of the endpoints, clearing all calls. This is synchonous and will wait till everything is shut down. This will also assure no new calls come in whilein the process of shutting down.

virtual PBoolean OpalManager::StartRecording ( const PString &  callToken,
const PFilePath &  filename,
bool  mono = false 
) [virtual]

Start recording a call. Current version saves to a WAV file. It may either mix the receive and transmit audio stream to a single mono file, or the streams are placed into the left and right channels of a stereo WAV file.

Returns true if the call exists and there is no recording in progress for the call.

Parameters:
callToken Call token for call to record
filename File into which to record
mono Record as mono/stereo

virtual bool OpalManager::StopRecording ( const PString &  callToken  )  [virtual]

Stop a recording. Returns true if the call does exists, that recording is active is not indicated.

Parameters:
callToken Call token for call to stop recording

virtual PBoolean OpalManager::TranslateIPAddress ( PIPSocket::Address &  localAddress,
const PIPSocket::Address &  remoteAddress 
) [virtual]

Provide address translation hook. This will check to see that remoteAddress is NOT a local address by using IsLocalAddress() and if not, set localAddress to the translationAddress (if valid) which would normally be the router address of a NAT system.


Friends And Related Function Documentation

void OpalCall::OnReleased ( OpalConnection connection  )  [friend]


Member Data Documentation

PString OpalManager::defaultDisplayName [protected]

Referenced by GetDefaultDisplayName().

PString OpalManager::defaultUserName [protected]

Referenced by GetDefaultUserName().

std::map<PString, OpalEndPoint *> OpalManager::endpointMap [protected]

PReadWriteMutex OpalManager::endpointsMutex [protected]

PSyncPoint OpalManager::garbageCollectExit [protected]

PThread* OpalManager::garbageCollector [protected]

PString OpalManager::ilsServer [protected]

PAtomicInteger OpalManager::lastCallTokenID [protected]

PSyncPoint OpalManager::m_allCallsCleared [protected]

PAtomicInteger OpalManager::m_clearingAllCallsCount [protected]

Referenced by GetRecordManager().

unsigned OpalManager::maxAudioJitterDelay [protected]

Referenced by GetMaxAudioJitterDelay().

PStringArray OpalManager::mediaFormatMask [protected]

Referenced by GetMediaFormatMask().

PStringArray OpalManager::mediaFormatOrder [protected]

Referenced by GetMediaFormatOrder().

unsigned OpalManager::minAudioJitterDelay [protected]

Referenced by GetMinAudioJitterDelay().

PTimeInterval OpalManager::noMediaTimeout [protected]

Referenced by GetNoMediaTimeout().

Referenced by GetProductInfo().

RouteTable OpalManager::routeTable [protected]

Referenced by GetRouteTable().

PMutex OpalManager::routeTableMutex [protected]

PINDEX OpalManager::rtpPayloadSizeMax [protected]

PSTUNClient* OpalManager::stun [protected]

Referenced by GetSTUNClient().

PString OpalManager::stunServer [protected]

Referenced by GetSTUNServer().

Referenced by GetTCPPortBase(), and GetTCPPortMax().

PIPSocket::Address OpalManager::translationAddress [protected]

Referenced by GetTranslationAddress().

PString OpalManager::translationHost [protected]

Referenced by GetTranslationHost().

Referenced by GetUDPPortBase(), and GetUDPPortMax().


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

Generated on Fri Apr 10 21:32:55 2009 for OPAL by  doxygen 1.5.8