h323ep.h

Go to the documentation of this file.

/*
 * h323ep.h
 *
 * H.323 protocol handler
 *
 * Open H323 Library
 *
 * Copyright (c) 1998-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 H323 Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions of this code were written with the assisance of funding from
 * Vovida Networks, Inc. http://www.vovida.com.
 *
 * Contributor(s): ______________________________________.
 *
 * $Revision: 31774 $
 * $Author: rjongbloed $
 * $Date: 2014-04-16 11:58:42 +1000 (Wed, 16 Apr 2014) $
 */

#ifndef OPAL_H323_H323EP_H
#define OPAL_H323_H323EP_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal_config.h>

#if OPAL_H323

#include <rtp/rtpep.h>
#include <opal/manager.h>
#include <opal/call.h>
#include <opal/transports.h>
#include <h323/h323con.h>
#include <h323/h323caps.h>
#include <h323/h235auth.h>
#include <h323/gkclient.h>
#include <asn/h225.h>
#include <h460/h4601.h>


class H225_EndpointType;
class H225_VendorIdentifier;
class H225_H221NonStandard;
class H225_ServiceControlDescriptor;
class H225_FeatureSet;

class H235SecurityInfo;

class H323Gatekeeper;
class H323SignalPDU;
class H323ServiceControlSession;

class H46019Server;



class H323EndPoint : public OpalRTPEndPoint
{
  PCLASSINFO(H323EndPoint, OpalRTPEndPoint);

  public:
    enum {
      DefaultTcpSignalPort = 1720
    };

    H323EndPoint(
      OpalManager & manager
    );

    ~H323EndPoint();

    virtual void ShutDown();

    virtual PBoolean GarbageCollection();

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

    virtual void OnReleased(
      OpalConnection & connection   
    );

    virtual PStringList GetAvailableStringOptions() const;

    virtual void SetEndpointTypeInfo(
      H225_EndpointType & info
    ) const;

    virtual void SetVendorIdentifierInfo(
      H225_VendorIdentifier & info
    ) const;

    virtual void SetH221NonStandardInfo(
      H225_H221NonStandard & info
    ) const;

    virtual bool SetGatewaySupportedProtocol(
      H225_ArrayOf_SupportedProtocols & protocols
    ) const;

    virtual bool OnSetGatewayPrefixes(
      PStringList & prefixes
    ) const;


    bool UseGatekeeper(
      const PString & address = PString::Empty(),     
      const PString & identifier = PString::Empty(),  
      const PString & localAddress = PString::Empty() 
    );

    bool SetGatekeeper(
      const PString & address,          
      const PString & localAddress = PString::Empty() 
    );

    bool SetGatekeeperZone(
      const PString & address,          
      const PString & identifier,       
      const PString & localAddress = PString::Empty() 
    );

    bool LocateGatekeeper(
      const PString & identifier,       
      const PString & localAddress = PString::Empty() 
    );

    bool DiscoverGatekeeper(
      const PString & localAddress = PString::Empty() 
    );

    virtual H323Gatekeeper * CreateGatekeeper(
      H323Transport * transport  
    );

    H323Gatekeeper * GetGatekeeper() const { return m_gatekeepers.IsEmpty() ? NULL : &m_gatekeepers.front(); }

    const PList<H323Gatekeeper> GetGatekeepers() const { return m_gatekeepers; }

    PBoolean IsRegisteredWithGatekeeper() const;

    PBoolean RemoveGatekeeper(
      int reason = -1    
    );

    virtual void SetGatekeeperPassword(
      const PString & password,
      const PString & username = PString::Empty()
    );

    virtual const PString & GetGatekeeperUsername() const { return m_gatekeeperUsername; }

    virtual const PString & GetGatekeeperPassword() const { return m_gatekeeperPassword; }

    enum { MaxGatekeeperAliasLimit = 1000000 };
    void SetGatekeeperAliasLimit(
      PINDEX limit   
    );

    PINDEX GetGatekeeperAliasLimit() const { return m_gatekeeperAliasLimit; }

    void SetGatekeeperSimulatePattern(bool sim) { m_gatekeeperSimulatePattern = sim; }

