manager.h

Go to the documentation of this file.

/*
 * manager.h
 *
 * OPAL system manager.
 *
 * Open Phone Abstraction Library (OPAL)
 * Formally known as the Open H323 project.
 *
 * Copyright (c) 2001 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open Phone Abstraction Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): ______________________________________.
 *
 * $Revision: 24038 $
 * $Author: rjongbloed $
 * $Date: 2010-02-09 22:21:59 -0600 (Tue, 09 Feb 2010) $
 */

#ifndef OPAL_OPAL_MANAGER_H
#define OPAL_OPAL_MANAGER_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal/buildopts.h>

#include <opal/pres_ent.h>
#include <opal/call.h>
#include <opal/connection.h> //OpalConnection::AnswerCallResponse
#include <opal/guid.h>
#include <codec/silencedetect.h>
#include <codec/echocancel.h>
#include <ptclib/pstun.h>
#include <ptclib/url.h>

#if OPAL_VIDEO
#include <ptlib/videoio.h>
#endif

class OpalEndPoint;
class OpalMediaPatch;


class OpalManager : public PObject
{
    PCLASSINFO(OpalManager, PObject);
  public:
    OpalManager();

    ~OpalManager();

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

    void DetachEndPoint(
      const PString & prefix
    );
    void DetachEndPoint(
      OpalEndPoint * endpoint
    );

    OpalEndPoint * FindEndPoint(
      const PString & prefix
    );

    PList<OpalEndPoint> GetEndPoints() const;

    void ShutDownEndpoints();

    virtual PSafePtr<OpalCall> SetUpCall(
      const PString & partyA,       
      const PString & partyB,       
      void * userData = NULL,       
      unsigned options = 0,         
      OpalConnection::StringOptions * stringOptions = NULL   
    );
    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  
    ) { return activeCalls.FindWithLock(token, PSafeReference) != NULL; }

    PINDEX GetCallCount() const { return activeCalls.GetSize(); }


    virtual PBoolean IsCallEstablished(
      const PString & token  
    );

    PSafePtr<OpalCall> FindCallWithLock(
      const PString & token,  
      PSafetyMode mode = PSafeReadWrite
    ) { return activeCalls.FindWithLock(token, mode); }

    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 OpalCall * CreateCall(
      void * userData            
    );
    OpalCall * InternalCreateCall();

    virtual void DestroyCall(
      OpalCall * call
    );

    virtual PString GetNextToken(char prefix);

    virtual PSafePtr<OpalPresentity> AddPresentity(
      const PString & presentity  
    );

    virtual PSafePtr<OpalPresentity> GetPresentity(
      const PString & presentity,         
      PSafetyMode mode = PSafeReference   
    );

    virtual PStringList GetPresentities() const;

    virtual bool RemovePresentity(
      const PString & presentity  
    );

    virtual PBoolean Message(
      const PString & to, 
      const PString & body
    );
    virtual PBoolean Message(
      const PURL & to, 
      const PString & type,
      const PString & body,
      PURL & from, 
      PString & conversationId
    );

    virtual void OnMessageReceived(
      const PURL & from, 
      const PString & fromName,
      const PURL & to, 
      const PString & type,
      const PString & body,
      const PString & conversationId
    );

#if OPAL_HAS_IM

    virtual bool TransmitExternalIM(
      OpalConnection & conn, 
      const OpalMediaFormat & format, 
      RTP_IMFrame & frame
    );
