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

Generated on Mon Sep 25 16:19:37 2006 for OPAL by  doxygen 1.4.7