    bool GetGatekeeperSimulatePattern() const { return m_gatekeeperSimulatePattern; }

    virtual H235Authenticators CreateAuthenticators();

    virtual void OnGatekeeperStatus(
      H323Gatekeeper::RegistrationFailReasons status
    );

    virtual void NewIncomingConnection(
      OpalListener & listener,            
      const OpalTransportPtr & transport  
    );

    void InternalNewIncomingConnection(
      OpalTransportPtr transport,   
      bool reused = false
    );

    virtual H323Connection * CreateConnection(
      OpalCall & call,                         
      const PString & token,                   
      void * userData,                         
      OpalTransport & transport,               
      const PString & alias,                   
      const H323TransportAddress & address,    
      H323SignalPDU * setupPDU,                
      unsigned options = 0,
      OpalConnection::StringOptions * stringOptions = NULL 
    );

    virtual PBoolean SetupTransfer(
      const PString & token,        
      const PString & callIdentity, 
      const PString & remoteParty,  
      void * userData = NULL        
    );

    void TransferCall(
      const PString & token,        
      const PString & remoteParty,  
      const PString & callIdentity = PString::Empty()
    );

    void ConsultationTransfer(
      const PString & primaryCallToken,   
      const PString & secondaryCallToken  
    );

    PBoolean IntrudeCall(
      const PString & remoteParty,  
      unsigned capabilityLevel,     
      void * userData = NULL        
    );

    PBoolean ParsePartyName(
      const PString & party,          
      PString & alias,                
      H323TransportAddress & address, 
      OpalConnection::StringOptions * stringOptions = NULL 
    );

    PSafePtr<H323Connection> FindConnectionWithLock(
      const PString & token,     
      PSafetyMode mode = PSafeReadWrite
    );

    virtual PBoolean OnSendSignalSetup(H323Connection & connection,
                                   H323SignalPDU & setupPDU);

    virtual PBoolean OnSendCallProceeding(
      H323Connection & connection,
      H323SignalPDU & callProceedingPDU
    );

    virtual PBoolean OnSendConnect(
      H323Connection & connection,
      H323SignalPDU & connectPDU
    );
    
    virtual PBoolean OnIncomingCall(
      H323Connection & connection,    
      const H323SignalPDU & setupPDU,   
      H323SignalPDU & alertingPDU       
    );

    virtual PBoolean OnOutgoingCall(
      H323Connection & conn, 
      const H323SignalPDU & connectPDU
    );

    virtual PBoolean OnCallTransferInitiate(
      H323Connection & connection,    
      const PString & remoteParty     
    );

    virtual PBoolean OnCallTransferIdentify(
      H323Connection & connection    
    );

    virtual void OnSendARQ(
      H323Connection & conn,
      H225_AdmissionRequest & arq
    );

    virtual OpalConnection::AnswerCallResponse OnAnswerCall(
      H323Connection & connection,    
      const PString & callerName,       
      const H323SignalPDU & setupPDU,   
      H323SignalPDU & connectPDU,       
      H323SignalPDU & progressPDU        
    );
    virtual OpalConnection::AnswerCallResponse OnAnswerCall(
       OpalConnection & connection,
       const PString & caller
    );

    virtual PBoolean OnAlerting(
      H323Connection & connection,    
      const H323SignalPDU & alertingPDU,  
      const PString & user                
    );

    virtual PBoolean OnSendAlerting(
      H323Connection & connection,  
      H323SignalPDU & alerting,     
      const PString & calleeName,   
      PBoolean withMedia                
    );

    virtual PBoolean OnSentAlerting(
      H323Connection & connection
    );

    virtual PBoolean OnConnectionForwarded(
      H323Connection & connection,    
      const PString & forwardParty,   
      const H323SignalPDU & pdu       
    );

    virtual PBoolean ForwardConnection(
      H323Connection & connection,    
      const PString & forwardParty,   
      const H323SignalPDU & pdu       
    );

    virtual void OnConnectionEstablished(
      H323Connection & connection,    
      const PString & token           
    );

    virtual PBoolean IsConnectionEstablished(
      const PString & token   
    );