#endif


    virtual PSafePtr<OpalConnection> MakeConnection(
      OpalCall & call,                   
      const PString & party,             
      void * userData = NULL,            
      unsigned int options = 0,          
      OpalConnection::StringOptions * stringOptions = NULL
    );

    virtual void OnNewConnection(
      OpalConnection & connection   
    );

    virtual PBoolean OnIncomingConnection(
      OpalConnection & connection,   
      unsigned options,              
      OpalConnection::StringOptions * stringOptions
    );

    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); // For backward compatibility

    virtual PBoolean OnForwarded(
      OpalConnection & connection,  
      const PString & remoteParty         
    );

    virtual OpalMediaFormatList GetCommonMediaFormats(
      bool transportable,  
      bool pcmAudio        
    ) const;

    virtual void AdjustMediaFormats(
      bool local,                         
      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 RTP_UDP * CreateRTPSession (const RTP_Session::Params & params);

    virtual void OnRTPStatistics(
      const OpalConnection & connection,  
      const RTP_Session & session         
    );

    virtual bool OnLocalRTP(
      OpalConnection & connection1, 
      OpalConnection & connection2, 
      unsigned sessionID,           
      bool opened                   
    ) const;

    bool SetMediaBypass(
      const PString & token1, 
      const PString & token2, 
      bool bypass,            
      unsigned sessionID = 0, 
      bool network  = true    
    );
    static bool SetMediaBypass(
      OpalConnection & connection1, 
      OpalConnection & connection2, 
      bool bypass,                  
      unsigned sessionID = 0        
    );

    virtual void OnClosedMediaStream(
      const OpalMediaStream & stream     
    );

#if OPAL_VIDEO

    virtual PBoolean CreateVideoInputDevice(
      const OpalConnection & connection,    
      const OpalMediaFormat & mediaFormat,  
      PVideoInputDevice * & device,         
      PBoolean & autoDelete                     
    );

    virtual PBoolean CreateVideoOutputDevice(
      const OpalConnection & connection,    
      const OpalMediaFormat & mediaFormat,  
      PBoolean preview,                         
      PVideoOutputDevice * & device,        
      PBoolean & autoDelete                     
    );
#endif

    virtual OpalMediaPatch * CreateMediaPatch(
      OpalMediaStream & source,         
      PBoolean requiresPatchThread = PTrue
    );

    virtual void DestroyMediaPatch(
      OpalMediaPatch * patch
    );

    virtual void OnStartMediaPatch(
      OpalConnection & connection,  
      OpalMediaPatch & patch        
    );

    virtual void OnStopMediaPatch(
      OpalConnection & connection,  
      OpalMediaPatch & patch        
    );

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

    enum MessageWaitingType { 
      NoMessageWaiting,
      VoiceMessageWaiting, 
      FaxMessageWaiting,
      PagerMessageWaiting,
      MultimediaMessageWaiting,
      TextMessageWaiting,
      NumMessageWaitingTypes
    };

    virtual void OnMWIReceived(
      const PString & party,    
      MessageWaitingType type,  
      const PString & extraInfo 
    );
    
    
    class RouteEntry : public PObject
    {
        PCLASSINFO(RouteEntry, PObject);
      public:
        RouteEntry(const PString & pat, const PString & dest);
        void PrintOn(ostream & strm) const;
        PString            pattern;
        PString            destination;
        PRegularExpression regex;
    };
    PARRAY(RouteTable, RouteEntry);

    virtual PBoolean AddRouteEntry(
      const PString & spec  
    );

    PBoolean SetRouteTable(
      const PStringArray & specs  
    );

    void SetRouteTable(
      const RouteTable & table  
    );

    const RouteTable & GetRouteTable() const { return m_routeTable; }

    virtual PString ApplyRouteTable(
      const PString & source,      
      const PString & destination, 
      PINDEX & entry
    );

#if OPAL_HAS_MIXER

    virtual PBoolean StartRecording(
      const PString & callToken,  
      const PFilePath & filename, 
      const OpalRecordManager::Options & options = false 
    );

    virtual bool IsRecording(
      const PString & callToken   
    );

    virtual bool StopRecording(
      const PString & callToken   
    );

#endif

    const OpalProductInfo & GetProductInfo() const { return productInfo; }

    void SetProductInfo(
      const OpalProductInfo & info, 
      bool updateAll = true         
    );

    const PString & GetDefaultUserName() const { return defaultUserName; }

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

    const PString & GetDefaultDisplayName() const { return defaultDisplayName; }

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

#if OPAL_VIDEO

    //
    // these functions are deprecated and used only for backwards compatibility
    // applications should use OpalConnection::GetAutoStart() to check whether
    // a specific media type can be auto-started
    //

    bool CanAutoStartReceiveVideo() const { return (OpalMediaType::Video().GetAutoStart()&OpalMediaType::Receive) != 0; }

    void SetAutoStartReceiveVideo(bool can) { OpalMediaType::Video().GetDefinition()->SetAutoStart(OpalMediaType::Receive, can); }

    bool CanAutoStartTransmitVideo() const { return (OpalMediaType::Video().GetAutoStart()&OpalMediaType::Transmit) != 0; }

    void SetAutoStartTransmitVideo(bool can) { OpalMediaType::Video().GetDefinition()->SetAutoStart(OpalMediaType::Transmit, can); }

#endif

    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 { return translationHost; }

    bool SetTranslationHost(
      const PString & host
    );

    const PIPSocket::Address & GetTranslationAddress() const { return translationAddress; }

    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 { return stunServer; }

    PSTUNClient * GetSTUNClient() const { return stun; }

    WORD GetTCPPortBase() const { return tcpPorts.base; }

    WORD GetTCPPortMax() const { return tcpPorts.max; }

    void SetTCPPorts(unsigned tcpBase, unsigned tcpMax);

    WORD GetNextTCPPort();

    WORD GetUDPPortBase() const { return udpPorts.base; }

    WORD GetUDPPortMax() const { return udpPorts.max; }

    void SetUDPPorts(unsigned udpBase, unsigned udpMax);

    WORD GetNextUDPPort();

    WORD GetRtpIpPortBase() const { return rtpIpPorts.base; }

    WORD GetRtpIpPortMax() const { return rtpIpPorts.max; }

    void SetRtpIpPorts(unsigned udpBase, unsigned udpMax);

    WORD GetRtpIpPortPair();

    BYTE GetRtpIpTypeofService() const { return rtpIpTypeofService; }

    void SetRtpIpTypeofService(unsigned tos) { rtpIpTypeofService = (BYTE)tos; }

    PINDEX GetMaxRtpPayloadSize() const { return rtpPayloadSizeMax; }

    void SetMaxRtpPayloadSize(
      PINDEX size,
      bool mtu = false
    ) { rtpPayloadSizeMax = size - (mtu ? (20+16+12) : 0); }

    PINDEX GetMaxRtpPacketSize() const { return rtpPacketSizeMax; }

    void SetMaxRtpPacketSize(
      PINDEX size
    ) { rtpPacketSizeMax = size; }

    unsigned GetMinAudioJitterDelay() const { return minAudioJitterDelay; }

    unsigned GetMaxAudioJitterDelay() const { return maxAudioJitterDelay; }

    void SetAudioJitterDelay(
      unsigned minDelay,   
      unsigned maxDelay    
    );

    const PStringArray & GetMediaFormatOrder() const { return mediaFormatOrder; }

    void SetMediaFormatOrder(
      const PStringArray & order   
    );

    const PStringArray & GetMediaFormatMask() const { return mediaFormatMask; }

    void SetMediaFormatMask(
      const PStringArray & mask   //< New mask
    );

    virtual void SetSilenceDetectParams(
      const OpalSilenceDetector::Params & params
    ) { silenceDetectParams = params; }

    const OpalSilenceDetector::Params & GetSilenceDetectParams() const { return silenceDetectParams; }
    
#if OPAL_AEC

    virtual void SetEchoCancelParams(
      const OpalEchoCanceler::Params & params
    ) { echoCancelParams = params; }

    const OpalEchoCanceler::Params & GetEchoCancelParams() const { return echoCancelParams; }
#endif

#if OPAL_VIDEO

    virtual PBoolean SetVideoInputDevice(
      const PVideoDevice::OpenArgs & deviceArgs 
    );

    const PVideoDevice::OpenArgs & GetVideoInputDevice() const { return videoInputDevice; }

    virtual PBoolean SetVideoPreviewDevice(
      const PVideoDevice::OpenArgs & deviceArgs 
    );

    const PVideoDevice::OpenArgs & GetVideoPreviewDevice() const { return videoPreviewDevice; }

    virtual PBoolean SetVideoOutputDevice(
      const PVideoDevice::OpenArgs & deviceArgs 
    );

    const PVideoDevice::OpenArgs & GetVideoOutputDevice() const { return videoOutputDevice; }

#endif

    PBoolean DetectInBandDTMFDisabled() const
      { return disableDetectInBandDTMF; }

    void DisableDetectInBandDTMF(
      PBoolean mode 
    ) { disableDetectInBandDTMF = mode; } 

    const PTimeInterval & GetNoMediaTimeout() const { return noMediaTimeout; }

    PBoolean SetNoMediaTimeout(
      const PTimeInterval & newInterval  
    );

    const PString & GetDefaultILSServer() const { return ilsServer; }

    void SetDefaultILSServer(
      const PString & server
    ) { ilsServer = server; }

    // needs to be public for gcc 3.4
    void GarbageCollection();

#ifdef OPAL_ZRTP
    virtual bool GetZRTPEnabled() const;
#endif

    virtual void OnApplyStringOptions(
      OpalConnection & conn,
      OpalConnection::StringOptions & stringOptions
    );

  protected:
    // Configuration variables
    OpalProductInfo productInfo;

    PString       defaultUserName;
    PString       defaultDisplayName;

    BYTE          rtpIpTypeofService;
    PINDEX        rtpPayloadSizeMax;
    PINDEX        rtpPacketSizeMax;
    unsigned      minAudioJitterDelay;
    unsigned      maxAudioJitterDelay;
    PStringArray  mediaFormatOrder;
    PStringArray  mediaFormatMask;
    PBoolean          disableDetectInBandDTMF;
    PTimeInterval noMediaTimeout;
    PString       ilsServer;

    OpalSilenceDetector::Params silenceDetectParams;
#if OPAL_AEC
    OpalEchoCanceler::Params echoCancelParams;
#endif

#if OPAL_VIDEO
    PVideoDevice::OpenArgs videoInputDevice;
    PVideoDevice::OpenArgs videoPreviewDevice;
    PVideoDevice::OpenArgs videoOutputDevice;
#endif

    struct PortInfo {
      void Set(
        unsigned base,
        unsigned max,
        unsigned range,
        unsigned dflt
      );
      WORD GetNext(
        unsigned increment
      );

      PMutex mutex;
      WORD   base;
      WORD   max;
      WORD   current;
    } tcpPorts, udpPorts, rtpIpPorts;
    
    class InterfaceMonitor : public PInterfaceMonitorClient
    {
      PCLASSINFO(InterfaceMonitor, PInterfaceMonitorClient);
      
      enum {
        OpalManagerInterfaceMonitorClientPriority = 100,
      };
      public:
        InterfaceMonitor(OpalManager & manager);
        
      protected:
        virtual void OnAddInterface(const PIPSocket::InterfaceEntry & entry);
        virtual void OnRemoveInterface(const PIPSocket::InterfaceEntry & entry);
        
        OpalManager & m_manager;
    };

    PString            translationHost;
    PIPSocket::Address translationAddress;
    PString            stunServer;
    PSTUNClient      * stun;
    InterfaceMonitor * interfaceMonitor;

    RouteTable m_routeTable;
    PMutex     m_routeMutex;

    // Dynamic variables
    PReadWriteMutex     endpointsMutex;
    PList<OpalEndPoint> endpointList;
    std::map<PString, OpalEndPoint *> endpointMap;

    PAtomicInteger lastCallTokenID;

    class CallDict : public PSafeDictionary<PString, OpalCall>
    {
      public:
        CallDict(OpalManager & mgr) : manager(mgr) { }
        virtual void DeleteObject(PObject * object) const;
        OpalManager & manager;
    } activeCalls;

    PSafeDictionary<PString, OpalPresentity> m_presentities;

    PAtomicInteger m_clearingAllCallsCount;
    PMutex         m_clearingAllCallsMutex;
    PSyncPoint     m_allCallsCleared;
    void InternalClearAllCalls(OpalConnection::CallEndReason reason, bool wait, bool first);

    PThread    * garbageCollector;
    PSyncPoint   garbageCollectExit;
    PDECLARE_NOTIFIER(PThread, OpalManager, GarbageMain);

#ifdef OPAL_ZRTP
    bool zrtpEnabled;
#endif

    friend OpalCall::OpalCall(OpalManager & mgr);
    friend void OpalCall::InternalOnClear();

  private:
    P_REMOVE_VIRTUAL(OpalCall *,CreateCall(), 0);
    P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(OpalConnection &, unsigned), false);
    P_REMOVE_VIRTUAL(PBoolean, OnIncomingConnection(OpalConnection &), false);
    P_REMOVE_VIRTUAL(PBoolean, OnStartMediaPatch(const OpalMediaPatch &), false);
    P_REMOVE_VIRTUAL_VOID(AdjustMediaFormats(const OpalConnection &, OpalMediaFormatList &) const);
};


PString  OpalGetVersion();
unsigned OpalGetMajorVersion();
unsigned OpalGetMinorVersion();
unsigned OpalGetBuildNumber();


#endif // OPAL_OPAL_MANAGER_H


// End of File ///////////////////////////////////////////////////////////////

---