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: 23129 $
 * $Author: rjongbloed $
 * $Date: 2009-07-22 05:19:59 +0000 (Wed, 22 Jul 2009) $
 */

#ifndef OPAL_H323_H323EP_H
#define OPAL_H323_H323EP_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal/buildopts.h>

#if OPAL_H323

#include <opal/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>

#if OPAL_H460
#include <h460/h4601.h>
#endif


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

class H235SecurityInfo;

class H323Gatekeeper;
class H323SignalPDU;
class H323ServiceControlSession;


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

  public:
    enum {
      DefaultTcpSignalPort = 1720
    };

    H323EndPoint(
      OpalManager & manager
    );

    ~H323EndPoint();

    virtual void ShutDown();

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

    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;


    void AddCapability(
      H323Capability * capability   
    );

    PINDEX SetCapability(
      PINDEX descriptorNum, 
      PINDEX simultaneous,  
      H323Capability * cap  
    );

    PINDEX AddAllCapabilities(
      PINDEX descriptorNum, 
      PINDEX simultaneous,  
      const PString & name  
    );

    void AddAllUserInputCapabilities(
      PINDEX descriptorNum, 
      PINDEX simultaneous   
    );

    void RemoveCapabilities(
      const PStringArray & codecNames
    );

    void ReorderCapabilities(
      const PStringArray & preferenceOrder
    );

    H323Capability * FindCapability(
      const H245_Capability & cap  
    ) const;

    H323Capability * FindCapability(
      const H245_DataType & dataType  
    ) const;

    H323Capability * FindCapability(
      H323Capability::MainTypes mainType,   
      unsigned subType                      
    ) const;

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

    PBoolean SetGatekeeper(
      const PString & address,          
      H323Transport * transport = NULL  
    );

    PBoolean SetGatekeeperZone(
      const PString & address,          
      const PString & identifier,       
      H323Transport * transport = NULL  
    );

    PBoolean LocateGatekeeper(
      const PString & identifier,       
      H323Transport * transport = NULL  
    );

    PBoolean DiscoverGatekeeper(
      H323Transport * transport = NULL  
    );

    virtual H323Gatekeeper * CreateGatekeeper(
      H323Transport * transport  
    );

    H323Gatekeeper * GetGatekeeper() const { return gatekeeper; }

    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 gatekeeperUsername; }

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

    virtual H235Authenticators CreateAuthenticators();

    virtual void  OnGatekeeperConfirm();

    virtual void  OnGatekeeperReject();

    virtual void OnRegistrationConfirm();

    virtual void  OnRegistrationReject();

    virtual PBoolean NewIncomingConnection(
      OpalTransport * transport  
    );

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

    void HoldCall(
      const PString & token,        
      PBoolean localHold   
    );

    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 void OnConnectionCleared(
      H323Connection & connection,    
      const PString & token           
    );


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

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

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

    virtual void OnGatekeeperNATDetect(
      PIPSocket::Address publicAddr,         
      PString & gkIdentifier,                
      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 OnConferenceInvite(
      const H323SignalPDU & setupPDU
    );

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

    PBoolean AddAliasName(
      const PString & name  
    );

    PBoolean RemoveAliasName(
      const PString & name  
    );

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

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

    PBoolean AddAliasNamePattern(
      const PString & pattern  
    );

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

    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;

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

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

    unsigned GetInitialBandwidth() const { return initialBandwidth; }

    void SetInitialBandwidth(unsigned bandwidth) { initialBandwidth = bandwidth; }

#if OPAL_H239

    bool GetDefaultH239Control() const { return m_defaultH239Control; }

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

    virtual PBoolean OnSendFeatureSet(unsigned, H225_FeatureSet &);

    virtual void OnReceiveFeatureSet(unsigned, const H225_FeatureSet &);
        
    virtual void LoadBaseFeatureSet();

    virtual bool OnFeatureInstance(
      int instType,
      const PString & identifer
    );

#if OPAL_H460

    bool FeatureSetDisabled() const { return disableH460; }

    void FeatureSetDisable() { disableH460 = true; }

    H460_FeatureSet * GetFeatureSet() { return features.DeriveNewFeatureSet(); };
#endif

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

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

    WORD GetTCPPortBase() const { return manager.GetTCPPortBase(); }

    WORD GetTCPPortMax() const { return manager.GetTCPPortMax(); }

    void SetTCPPorts(unsigned tcpBase, unsigned tcpMax) { manager.SetTCPPorts(tcpBase, tcpMax); }

    WORD GetNextTCPPort() { return manager.GetNextTCPPort(); }

    WORD GetUDPPortBase() const { return manager.GetUDPPortBase(); }

    WORD GetUDPPortMax() const { return manager.GetUDPPortMax(); }

    void SetUDPPorts(unsigned udpBase, unsigned udpMax) { manager.SetUDPPorts(udpBase, udpMax); }

    WORD GetNextUDPPort() { return manager.GetNextUDPPort(); }

    WORD GetRtpIpPortBase() const { return manager.GetRtpIpPortBase(); }

    WORD GetRtpIpPortMax() const { return manager.GetRtpIpPortMax(); }

    void SetRtpIpPorts(unsigned udpBase, unsigned udpMax) { manager.SetRtpIpPorts(udpBase, udpMax); }

    WORD GetRtpIpPortPair() { return manager.GetRtpIpPortPair(); }

    BYTE GetRtpIpTypeofService() const { return manager.GetRtpIpTypeofService(); }

    void SetRtpIpTypeofService(unsigned tos) { manager.SetRtpIpTypeofService(tos); }

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

    const PTimeInterval & GetControlChannelStartTimeout() const { return controlChannelStartTimeout; }

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

    PBoolean SetNoMediaTimeout(
      const PTimeInterval & newInterval  
    ) { return 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; }

    PBoolean GetSendGRQ() const
    { return sendGRQ; }

    void SetSendGRQ(PBoolean v) 
    { sendGRQ = 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; }

    H323CallIdentityDict& GetCallIdentityDictionary() { return secondaryConnectionsActive; }

#if OPAL_H450
    unsigned GetNextH450CallIdentityValue() const { return ++nextH450CallIdentity; }
#endif

    PString GetDefaultTransport() const;

  protected:
    bool InternalCreateGatekeeper(H323Transport * transport);
    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;
    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 controlChannelStartTimeout;
    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;
    PBoolean          sendGRQ;

    /* 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
    mutable H323Capabilities capabilities;
    H323Gatekeeper *     gatekeeper;
    PString              gatekeeperUsername;
    PString              gatekeeperPassword;
    H323CallIdentityDict secondaryConnectionsActive;

#if OPAL_H450
    mutable PAtomicInteger nextH450CallIdentity;
#endif

#if OPAL_H460
    bool            disableH460;
    H460_FeatureSet features;
#endif

};

#endif // OPAL_H323

#endif // OPAL_H323_H323EP_H

---