    virtual PBoolean OnStartLogicalChannel(
      H323Connection & connection,    
      H323Channel & channel           
    );

    virtual void OnClosedLogicalChannel(
      H323Connection & connection,    
      const H323Channel & channel     
    );

    virtual void OnGatekeeperNATDetect(
      const PIPSocket::Address & publicAddr, 
      H323TransportAddress & gkRouteAddress  
    );

    virtual void OnHTTPServiceControl(
      unsigned operation,  
      unsigned sessionId,  
      const PString & url  
    );

    virtual void OnCallCreditServiceControl(
      const PString & amount,  
      PBoolean mode          
    );

    virtual void OnServiceControlSession(
      unsigned type,
      unsigned sessionid,
      const H323ServiceControlSession & session,
      H323Connection * connection
    );

    virtual H323ServiceControlSession * CreateServiceControlSession(
      const H225_ServiceControlDescriptor & contents
    );

    virtual PBoolean OnCallIndependentSupplementaryService(
      const H323SignalPDU & setupPDU
    );

    virtual PBoolean OnNegotiateConferenceCapabilities(
      const H323SignalPDU & setupPDU
    );

    virtual void SetDefaultLocalPartyName(
      const PString & name  
    );

    virtual void SetLocalUserName(
      const PString & name  
    );

    virtual const PString & GetLocalUserName() const { return localAliasNames.front(); }

    bool AddAliasNames(
      const PStringList & names  
    );

    bool AddAliasName(
      const PString & name  
    );

    bool RemoveAliasName(
      const PString & name  
    );

    const PStringList & GetAliasNames() const { return localAliasNames; }

    bool AddAliasNamePattern(
      const PString & pattern  
    );

    bool RemoveAliasNamePattern(
      const PString & pattern  
    );

    void SetAliasNamePatterns(
      const PStringList & patterns  
    ) { localAliasPatterns = patterns; }

    const PStringList & GetAliasNamePatterns() const { return localAliasPatterns; }

    static int ParseAliasPatternRange(const PString & pattern, PString & start, PString & end);

    const PString & GetDefaultILSServer() const { return manager.GetDefaultILSServer(); }

    void SetDefaultILSServer(
      const PString & server
    ) { manager.SetDefaultILSServer(server); }

    PBoolean IsFastStartDisabled() const
      { return disableFastStart; }

    void DisableFastStart(
      PBoolean mode 
    ) { disableFastStart = mode; } 

    PBoolean IsH245TunnelingDisabled() const
      { return disableH245Tunneling; }

    void DisableH245Tunneling(
      PBoolean mode 
    ) { disableH245Tunneling = mode; } 

    PBoolean IsH245inSetupDisabled() const
      { return disableH245inSetup; }

    void DisableH245inSetup(
      PBoolean mode 
    ) { disableH245inSetup = mode; } 

    bool IsForcedSymmetricTCS() const
      { return m_forceSymmetricTCS; }

    void ForceSymmetricTCS(
      bool mode 
    ) { m_forceSymmetricTCS = mode; } 

    PBoolean IsH245Disabled() const
    { return m_bH245Disabled; }

    void DisableH245(PBoolean bH245Disabled) { m_bH245Disabled = bH245Disabled; } 
    
    PBoolean CanDisplayAmountString() const
      { return canDisplayAmountString; }

    void SetCanDisplayAmountString(
      PBoolean mode 
    ) { canDisplayAmountString = mode; } 

    PBoolean CanEnforceDurationLimit() const
      { return canEnforceDurationLimit; }

    void SetCanEnforceDurationLimit(
      PBoolean mode 
    ) { canEnforceDurationLimit = mode; } 

#if OPAL_H450

    unsigned GetCallIntrusionProtectionLevel() const { return callIntrusionProtectionLevel; }

    void SetCallIntrusionProtectionLevel(
      unsigned level  
    ) { PAssert(level<=3, PInvalidParameter); callIntrusionProtectionLevel = level; }
#endif

    virtual void OnReceivedInitiateReturnError();

    PBoolean CanAutoCallForward() const { return autoCallForward; }

    const H323Capabilities & GetCapabilities() const { return m_capabilities; }

