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

Generated on Thu Jun 15 16:29:25 2006 for OpenH323 by  doxygen 1.4.2