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

Generated on Wed Feb 6 09:02:21 2008 for OpenH323 by  doxygen 1.5.4