    enum TerminalTypes {
      e_TerminalOnly = 50,
      e_TerminalAndMC = 70,
      e_GatewayOnly = 60,
      e_GatewayAndMC = 80,
      e_GatewayAndMCWithDataMP = 90,
      e_GatewayAndMCWithAudioMP = 100,
      e_GatewayAndMCWithAVMP = 110,
      e_GatekeeperOnly = 120,
      e_GatekeeperWithDataMP = 130,
      e_GatekeeperWithAudioMP = 140,
      e_GatekeeperWithAVMP = 150,
      e_MCUOnly = 160,
      e_MCUWithDataMP = 170,
      e_MCUWithAudioMP = 180,
      e_MCUWithAVMP = 190
    };

    void SetTerminalType(TerminalTypes type) { terminalType = type; }

    TerminalTypes GetTerminalType() const { return terminalType; }

    PBoolean IsTerminal() const;

    PBoolean IsGateway() const;

    PBoolean IsGatekeeper() const;

    PBoolean IsMCU() const;

    unsigned GetMinAudioJitterDelay() const { return manager.GetMinAudioJitterDelay(); }

    unsigned GetMaxAudioJitterDelay() const { return manager.GetMaxAudioJitterDelay(); }

    void SetAudioJitterDelay(
      unsigned minDelay,   
      unsigned maxDelay    
    ) { manager.SetAudioJitterDelay(minDelay, maxDelay); }

#if OPAL_H239

    bool GetDefaultH239Control() const { return m_defaultH239Control; }

    void SetDefaultH239Control(
      bool on   
    ) { m_defaultH239Control = on; }
#endif

#if OPAL_H460

    bool H460Disabled() const { return m_disableH460; }

    void DisableH460(bool disable = true) { m_disableH460 = disable; }

    H460_FeatureSet * GetFeatures() const { return m_features; }

    virtual H460_FeatureSet * CreateFeatureSet(
      H323Connection * connection
    );
    virtual H460_FeatureSet * InternalCreateFeatureSet(
      H323Connection * connection
    );

    virtual PBoolean OnSendFeatureSet(H460_MessageType pduType, H225_FeatureSet &);

    virtual void OnReceiveFeatureSet(H460_MessageType pduType, const H225_FeatureSet &);
    
    virtual bool OnLoadFeature(
      H460_Feature & feature
    );

#endif // OPAL_H460

#if OPAL_H460_NAT
    H46019Server * GetH46019Server() const { return m_H46019Server; }
#endif

    virtual PBoolean IsLocalAddress(
      const PIPSocket::Address & remoteAddress
    ) const { return manager.IsLocalAddress(remoteAddress); }

    virtual void TranslateTCPAddress(
      PIPSocket::Address & localAddr,
      const PIPSocket::Address & remoteAddr
    );

    const PTimeInterval & GetSignallingChannelCallTimeout() const { return signallingChannelCallTimeout; }

    const PTimeInterval & GetFirstSignalPduTimeout() const { return firstSignalPduTimeout; }

    const PTimeInterval & GetEndSessionTimeout() const { return endSessionTimeout; }

    const PTimeInterval & GetMasterSlaveDeterminationTimeout() const { return masterSlaveDeterminationTimeout; }

    unsigned GetMasterSlaveDeterminationRetries() const { return masterSlaveDeterminationRetries; }

    const PTimeInterval & GetCapabilityExchangeTimeout() const { return capabilityExchangeTimeout; }

    const PTimeInterval & GetLogicalChannelTimeout() const { return logicalChannelTimeout; }

    const PTimeInterval & GetRequestModeTimeout() const { return logicalChannelTimeout; }

    const PTimeInterval & GetRoundTripDelayTimeout() const { return roundTripDelayTimeout; }

    const PTimeInterval & GetRoundTripDelayRate() const { return roundTripDelayRate; }

    PBoolean ShouldClearCallOnRoundTripFail() const { return clearCallOnRoundTripFail; }

    const PTimeInterval & GetNoMediaTimeout() const { return manager.GetNoMediaTimeout(); }

    void SetNoMediaTimeout(
      const PTimeInterval & newInterval  
    ) { manager.SetNoMediaTimeout(newInterval); }

