# gkclient.h

Go to the documentation of this file.

    00001 /*
    00002  * gkclient.h
    00003  *
    00004  * Gatekeeper client protocol handler
    00005  *
    00006  * Open H323 Library
    00007  *
    00008  * Copyright (c) 1998-2001 Equivalence Pty. Ltd.
    00009  *
    00010  * The contents of this file are subject to the Mozilla Public License
    00011  * Version 1.0 (the "License"); you may not use this file except in
    00012  * compliance with the License. You may obtain a copy of the License at
    00013  * http://www.mozilla.org/MPL/
    00014  *
    00015  * Software distributed under the License is distributed on an "AS IS"
    00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
    00017  * the License for the specific language governing rights and limitations
    00018  * under the License.
    00019  *
    00020  * The Original Code is Open H323 Library.
    00021  *
    00022  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
    00023  *
    00024  * Portions of this code were written with the assisance of funding from
    00025  * iFace, Inc. http://www.iface.com
    00026  *
    00027  * Contributor(s): ______________________________________.
    00028  *
    00029  * $Revision: 28549 $
    00030  * $Author: rjongbloed $
    00031  * $Date: 2012-11-16 05:31:10 -0600 (Fri, 16 Nov 2012) $
    00032  */
    00033
    00034 #ifndef OPAL_H323_GKCLIENT_H
    00035 #define OPAL_H323_GKCLIENT_H
    00036
    00037 #ifdef P_USE_PRAGMA
    00038 #pragma interface
    00039 #endif
    00040
    00041 #include <opal/buildopts.h>
    00042
    00043 #if OPAL_H323
    00044
    00045 #include <opal/mediafmt.h>
    00046 #include <h323/h225ras.h>
    00047 #include <h323/h235auth.h>
    00048
    00049 #if OPAL_H460
    00050 class H460_FeatureSet;
    00051 #endif
    00052
    00053 class H323Connection;
    00054 class H225_ArrayOf_AliasAddress;
    00055 class H225_H323_UU_PDU;
    00056 class H225_AlternateGK;
    00057 class H225_ArrayOf_AlternateGK;
    00058 class H225_ArrayOf_ServiceControlSession;
    00059 class H225_FeatureSet;
    00060
    00061
    00063
    00066 class H323Gatekeeper : public H225_RAS
    00067 {
    00068     PCLASSINFO(H323Gatekeeper, H225_RAS);
    00069   public:
    00074     H323Gatekeeper(
    00075       H323EndPoint & endpoint,
    00076       H323Transport * transport
    00077     );
    00078
    00081     ~H323Gatekeeper();
    00083
    00086     virtual PBoolean WriteTo(
    00087       H323TransactionPDU & pdu,
    00088       const H323TransportAddressArray & addresses,
    00089       PBoolean callback = true
    00090     );
    00092
    00095     PBoolean OnReceiveGatekeeperConfirm(const H225_GatekeeperConfirm & gcf);
    00096     PBoolean OnReceiveGatekeeperReject(const H225_GatekeeperReject & grj);
    00097     PBoolean OnReceiveRegistrationConfirm(const H225_RegistrationConfirm & rcf);
    00098     PBoolean OnReceiveRegistrationReject(const H225_RegistrationReject & rrj);
    00099     PBoolean OnReceiveUnregistrationRequest(const H225_UnregistrationRequest & urq);
    00100     PBoolean OnReceiveUnregistrationConfirm(const H225_UnregistrationConfirm & ucf);
    00101     PBoolean OnReceiveUnregistrationReject(const H225_UnregistrationReject & urj);
    00102     PBoolean OnReceiveAdmissionConfirm(const H225_AdmissionConfirm & acf);
    00103     PBoolean OnReceiveAdmissionReject(const H225_AdmissionReject & arj);
    00104     PBoolean OnReceiveDisengageRequest(const H225_DisengageRequest & drq);
    00105     PBoolean OnReceiveBandwidthConfirm(const H225_BandwidthConfirm & bcf);
    00106     PBoolean OnReceiveBandwidthRequest(const H225_BandwidthRequest & brq);
    00107     PBoolean OnReceiveInfoRequest(const H225_InfoRequest & irq);
    00108     PBoolean OnReceiveServiceControlIndication(const H225_ServiceControlIndication &);
    00109     void OnSendGatekeeperRequest(H225_GatekeeperRequest & grq);
    00110     void OnSendAdmissionRequest(H225_AdmissionRequest & arq);
    00111     PBoolean OnSendFeatureSet(unsigned, H225_FeatureSet & features) const;
    00112     void OnReceiveFeatureSet(unsigned, const H225_FeatureSet & features) const;
    00114
    00119     PBoolean DiscoverAny();
    00120
    00125     PBoolean DiscoverByName(
    00126       const PString & identifier
    00127     );
    00128
    00133     PBoolean DiscoverByAddress(
    00134       const H323TransportAddress & address
    00135     );
    00136
    00140     PBoolean DiscoverByNameAndAddress(
    00141       const PString & identifier,
    00142       const H323TransportAddress & address
    00143     );
    00144
    00147     PBoolean RegistrationRequest(
    00148       PBoolean autoReregister = true,
    00149       PBoolean didGkDiscovery = false
    00150     );
    00151
    00154     PBoolean UnregistrationRequest(
    00155       int reason
    00156     );
    00157
    00160     PBoolean LocationRequest(
    00161       const PString & alias,
    00162       H323TransportAddress & address
    00163     );
    00164
    00167     PBoolean LocationRequest(
    00168       const PStringList & aliases,
    00169       H323TransportAddress & address
    00170     );
    00171
    00172     struct AdmissionResponse {
    00173       AdmissionResponse();
    00174
    00175       unsigned rejectReason;
    00176
    00177       PBoolean gatekeeperRouted;
    00178       PINDEX endpointCount;
    00179       H323TransportAddress * transportAddress;
    00180       PBYTEArray * accessTokenData;
    00181
    00182       H225_ArrayOf_AliasAddress * aliasAddresses;
    00183       H225_ArrayOf_AliasAddress * destExtraCallInfo;
    00184     };
    00185
    00188     PBoolean AdmissionRequest(
    00189       H323Connection & connection,
    00190       AdmissionResponse & response,
    00191       PBoolean ignorePreGrantedARQ = false
    00192     );
    00193
    00196     PBoolean DisengageRequest(
    00197       const H323Connection & connection,
    00198       unsigned reason
    00199     );
    00200
    00203     PBoolean BandwidthRequest(
    00204       H323Connection & connection,
    00205       OpalBandwidth requestedBandwidth
    00206     );
    00207
    00210     void InfoRequestResponse();
    00211
    00214     void InfoRequestResponse(
    00215       const H323Connection & connection
    00216     );
    00217
    00220     void InfoRequestResponse(
    00221       const H323Connection & connection,
    00222       const H225_H323_UU_PDU & pdu,
    00223       PBoolean sent
    00224     );
    00225
    00228     virtual void OnServiceControlSessions(
    00229       const H225_ArrayOf_ServiceControlSession & serviceControl,
    00230       H323Connection * connection
    00231     );
    00232
    00235     virtual void OnTerminalAliasChanged();
    00237
    00242     PBoolean IsDiscoveryComplete() const { return discoveryComplete; }
    00243
    00246     PBoolean IsRegistered() const { return m_registrationFailReason == RegistrationSuccessful; }
    00247
    00248     enum RegistrationFailReasons {
    00249       RegistrationSuccessful,
    00250       UnregisteredLocally,
    00251       UnregisteredByGatekeeper,
    00252       GatekeeperLostRegistration,
    00253       InvalidListener,
    00254       DuplicateAlias,
    00255       SecurityDenied,
    00256       TransportError,
    00257       NumRegistrationFailReasons,
    00258       GatekeeperRejectReasonMask = 0x4000,
    00259       RegistrationRejectReasonMask = 0x8000,
    00260       UnregistrationRejectReasonMask = 0x10000
    00261     };
    00262     static PString GetRegistrationFailReasonString(RegistrationFailReasons reason);
    00263     friend ostream & operator<<(ostream & strm, RegistrationFailReasons reason) { return strm << GetRegistrationFailReasonString(reason); }
    00264
    00267     RegistrationFailReasons GetRegistrationFailReason() const { return m_registrationFailReason; }
    00268
    00277     PString GetName() const;
    00278
    00281     const PString & GetEndpointIdentifier() const { return endpointIdentifier; }
    00282
    00287     void SetPassword(
    00288       const PString & password,
    00289       const PString & username = PString()
    00290     );
    00291
    00292     /*
    00293      * Return the call signalling address for the gatekeeper (if present)
    00294      */
    00295     H323TransportAddress GetGatekeeperRouteAddress() const
    00296     { return gkRouteAddress; }
    00298
    00299 #if OPAL_H460
    00300     H460_FeatureSet & GetFeatures();
    00301 #endif
    00302
    00303   protected:
    00304     bool StartGatekeeper(const H323TransportAddress & address);
    00305     virtual bool DiscoverGatekeeper();
    00306     unsigned SetupGatekeeperRequest(H323RasPDU & request);
    00307
    00308     void Connect(const H323TransportAddress & address, const PString & gatekeeperIdentifier);
    00309     PDECLARE_NOTIFIER(PThread, H323Gatekeeper, MonitorMain);
    00310     PDECLARE_NOTIFIER(PTimer, H323Gatekeeper, TickleMonitor);
    00311     void RegistrationTimeToLive();
    00312
    00313     void SetInfoRequestRate(
    00314       const PTimeInterval & rate
    00315     );
    00316     void ClearInfoRequestRate();
    00317     H225_InfoRequestResponse & BuildInfoRequestResponse(
    00318       H323RasPDU & response,
    00319       unsigned seqNum
    00320     );
    00321     PBoolean SendUnsolicitedIRR(
    00322       H225_InfoRequestResponse & irr,
    00323       H323RasPDU & response
    00324     );
    00325
    00326     void SetAlternates(
    00327       const H225_ArrayOf_AlternateGK & alts,
    00328       PBoolean permanent
    00329     );
    00330
    00331     virtual PBoolean MakeRequest(
    00332       Request & request
    00333     );
    00334     PBoolean MakeRequestWithReregister(
    00335       Request & request,
    00336       unsigned unregisteredTag
    00337     );
    00338
    00339     virtual H323Transport * CreateTransport(PIPSocket::Address bindng = PIPSocket::GetDefaultIpAny(), WORD port = 0, PBoolean reuseAddr = false);
    00340
    00341     // Handling interface changes
    00342     void OnAddInterface(const PIPSocket::InterfaceEntry & entry, PINDEX priority);
    00343     void OnRemoveInterface(const PIPSocket::InterfaceEntry & entry, PINDEX priority);
    00344     bool SetListenerAddresses(H225_ArrayOf_TransportAddress & pdu);
    00345
    00346     // Gatekeeper registration state variables
    00347     bool     discoveryComplete;
    00348     PString  endpointIdentifier;
    00349     RegistrationFailReasons m_registrationFailReason;
    00350     void SetRegistrationFailReason(unsigned reason, unsigned commandMask);
    00351     void SetRegistrationFailReason(RegistrationFailReasons reason);
    00352
    00353     PDECLARE_InterfaceNotifier(H323Gatekeeper, OnHighPriorityInterfaceChange);
    00354     PDECLARE_InterfaceNotifier(H323Gatekeeper, OnLowPriorityInterfaceChange);
    00355
    00356     class AlternateInfo : public PObject {
    00357       PCLASSINFO(AlternateInfo, PObject);
    00358       public:
    00359         AlternateInfo(H225_AlternateGK & alt);
    00360         ~AlternateInfo();
    00361         Comparison Compare(const PObject & obj);
    00362         void PrintOn(ostream & strm) const;
    00363
    00364         H323TransportAddress rasAddress;
    00365         PString              gatekeeperIdentifier;
    00366         unsigned             priority;
    00367         enum {
    00368           NoRegistrationNeeded,
    00369           NeedToRegister,
    00370           Register,
    00371           IsRegistered,
    00372           RegistrationFailed
    00373         } registrationState;
    00374
    00375       private:
    00376         // Disable copy constructor and assignment
    00377         AlternateInfo(const AlternateInfo &other): PObject(other) { }
    00378         AlternateInfo & operator=(const AlternateInfo &) { return *this; }
    00379     };
    00380     PSortedList<AlternateInfo> alternates;
    00381     bool               alternatePermanent;
    00382     PSemaphore         requestMutex;
    00383     H235Authenticators authenticators;
    00384
    00385     enum {
    00386       RequireARQ,
    00387       PregrantARQ,
    00388       PreGkRoutedARQ
    00389     } pregrantMakeCall, pregrantAnswerCall;
    00390     H323TransportAddress gkRouteAddress;
    00391
    00392     // Gatekeeper operation variables
    00393     bool       autoReregister;
    00394     bool       reregisterNow;
    00395     PTimer     timeToLive;
    00396     bool       requiresDiscovery;
    00397     PTimer     infoRequestRate;
    00398     bool       willRespondToIRR;
    00399     PThread  * monitor;
    00400     bool       monitorStop;
    00401     PSyncPoint monitorTickle;
    00402
    00403     PDictionary<POrdinalKey, H323ServiceControlSession> serviceControlSessions;
    00404
    00405 #if OPAL_H460
    00406     H460_FeatureSet * features;
    00407 #endif
    00408
    00409 };
    00410
    00411
    00412 PLIST(H323GatekeeperList, H323Gatekeeper);
    00413
    00414
    00415 #endif // OPAL_H323
    00416
    00417 #endif // OPAL_H323_GKCLIENT_H
    00418
    00419