gkclient.h

Go to the documentation of this file.

/*
 * gkclient.h
 *
 * Gatekeeper client 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
 * iFace, Inc. http://www.iface.com
 *
 * Contributor(s): ______________________________________.
 *
 * $Revision: 30798 $
 * $Author: rjongbloed $
 * $Date: 2013-10-31 16:14:02 +1100 (Thu, 31 Oct 2013) $
 */

#ifndef OPAL_H323_GKCLIENT_H
#define OPAL_H323_GKCLIENT_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <opal/buildopts.h>

#if OPAL_H323

#include <opal/mediafmt.h>
#include <h323/h225ras.h>
#include <h323/h235auth.h>

#if OPAL_H460
class H460_FeatureSet;
#endif

class H323Connection;
class H225_ArrayOf_AliasAddress;
class H225_H323_UU_PDU;
class H225_AlternateGK;
class H225_ArrayOf_AlternateGK;
class H225_ArrayOf_ServiceControlSession;
class H225_FeatureSet;



class H323Gatekeeper : public H225_RAS
{
    PCLASSINFO(H323Gatekeeper, H225_RAS);
  public:
    H323Gatekeeper(
      H323EndPoint & endpoint,  
      H323Transport * transport       
    );

    ~H323Gatekeeper();
    
    virtual PBoolean WriteTo(
      H323TransactionPDU & pdu,
      const H323TransportAddressArray & addresses,
      PBoolean callback = true
    );

    PBoolean OnReceiveGatekeeperConfirm(const H225_GatekeeperConfirm & gcf);
    PBoolean OnReceiveGatekeeperReject(const H225_GatekeeperReject & grj);
    PBoolean OnReceiveRegistrationConfirm(const H225_RegistrationConfirm & rcf);
    PBoolean OnReceiveRegistrationReject(const H225_RegistrationReject & rrj);
    PBoolean OnReceiveUnregistrationRequest(const H225_UnregistrationRequest & urq);
    PBoolean OnReceiveUnregistrationConfirm(const H225_UnregistrationConfirm & ucf);
    PBoolean OnReceiveUnregistrationReject(const H225_UnregistrationReject & urj);
    PBoolean OnReceiveAdmissionConfirm(const H225_AdmissionConfirm & acf);
    PBoolean OnReceiveAdmissionReject(const H225_AdmissionReject & arj);
    PBoolean OnReceiveDisengageRequest(const H225_DisengageRequest & drq);
    PBoolean OnReceiveDisengageReject(const H323RasPDU &, const H225_DisengageReject &);
    PBoolean OnReceiveBandwidthConfirm(const H225_BandwidthConfirm & bcf);
    PBoolean OnReceiveBandwidthRequest(const H225_BandwidthRequest & brq);
    PBoolean OnReceiveInfoRequest(const H225_InfoRequest & irq);
    PBoolean OnReceiveInfoRequestResponse(const H225_InfoRequestResponse & irr);
    PBoolean OnReceiveServiceControlIndication(const H225_ServiceControlIndication &);
    void OnSendGatekeeperRequest(H225_GatekeeperRequest & grq);
    void OnSendAdmissionRequest(H225_AdmissionRequest & arq);
    PBoolean OnSendFeatureSet(unsigned, H225_FeatureSet & features) const;
    void OnReceiveFeatureSet(unsigned, const H225_FeatureSet & features) const;

    PBoolean DiscoverAny();

    PBoolean DiscoverByName(
      const PString & identifier  
    );

    PBoolean DiscoverByAddress(
      const H323TransportAddress & address 
    );

    PBoolean DiscoverByNameAndAddress(
      const PString & identifier,
      const H323TransportAddress & address
    );

    PBoolean RegistrationRequest(
      PBoolean autoReregister = true,  
      PBoolean didGkDiscovery = false  
    );

    PBoolean UnregistrationRequest(
      int reason      
    );

    PBoolean LocationRequest(
      const PString & alias,          
      H323TransportAddress & address  
    );

    PBoolean LocationRequest(
      const PStringList & aliases,    
      H323TransportAddress & address  
    );

    struct AdmissionResponse {
      AdmissionResponse();

      unsigned rejectReason;                      

      PBoolean gatekeeperRouted;                      
      PINDEX endpointCount;                       
      H323TransportAddress * transportAddress;    
      PBYTEArray * accessTokenData;               

      H225_ArrayOf_AliasAddress * aliasAddresses; 
      H225_ArrayOf_AliasAddress * destExtraCallInfo; 
    };

    PBoolean AdmissionRequest(
      H323Connection & connection,      
      AdmissionResponse & response,     
      PBoolean ignorePreGrantedARQ = false  
    );

    PBoolean DisengageRequest(
      const H323Connection & connection,  
      unsigned reason                     
    );

    PBoolean BandwidthRequest(
      H323Connection & connection,    
      OpalBandwidth requestedBandwidth     
    );

    void InfoRequestResponse();

    void InfoRequestResponse(
      const H323Connection & connection  
    );

    void InfoRequestResponse(
      const H323Connection & connection,  
      const H225_H323_UU_PDU & pdu,       
      PBoolean sent                           
    );

    virtual void OnServiceControlSessions(
      const H225_ArrayOf_ServiceControlSession & serviceControl,
      H323Connection * connection
    );
    
    virtual void OnTerminalAliasChanged();

    PBoolean IsDiscoveryComplete() const { return discoveryComplete; }