    const PTimeInterval & GetGatekeeperRequestTimeout() const { return gatekeeperRequestTimeout; }

    unsigned GetGatekeeperRequestRetries() const { return gatekeeperRequestRetries; }

    const PTimeInterval & GetRasRequestTimeout() const { return rasRequestTimeout; }

    unsigned GetRasRequestRetries() const { return rasRequestRetries; }

    const PTimeInterval & GetGatekeeperTimeToLive() const { return registrationTimeToLive; }

    void SetGatekeeperTimeToLive(const PTimeInterval & ttl) { registrationTimeToLive = ttl; }

    const PString & GetGkAccessTokenOID() const { return gkAccessTokenOID; }

    void SetGkAccessTokenOID(const PString & token) { gkAccessTokenOID = token; }

    bool GetSendGRQ() const { return m_sendGRQ; }

    void SetSendGRQ(bool v) { m_sendGRQ = v; }

    bool GetOneSignalAddressInRRQ() const { return m_oneSignalAddressInRRQ; }

    void SetOneSignalAddressInRRQ(bool v) { m_oneSignalAddressInRRQ = v; }

    const PTimeInterval & GetCallTransferT1() const { return callTransferT1; }

    const PTimeInterval & GetCallTransferT2() const { return callTransferT2; }

    const PTimeInterval & GetCallTransferT3() const { return callTransferT3; }

    const PTimeInterval & GetCallTransferT4() const { return callTransferT4; }

    const PTimeInterval & GetCallIntrusionT1() const { return callIntrusionT1; }
    const PTimeInterval & GetCallIntrusionT2() const { return callIntrusionT2; }
    const PTimeInterval & GetCallIntrusionT3() const { return callIntrusionT3; }
    const PTimeInterval & GetCallIntrusionT4() const { return callIntrusionT4; }
    const PTimeInterval & GetCallIntrusionT5() const { return callIntrusionT5; }
    const PTimeInterval & GetCallIntrusionT6() const { return callIntrusionT6; }

#if OPAL_H450

    H323CallIdentityDict& GetCallIdentityDictionary() { return m_secondaryConnectionsActive; }

    unsigned GetNextH450CallIdentityValue() const { return ++m_nextH450CallIdentity; }
#endif //OPAL_H450

    virtual PString GetDefaultTransport() const;

    virtual WORD GetDefaultSignalPort() const;

    PString GetCompatibility(
      H323Connection::CompatibilityIssues issue    
    ) const;

    bool SetCompatibility(
      H323Connection::CompatibilityIssues issue,    
      const PString & regex         
    );

    bool AddCompatibility(
      H323Connection::CompatibilityIssues issue,    
      const PString & regex         
    );

    bool HasCompatibilityIssue(
      H323Connection::CompatibilityIssues issue,            
      const OpalProductInfo & productInfo   
    ) const;

    void TickleGatekeeperMonitor() { m_gatekeeperMonitorTickle.Signal(); }

  protected:
    bool InternalCreateGatekeeper(
      const H323TransportAddress & remoteAddress,
      const PString & localAddress
    );
    void RestartGatekeeper();
    void GatekeeperMonitor();

    H323Connection * InternalMakeCall(
      OpalCall & call,
      const PString & existingToken,           
      const PString & callIdentity,            
      unsigned capabilityLevel,                
      const PString & remoteParty,             
      void * userData,                         
      unsigned int options = 0,                
      OpalConnection::StringOptions * stringOptions = NULL 
    );

    // Configuration variables, commonly changed
    PStringList     localAliasNames;
    PStringList     localAliasPatterns;
    PBoolean        autoCallForward;
    PBoolean        disableFastStart;
    PBoolean        disableH245Tunneling;
    PBoolean        disableH245inSetup;
    bool            m_forceSymmetricTCS;
    PBoolean        m_bH245Disabled; /* enabled or disabled h245 */
    PBoolean        canDisplayAmountString;
    PBoolean        canEnforceDurationLimit;
#if OPAL_H450
    unsigned        callIntrusionProtectionLevel;
#endif

