Main Page | Namespace List | Class Hierarchy | Class List | Directories | File List | Namespace Members | Class Members | File Members

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-2000 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  * $Log: gkclient.h,v $
00030  * Revision 1.53  2004/09/03 01:06:08  csoutheren
00031  * Added initial hooks for H.460 GEF
00032  * Thanks to Simon Horne and ISVO (Asia) Pte Ltd. for this contribution
00033  *
00034  * Revision 1.52  2004/03/04 04:49:34  csoutheren
00035  * Added access function for gatekeeper routed address
00036  *
00037  * Revision 1.51  2003/03/26 00:46:25  robertj
00038  * Had another go at making H323Transactor being able to be created
00039  *   without having a listener running.
00040  *
00041  * Revision 1.50  2003/02/12 23:59:22  robertj
00042  * Fixed adding missing endpoint identifer in SETUP packet when gatekeeper
00043  * routed, pointed out by Stefan Klein
00044  * Also fixed correct rutrn of gk routing in IRR packet.
00045  *
00046  * Revision 1.49  2003/02/07 06:37:42  robertj
00047  * Changed registration state to an enum so can determine why the RRQ failed.
00048  *
00049  * Revision 1.48  2003/01/06 07:09:28  robertj
00050  * Further fixes for alternate gatekeeper, thanks Kevin Bouchard
00051  *
00052  * Revision 1.47  2002/12/23 22:46:38  robertj
00053  * Changed gatekeeper discovery so an GRJ does not indicate "discovered".
00054  * Added trace output of alternate gatekeepers list.
00055  *
00056  * Revision 1.46  2002/11/28 04:41:44  robertj
00057  * Added support for RAS ServiceControlIndication command.
00058  *
00059  * Revision 1.45  2002/11/27 06:54:52  robertj
00060  * Added Service Control Session management as per Annex K/H.323 via RAS
00061  *   only at this stage.
00062  * Added H.248 ASN and very primitive infrastructure for linking into the
00063  *   Service Control Session management system.
00064  * Added basic infrastructure for Annex K/H.323 HTTP transport system.
00065  * Added Call Credit Service Control to display account balances.
00066  *
00067  * Revision 1.44  2002/11/21 07:21:46  robertj
00068  * Improvements to alternate gatekeeper client code, thanks Kevin Bouchard
00069  *
00070  * Revision 1.43  2002/09/18 06:58:29  robertj
00071  * Fixed setting of IRR frequency, an RCF could reset timer so it did not time
00072  *   out correctly and send IRR in time causing problems with gatekeeper.
00073  *
00074  * Revision 1.42  2002/09/16 01:14:15  robertj
00075  * Added #define so can select if #pragma interface/implementation is used on
00076  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00077  *
00078  * Revision 1.41  2002/09/03 06:19:36  robertj
00079  * Normalised the multi-include header prevention ifdef/define symbol.
00080  *
00081  * Revision 1.40  2002/08/15 04:13:21  robertj
00082  * Fixed correct status of isRegistered flag on various reject/errors.
00083  *
00084  * Revision 1.39  2002/08/12 05:38:20  robertj
00085  * Changes to the RAS subsystem to support ability to make requests to client
00086  *   from gkserver without causing bottlenecks and race conditions.
00087  *
00088  * Revision 1.38  2002/08/05 05:17:36  robertj
00089  * Fairly major modifications to support different authentication credentials
00090  *   in ARQ to the logged in ones on RRQ. For both client and server.
00091  * Various other H.235 authentication bugs and anomalies fixed on the way.
00092  *
00093  * Revision 1.37  2002/07/18 03:03:38  robertj
00094  * Fixed bug with continually doing lightweight RRQ if no timeToLive present
00095  *   and it should not be doing it at all, ditto for unsolicited IRR.
00096  *
00097  * Revision 1.36  2002/07/16 11:06:21  robertj
00098  * Added more alternate gatekeeper implementation, thanks Kevin Bouchard
00099  *
00100  * Revision 1.35  2002/06/26 03:47:45  robertj
00101  * Added support for alternate gatekeepers.
00102  *
00103  * Revision 1.34  2002/05/29 00:03:15  robertj
00104  * Fixed unsolicited IRR support in gk client and server,
00105  *   including support for IACK and INAK.
00106  *
00107  * Revision 1.33  2002/05/17 04:12:38  robertj
00108  * Added support for unsolicited IRR transmission in background (heartbeat).
00109  *
00110  * Revision 1.32  2002/03/19 05:17:11  robertj
00111  * Normalised ACF destExtraCallIInfo to be same as other parameters.
00112  * Added ability to get multiple endpoint addresses and tokens from ACF.
00113  *
00114  * Revision 1.31  2001/09/26 07:02:49  robertj
00115  * Added needed mutex for SeparateAuthenticationInARQ mode, thanks Nick Hoath
00116  *
00117  * Revision 1.30  2001/09/18 10:36:54  robertj
00118  * Allowed multiple overlapping requests in RAS channel.
00119  *
00120  * Revision 1.29  2001/09/13 03:21:16  robertj
00121  * Added ability to override authentication credentials for ARQ, thanks Nick Hoath
00122  *
00123  * Revision 1.28  2001/09/12 06:57:58  robertj
00124  * Added support for iNow Access Token from gk, thanks Nick Hoath
00125  *
00126  * Revision 1.27  2001/09/12 06:04:36  robertj
00127  * Added support for sending UUIE's to gk on request, thanks Nick Hoath
00128  *
00129  * Revision 1.26  2001/09/06 02:32:26  robertj
00130  * Added overloaded AdmissionRequest for backward compatibility.
00131  *
00132  * Revision 1.25  2001/08/14 04:26:46  robertj
00133  * Completed the Cisco compatible MD5 authentications, thanks Wolfgang Platzer.
00134  *
00135  * Revision 1.24  2001/08/13 01:27:00  robertj
00136  * Changed GK admission so can return multiple aliases to be used in
00137  *   setup packet, thanks Nick Hoath.
00138  *
00139  * Revision 1.23  2001/08/10 11:03:49  robertj
00140  * Major changes to H.235 support in RAS to support server.
00141  *
00142  * Revision 1.22  2001/08/06 07:44:52  robertj
00143  * Fixed problems with building without SSL
00144  *
00145  * Revision 1.21  2001/08/06 03:18:35  robertj
00146  * Fission of h323.h to h323ep.h & h323con.h, h323.h now just includes files.
00147  * Improved access to H.235 secure RAS functionality.
00148  * Changes to H.323 secure RAS contexts to help use with gk server.
00149  *
00150  * Revision 1.20  2001/08/02 04:30:09  robertj
00151  * Added ability for AdmissionRequest to alter destination alias used in
00152  *   the outgoing call.
00153  *
00154  * Revision 1.19  2001/06/18 06:23:47  robertj
00155  * Split raw H.225 RAS protocol out of gatekeeper client class.
00156  *
00157  * Revision 1.18  2001/04/05 03:39:42  robertj
00158  * Fixed deadlock if tried to do discovery in time to live timeout.
00159  *
00160  * Revision 1.17  2001/03/28 07:12:56  robertj
00161  * Changed RAS thread interlock to allow for what should not happen, the
00162  *   syncpoint being signalled before receiving any packets.
00163  *
00164  * Revision 1.16  2001/03/27 02:18:41  robertj
00165  * Changed to send gk a GRQ if it gives a discoveryRequired error on RRQ.
00166  *
00167  * Revision 1.15  2001/03/17 00:05:52  robertj
00168  * Fixed problems with Gatekeeper RIP handling.
00169  *
00170  * Revision 1.14  2001/02/28 00:20:15  robertj
00171  * Added DiscoverByNameAndAddress() function, thanks Chris Purvis.
00172  *
00173  * Revision 1.13  2001/02/09 05:16:24  robertj
00174  * Added #pragma interface for GNU C++.
00175  *
00176  * Revision 1.12  2000/09/25 06:47:54  robertj
00177  * Removed use of alias if there is no alias present, ie only have transport address.
00178  *
00179  * Revision 1.11  2000/09/01 02:12:54  robertj
00180  * Added ability to select a gatekeeper on LAN via it's identifier name.
00181  *
00182  * Revision 1.10  2000/07/11 19:20:02  robertj
00183  * Fixed problem with endpoint identifiers from some gatekeepers not being a string, just binary info.
00184  *
00185  * Revision 1.9  2000/06/20 03:17:56  robertj
00186  * Added function to get name of gatekeeper, subtle difference from getting identifier.
00187  *
00188  * Revision 1.8  2000/05/18 11:53:33  robertj
00189  * Changes to support doc++ documentation generation.
00190  *
00191  * Revision 1.7  2000/05/09 08:52:36  robertj
00192  * Added support for preGrantedARQ fields on registration.
00193  *
00194  * Revision 1.6  2000/05/02 04:32:24  robertj
00195  * Fixed copyright notice comment.
00196  *
00197  * Revision 1.5  2000/04/11 03:10:40  robertj
00198  * Added ability to reject reason on gatekeeper requests.
00199  * Added ability to get the transport being used to talk to the gatekeeper.
00200  *
00201  * Revision 1.4  2000/04/10 17:37:13  robertj
00202  * Added access function to get the gatekeeper identification string.
00203  *
00204  * Revision 1.3  1999/12/09 21:49:17  robertj
00205  * Added reregister on unregister and time to live reregistration
00206  *
00207  * Revision 1.2  1999/09/14 06:52:54  robertj
00208  * Added better support for multi-homed client hosts.
00209  *
00210  * Revision 1.1  1999/08/31 12:34:18  robertj
00211  * Added gatekeeper support.
00212  *
00213  */
00214 
00215 #ifndef __OPAL_GKCLIENT_H
00216 #define __OPAL_GKCLIENT_H
00217 
00218 
00219 #include "h225ras.h"
00220 #include "h235auth.h"
00221 
00222 #ifdef P_USE_PRAGMA
00223 #pragma interface
00224 #endif
00225 
00226 
00227 class H225_ArrayOf_AliasAddress;
00228 class H225_H323_UU_PDU;
00229 class H225_AlternateGK;
00230 class H225_ArrayOf_AlternateGK;
00231 class H225_ArrayOf_ServiceControlSession;
00232 
00233 
00235 
00238 class H323Gatekeeper : public H225_RAS
00239 {
00240     PCLASSINFO(H323Gatekeeper, H225_RAS);
00241   public:
00246     H323Gatekeeper(
00247       H323EndPoint & endpoint,  
00248       H323Transport * transport       
00249     );
00250 
00253     ~H323Gatekeeper();
00255 
00258     BOOL OnReceiveGatekeeperConfirm(const H225_GatekeeperConfirm & gcf);
00259     BOOL OnReceiveGatekeeperReject(const H225_GatekeeperReject & grj);
00260     BOOL OnReceiveRegistrationConfirm(const H225_RegistrationConfirm & rcf);
00261     BOOL OnReceiveRegistrationReject(const H225_RegistrationReject & rrj);
00262     BOOL OnReceiveUnregistrationRequest(const H225_UnregistrationRequest & urq);
00263     BOOL OnReceiveUnregistrationConfirm(const H225_UnregistrationConfirm & ucf);
00264     BOOL OnReceiveUnregistrationReject(const H225_UnregistrationReject & urj);
00265     BOOL OnReceiveAdmissionConfirm(const H225_AdmissionConfirm & acf);
00266     BOOL OnReceiveAdmissionReject(const H225_AdmissionReject & arj);
00267     BOOL OnReceiveDisengageRequest(const H225_DisengageRequest & drq);
00268     BOOL OnReceiveBandwidthConfirm(const H225_BandwidthConfirm & bcf);
00269     BOOL OnReceiveBandwidthRequest(const H225_BandwidthRequest & brq);
00270     BOOL OnReceiveInfoRequest(const H225_InfoRequest & irq);
00271     BOOL OnReceiveServiceControlIndication(const H225_ServiceControlIndication &);
00272     void OnSendGatekeeperRequest(H225_GatekeeperRequest & grq);
00273     void OnSendAdmissionRequest(H225_AdmissionRequest & arq);
00274     BOOL OnSendFeatureSet(unsigned, H225_FeatureSet & features) const;
00275     void OnReceiveFeatureSet(unsigned, const H225_FeatureSet & features) const;
00277 
00282     BOOL DiscoverAny();
00283 
00288     BOOL DiscoverByName(
00289       const PString & identifier  
00290     );
00291 
00296     BOOL DiscoverByAddress(
00297       const H323TransportAddress & address 
00298     );
00299 
00303     BOOL DiscoverByNameAndAddress(
00304       const PString & identifier,
00305       const H323TransportAddress & address
00306     );
00307 
00310     BOOL RegistrationRequest(
00311       BOOL autoReregister = TRUE  
00312     );
00313 
00316     BOOL UnregistrationRequest(
00317       int reason      
00318     );
00319 
00322     BOOL LocationRequest(
00323       const PString & alias,          
00324       H323TransportAddress & address  
00325     );
00326 
00329     BOOL LocationRequest(
00330       const PStringList & aliases,    
00331       H323TransportAddress & address  
00332     );
00333 
00334     struct AdmissionResponse {
00335       AdmissionResponse();
00336 
00337       unsigned rejectReason;                      
00338 
00339       BOOL gatekeeperRouted;                      
00340       PINDEX endpointCount;                       
00341       H323TransportAddress * transportAddress;    
00342       PBYTEArray * accessTokenData;               
00343 
00344       H225_ArrayOf_AliasAddress * aliasAddresses; 
00345       H225_ArrayOf_AliasAddress * destExtraCallInfo; 
00346     };
00347 
00350     BOOL AdmissionRequest(
00351       H323Connection & connection,      
00352       AdmissionResponse & response,     
00353       BOOL ignorePreGrantedARQ = FALSE  
00354     );
00355 
00358     BOOL DisengageRequest(
00359       const H323Connection & connection,  
00360       unsigned reason                     
00361     );
00362 
00365     BOOL BandwidthRequest(
00366       H323Connection & connection,    
00367       unsigned requestedBandwidth     
00368     );
00369 
00372     void InfoRequestResponse();
00373 
00376     void InfoRequestResponse(
00377       const H323Connection & connection  
00378     );
00379 
00382     void InfoRequestResponse(
00383       const H323Connection & connection,  
00384       const H225_H323_UU_PDU & pdu,       
00385       BOOL sent                           
00386     );
00387 
00390     virtual void OnServiceControlSessions(
00391       const H225_ArrayOf_ServiceControlSession & serviceControl,
00392       H323Connection * connection
00393     );
00395 
00400     BOOL IsDiscoveryComplete() const { return discoveryComplete; }
00401 
00404     BOOL IsRegistered() const { return registrationFailReason == RegistrationSuccessful; }
00405 
00406     enum RegistrationFailReasons {
00407       RegistrationSuccessful,
00408       UnregisteredLocally,
00409       UnregisteredByGatekeeper,
00410       GatekeeperLostRegistration,
00411       InvalidListener,
00412       DuplicateAlias,
00413       SecurityDenied,
00414       TransportError,
00415       NumRegistrationFailReasons,
00416       RegistrationRejectReasonMask = 0x8000
00417     };
00420     RegistrationFailReasons GetRegistrationFailReason() const { return registrationFailReason; }
00421 
00430     PString GetName() const;
00431 
00434     const PString & GetEndpointIdentifier() const { return endpointIdentifier; }
00435 
00440     void SetPassword(
00441       const PString & password,            
00442       const PString & username = PString() 
00443     );
00444 
00445     /*
00446      * Return the call signalling address for the gatekeeper (if present)
00447      */
00448     H323TransportAddress GetGatekeeperRouteAddress() const
00449     { return gkRouteAddress; }
00451         
00452 
00453   protected:
00454     BOOL StartDiscovery(const H323TransportAddress & address);
00455     unsigned SetupGatekeeperRequest(H323RasPDU & request);
00456         
00457     void Connect(const H323TransportAddress & address, const PString & gatekeeperIdentifier);
00458     PDECLARE_NOTIFIER(PThread, H323Gatekeeper, MonitorMain);
00459     PDECLARE_NOTIFIER(PTimer, H323Gatekeeper, TickleMonitor);
00460     void RegistrationTimeToLive();
00461 
00462     void SetInfoRequestRate(
00463       const PTimeInterval & rate
00464     );
00465     void ClearInfoRequestRate();
00466     H225_InfoRequestResponse & BuildInfoRequestResponse(
00467       H323RasPDU & response,
00468       unsigned seqNum
00469     );
00470     BOOL SendUnsolicitedIRR(
00471       H225_InfoRequestResponse & irr,
00472       H323RasPDU & response
00473     );
00474 
00475     void SetAlternates(
00476       const H225_ArrayOf_AlternateGK & alts,
00477       BOOL permanent
00478     );
00479 
00480     virtual BOOL MakeRequest(
00481       Request & request
00482     );
00483     BOOL MakeRequestWithReregister(
00484       Request & request,
00485       unsigned unregisteredTag
00486     );
00487 
00488 
00489     // Gatekeeper registration state variables
00490     BOOL     discoveryComplete;
00491     PString  endpointIdentifier;
00492     RegistrationFailReasons registrationFailReason;
00493 
00494     class AlternateInfo : public PObject {
00495         PCLASSINFO(AlternateInfo, PObject);
00496       public:
00497         AlternateInfo(H225_AlternateGK & alt);
00498         ~AlternateInfo();
00499         Comparison Compare(const PObject & obj);
00500         void PrintOn(ostream & strm) const;
00501 
00502         H323TransportAddress rasAddress;
00503         PString              gatekeeperIdentifier;
00504         unsigned             priority;
00505         enum {
00506           NoRegistrationNeeded,
00507           NeedToRegister,
00508           Register,
00509           IsRegistered,
00510           RegistrationFailed
00511         } registrationState;
00512 
00513       private:
00514         // Disable copy constructor and assignment
00515         AlternateInfo(const AlternateInfo &) { }
00516         AlternateInfo & operator=(const AlternateInfo &) { return *this; }
00517     };
00518     PSortedList<AlternateInfo> alternates;
00519     BOOL               alternatePermanent;
00520     PSemaphore         requestMutex;
00521     H235Authenticators authenticators;
00522 
00523     enum {
00524       RequireARQ,
00525       PregrantARQ,
00526       PreGkRoutedARQ
00527     } pregrantMakeCall, pregrantAnswerCall;
00528     H323TransportAddress gkRouteAddress;
00529 
00530     // Gatekeeper operation variables
00531     BOOL       autoReregister;
00532     BOOL       reregisterNow;
00533     PTimer     timeToLive;
00534     BOOL       requiresDiscovery;
00535     PTimer     infoRequestRate;
00536     BOOL       willRespondToIRR;
00537     PThread  * monitor;
00538     BOOL       monitorStop;
00539     PSyncPoint monitorTickle;
00540 
00541     PDictionary<POrdinalKey, H323ServiceControlSession> serviceControlSessions;
00542 };
00543 
00544 
00545 PLIST(H323GatekeeperList, H323Gatekeeper);
00546 
00547 
00548 
00549 #endif // __OPAL_GKCLIENT_H
00550 
00551 

Generated on Mon Sep 26 15:44:37 2005 for OpenH323 by  doxygen 1.4.4