    PBoolean IsRegistered() const { return m_registrationFailReason == RegistrationSuccessful; }

    enum RegistrationFailReasons {
      RegistrationSuccessful,
      UnregisteredLocally,
      UnregisteredByGatekeeper,
      GatekeeperLostRegistration,
      InvalidListener,
      DuplicateAlias,
      SecurityDenied,
      TransportError,
      TryingAlternate,
      NumRegistrationFailReasons,
      GatekeeperRejectReasonMask = 0x4000,
      RegistrationRejectReasonMask = 0x8000,
      UnregistrationRejectReasonMask = 0x10000
    };
    static PString GetRegistrationFailReasonString(RegistrationFailReasons reason);
    friend ostream & operator<<(ostream & strm, RegistrationFailReasons reason) { return strm << GetRegistrationFailReasonString(reason); }

    RegistrationFailReasons GetRegistrationFailReason() const { return m_registrationFailReason; }

    PString GetName() const;

    const PString & GetEndpointIdentifier() const { return endpointIdentifier; }

    void SetPassword(
      const PString & password,            
      const PString & username = PString() 
    );
        
    /*
     * Return the call signalling address for the gatekeeper (if present)
     */
    H323TransportAddress GetGatekeeperRouteAddress() const
    { return gkRouteAddress; }

#if OPAL_H460
    H460_FeatureSet & GetFeatures();
#endif

  protected:
    bool StartGatekeeper(const H323TransportAddress & address);
    virtual bool DiscoverGatekeeper();
    unsigned SetupGatekeeperRequest(H323RasPDU & request);
        
    void Connect(const H323TransportAddress & address, const PString & gatekeeperIdentifier);
    PDECLARE_NOTIFIER(PThread, H323Gatekeeper, MonitorMain);
    PDECLARE_NOTIFIER(PTimer, H323Gatekeeper, TickleMonitor);
    void RegistrationTimeToLive();

    void SetInfoRequestRate(
      const PTimeInterval & rate
    );
    void ClearInfoRequestRate();
    H225_InfoRequestResponse & BuildInfoRequestResponse(
      H323RasPDU & response,
      unsigned seqNum
    );
    PBoolean SendUnsolicitedIRR(
      H225_InfoRequestResponse & irr,
      H323RasPDU & response
    );

    void SetAlternates(
      const H225_ArrayOf_AlternateGK & alts,
      bool permanent
    );

    virtual PBoolean MakeRequest(
      Request & request
    );
    PBoolean MakeRequestWithReregister(
      Request & request,
      unsigned unregisteredTag
    );
    
    virtual H323Transport * CreateTransport(PIPSocket::Address bindng = PIPSocket::GetDefaultIpAny(), WORD port = 0, PBoolean reuseAddr = false);
    
    // Handling interface changes
    void OnAddInterface(const PIPSocket::InterfaceEntry & entry, PINDEX priority);
    void OnRemoveInterface(const PIPSocket::InterfaceEntry & entry, PINDEX priority);
    bool SetListenerAddresses(H225_ArrayOf_TransportAddress & pdu);

    // Gatekeeper registration state variables
    bool     discoveryComplete;
    PString  endpointIdentifier;
    RegistrationFailReasons m_registrationFailReason;
    void SetRegistrationFailReason(unsigned reason, unsigned commandMask);
    void SetRegistrationFailReason(RegistrationFailReasons reason);
    
    PDECLARE_InterfaceNotifier(H323Gatekeeper, OnHighPriorityInterfaceChange);
    PDECLARE_InterfaceNotifier(H323Gatekeeper, OnLowPriorityInterfaceChange);
    
    class AlternateInfo : public PObject {
      PCLASSINFO(AlternateInfo, PObject);
      public:
        AlternateInfo(H225_AlternateGK & alt);
        ~AlternateInfo();
        Comparison Compare(const PObject & obj) const;
        void PrintOn(ostream & strm) const;

        H323TransportAddress rasAddress;
        PString              gatekeeperIdentifier;
        unsigned             priority;
        enum {
          NoRegistrationNeeded,
          NeedToRegister,
          IsRegistered,
          RegistrationFailed
        } registrationState;

      private:
        // Disable copy constructor and assignment
        AlternateInfo(const AlternateInfo &other): PObject(other) { }
        AlternateInfo & operator=(const AlternateInfo &) { return *this; }
    };
    typedef PSortedList<AlternateInfo> AlternateList;
    AlternateList m_alternates;
    bool          m_alternateTemporary;

    PSemaphore         requestMutex;
    H235Authenticators authenticators;

    enum {
      RequireARQ,
      PregrantARQ,
      PreGkRoutedARQ
    } pregrantMakeCall, pregrantAnswerCall;
    H323TransportAddress gkRouteAddress;

    // Gatekeeper operation variables
    bool       autoReregister;
    bool       reregisterNow;
    PTimer     timeToLive;
    bool       requiresDiscovery;
    PTimer     infoRequestRate;
    bool       willRespondToIRR;
    PThread  * monitor;
    bool       monitorStop;
    PSyncPoint monitorTickle;

    PDictionary<POrdinalKey, H323ServiceControlSession> serviceControlSessions;
        
#if OPAL_H460
    H460_FeatureSet * features;
#endif
        
};


PLIST(H323GatekeeperList, H323Gatekeeper);


#endif // OPAL_H323

#endif // OPAL_H323_GKCLIENT_H