    TerminalTypes   terminalType;

#if OPAL_H239
    bool            m_defaultH239Control;
#endif

    PBoolean        clearCallOnRoundTripFail;

    // Some more configuration variables, rarely changed.
    PTimeInterval signallingChannelCallTimeout;
    PTimeInterval firstSignalPduTimeout;
    PTimeInterval endSessionTimeout;
    PTimeInterval masterSlaveDeterminationTimeout;
    unsigned      masterSlaveDeterminationRetries;
    PTimeInterval capabilityExchangeTimeout;
    PTimeInterval logicalChannelTimeout;
    PTimeInterval requestModeTimeout;
    PTimeInterval roundTripDelayTimeout;
    PTimeInterval roundTripDelayRate;
    PTimeInterval gatekeeperRequestTimeout;
    unsigned      gatekeeperRequestRetries;
    PTimeInterval rasRequestTimeout;
    unsigned      rasRequestRetries;
    PTimeInterval registrationTimeToLive;

    PString       gkAccessTokenOID;
    bool          m_sendGRQ;
    bool          m_oneSignalAddressInRRQ;

    /* Protect against absence of a response to the ctIdentify reqest
       (Transferring Endpoint - Call Transfer with a secondary Call) */
    PTimeInterval callTransferT1;
    /* Protect against failure of completion of the call transfer operation
       involving a secondary Call (Transferred-to Endpoint) */
    PTimeInterval callTransferT2;
    /* Protect against failure of the Transferred Endpoint not responding
       within sufficient time to the ctInitiate APDU (Transferring Endpoint) */
    PTimeInterval callTransferT3;
    /* May optionally operate - protects against absence of a response to the
       ctSetup request (Transferred Endpoint) */
    PTimeInterval callTransferT4;

    PTimeInterval callIntrusionT1;
    PTimeInterval callIntrusionT2;
    PTimeInterval callIntrusionT3;
    PTimeInterval callIntrusionT4;
    PTimeInterval callIntrusionT5;
    PTimeInterval callIntrusionT6;

    // Dynamic variables
    PSafeDictionary<PString, H323Connection> m_connectionsByCallId;
    std::set<OpalTransportPtr> m_reusableTransports;

    H323Capabilities m_capabilities;

    PList<H323Gatekeeper> m_gatekeepers;
    PString               m_gatekeeperUsername;
    PString               m_gatekeeperPassword;
    PINDEX                m_gatekeeperAliasLimit;
    bool                  m_gatekeeperSimulatePattern;
    PThread             * m_gatekeeperMonitor;
    bool                  m_gatekeeperMonitorStop;
    PSyncPoint            m_gatekeeperMonitorTickle;
    PMutex                m_gatekeeperMutex;

#if OPAL_H450
    H323CallIdentityDict   m_secondaryConnectionsActive;
    mutable PAtomicInteger m_nextH450CallIdentity;
#endif

#if OPAL_H460
    bool              m_disableH460;
    H460_FeatureSet * m_features;
#endif
#if OPAL_H460_NAT
    H46019Server * m_H46019Server;
#endif

    typedef map<H323Connection::CompatibilityIssues, PRegularExpression> CompatibilityEndpoints;
    CompatibilityEndpoints m_compatibility;

  private:
    P_REMOVE_VIRTUAL_VOID(OnConnectionCleared(H323Connection &, const PString &));
    P_REMOVE_VIRTUAL_VOID(OnRTPStatistics(const H323Connection &, const OpalRTPSession &) const);
    P_REMOVE_VIRTUAL(PBoolean, OnConferenceInvite(const H323SignalPDU &), false);
    P_REMOVE_VIRTUAL_VOID(OnGatekeeperConfirm());
    P_REMOVE_VIRTUAL_VOID(OnGatekeeperReject());
    P_REMOVE_VIRTUAL_VOID(OnRegistrationConfirm());
    P_REMOVE_VIRTUAL_VOID(OnRegistrationReject());
    P_REMOVE_VIRTUAL_VOID(OnGatekeeperNATDetect(PIPSocket::Address, PString &, H323TransportAddress &));
};

#endif // OPAL_H323

#endif // OPAL_H323_H323EP_H