home *** CD-ROM | disk | FTP | other *** search
/ ftp.muug.mb.ca / 2014.06.ftp.muug.mb.ca.tar / ftp.muug.mb.ca / pub / openh323.tar.gz / openh323.tar / openh323 / include / gkclient.h < prev    next >
Text File  |  2003-03-25  |  19KB  |  538 lines
  1. /*
  2.  * gkclient.h
  3.  *
  4.  * Gatekeeper client protocol handler
  5.  *
  6.  * Open H323 Library
  7.  *
  8.  * Copyright (c) 1998-2000 Equivalence Pty. Ltd.
  9.  *
  10.  * The contents of this file are subject to the Mozilla Public License
  11.  * Version 1.0 (the "License"); you may not use this file except in
  12.  * compliance with the License. You may obtain a copy of the License at
  13.  * http://www.mozilla.org/MPL/
  14.  *
  15.  * Software distributed under the License is distributed on an "AS IS"
  16.  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17.  * the License for the specific language governing rights and limitations
  18.  * under the License.
  19.  *
  20.  * The Original Code is Open H323 Library.
  21.  *
  22.  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23.  *
  24.  * Portions of this code were written with the assisance of funding from
  25.  * iFace, Inc. http://www.iface.com
  26.  *
  27.  * Contributor(s): ______________________________________.
  28.  *
  29.  * $Log: gkclient.h,v $
  30.  * Revision 1.51  2003/03/26 00:46:25  robertj
  31.  * Had another go at making H323Transactor being able to be created
  32.  *   without having a listener running.
  33.  *
  34.  * Revision 1.50  2003/02/12 23:59:22  robertj
  35.  * Fixed adding missing endpoint identifer in SETUP packet when gatekeeper
  36.  * routed, pointed out by Stefan Klein
  37.  * Also fixed correct rutrn of gk routing in IRR packet.
  38.  *
  39.  * Revision 1.49  2003/02/07 06:37:42  robertj
  40.  * Changed registration state to an enum so can determine why the RRQ failed.
  41.  *
  42.  * Revision 1.48  2003/01/06 07:09:28  robertj
  43.  * Further fixes for alternate gatekeeper, thanks Kevin Bouchard
  44.  *
  45.  * Revision 1.47  2002/12/23 22:46:38  robertj
  46.  * Changed gatekeeper discovery so an GRJ does not indicate "discovered".
  47.  * Added trace output of alternate gatekeepers list.
  48.  *
  49.  * Revision 1.46  2002/11/28 04:41:44  robertj
  50.  * Added support for RAS ServiceControlIndication command.
  51.  *
  52.  * Revision 1.45  2002/11/27 06:54:52  robertj
  53.  * Added Service Control Session management as per Annex K/H.323 via RAS
  54.  *   only at this stage.
  55.  * Added H.248 ASN and very primitive infrastructure for linking into the
  56.  *   Service Control Session management system.
  57.  * Added basic infrastructure for Annex K/H.323 HTTP transport system.
  58.  * Added Call Credit Service Control to display account balances.
  59.  *
  60.  * Revision 1.44  2002/11/21 07:21:46  robertj
  61.  * Improvements to alternate gatekeeper client code, thanks Kevin Bouchard
  62.  *
  63.  * Revision 1.43  2002/09/18 06:58:29  robertj
  64.  * Fixed setting of IRR frequency, an RCF could reset timer so it did not time
  65.  *   out correctly and send IRR in time causing problems with gatekeeper.
  66.  *
  67.  * Revision 1.42  2002/09/16 01:14:15  robertj
  68.  * Added #define so can select if #pragma interface/implementation is used on
  69.  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  70.  *
  71.  * Revision 1.41  2002/09/03 06:19:36  robertj
  72.  * Normalised the multi-include header prevention ifdef/define symbol.
  73.  *
  74.  * Revision 1.40  2002/08/15 04:13:21  robertj
  75.  * Fixed correct status of isRegistered flag on various reject/errors.
  76.  *
  77.  * Revision 1.39  2002/08/12 05:38:20  robertj
  78.  * Changes to the RAS subsystem to support ability to make requests to client
  79.  *   from gkserver without causing bottlenecks and race conditions.
  80.  *
  81.  * Revision 1.38  2002/08/05 05:17:36  robertj
  82.  * Fairly major modifications to support different authentication credentials
  83.  *   in ARQ to the logged in ones on RRQ. For both client and server.
  84.  * Various other H.235 authentication bugs and anomalies fixed on the way.
  85.  *
  86.  * Revision 1.37  2002/07/18 03:03:38  robertj
  87.  * Fixed bug with continually doing lightweight RRQ if no timeToLive present
  88.  *   and it should not be doing it at all, ditto for unsolicited IRR.
  89.  *
  90.  * Revision 1.36  2002/07/16 11:06:21  robertj
  91.  * Added more alternate gatekeeper implementation, thanks Kevin Bouchard
  92.  *
  93.  * Revision 1.35  2002/06/26 03:47:45  robertj
  94.  * Added support for alternate gatekeepers.
  95.  *
  96.  * Revision 1.34  2002/05/29 00:03:15  robertj
  97.  * Fixed unsolicited IRR support in gk client and server,
  98.  *   including support for IACK and INAK.
  99.  *
  100.  * Revision 1.33  2002/05/17 04:12:38  robertj
  101.  * Added support for unsolicited IRR transmission in background (heartbeat).
  102.  *
  103.  * Revision 1.32  2002/03/19 05:17:11  robertj
  104.  * Normalised ACF destExtraCallIInfo to be same as other parameters.
  105.  * Added ability to get multiple endpoint addresses and tokens from ACF.
  106.  *
  107.  * Revision 1.31  2001/09/26 07:02:49  robertj
  108.  * Added needed mutex for SeparateAuthenticationInARQ mode, thanks Nick Hoath
  109.  *
  110.  * Revision 1.30  2001/09/18 10:36:54  robertj
  111.  * Allowed multiple overlapping requests in RAS channel.
  112.  *
  113.  * Revision 1.29  2001/09/13 03:21:16  robertj
  114.  * Added ability to override authentication credentials for ARQ, thanks Nick Hoath
  115.  *
  116.  * Revision 1.28  2001/09/12 06:57:58  robertj
  117.  * Added support for iNow Access Token from gk, thanks Nick Hoath
  118.  *
  119.  * Revision 1.27  2001/09/12 06:04:36  robertj
  120.  * Added support for sending UUIE's to gk on request, thanks Nick Hoath
  121.  *
  122.  * Revision 1.26  2001/09/06 02:32:26  robertj
  123.  * Added overloaded AdmissionRequest for backward compatibility.
  124.  *
  125.  * Revision 1.25  2001/08/14 04:26:46  robertj
  126.  * Completed the Cisco compatible MD5 authentications, thanks Wolfgang Platzer.
  127.  *
  128.  * Revision 1.24  2001/08/13 01:27:00  robertj
  129.  * Changed GK admission so can return multiple aliases to be used in
  130.  *   setup packet, thanks Nick Hoath.
  131.  *
  132.  * Revision 1.23  2001/08/10 11:03:49  robertj
  133.  * Major changes to H.235 support in RAS to support server.
  134.  *
  135.  * Revision 1.22  2001/08/06 07:44:52  robertj
  136.  * Fixed problems with building without SSL
  137.  *
  138.  * Revision 1.21  2001/08/06 03:18:35  robertj
  139.  * Fission of h323.h to h323ep.h & h323con.h, h323.h now just includes files.
  140.  * Improved access to H.235 secure RAS functionality.
  141.  * Changes to H.323 secure RAS contexts to help use with gk server.
  142.  *
  143.  * Revision 1.20  2001/08/02 04:30:09  robertj
  144.  * Added ability for AdmissionRequest to alter destination alias used in
  145.  *   the outgoing call.
  146.  *
  147.  * Revision 1.19  2001/06/18 06:23:47  robertj
  148.  * Split raw H.225 RAS protocol out of gatekeeper client class.
  149.  *
  150.  * Revision 1.18  2001/04/05 03:39:42  robertj
  151.  * Fixed deadlock if tried to do discovery in time to live timeout.
  152.  *
  153.  * Revision 1.17  2001/03/28 07:12:56  robertj
  154.  * Changed RAS thread interlock to allow for what should not happen, the
  155.  *   syncpoint being signalled before receiving any packets.
  156.  *
  157.  * Revision 1.16  2001/03/27 02:18:41  robertj
  158.  * Changed to send gk a GRQ if it gives a discoveryRequired error on RRQ.
  159.  *
  160.  * Revision 1.15  2001/03/17 00:05:52  robertj
  161.  * Fixed problems with Gatekeeper RIP handling.
  162.  *
  163.  * Revision 1.14  2001/02/28 00:20:15  robertj
  164.  * Added DiscoverByNameAndAddress() function, thanks Chris Purvis.
  165.  *
  166.  * Revision 1.13  2001/02/09 05:16:24  robertj
  167.  * Added #pragma interface for GNU C++.
  168.  *
  169.  * Revision 1.12  2000/09/25 06:47:54  robertj
  170.  * Removed use of alias if there is no alias present, ie only have transport address.
  171.  *
  172.  * Revision 1.11  2000/09/01 02:12:54  robertj
  173.  * Added ability to select a gatekeeper on LAN via it's identifier name.
  174.  *
  175.  * Revision 1.10  2000/07/11 19:20:02  robertj
  176.  * Fixed problem with endpoint identifiers from some gatekeepers not being a string, just binary info.
  177.  *
  178.  * Revision 1.9  2000/06/20 03:17:56  robertj
  179.  * Added function to get name of gatekeeper, subtle difference from getting identifier.
  180.  *
  181.  * Revision 1.8  2000/05/18 11:53:33  robertj
  182.  * Changes to support doc++ documentation generation.
  183.  *
  184.  * Revision 1.7  2000/05/09 08:52:36  robertj
  185.  * Added support for preGrantedARQ fields on registration.
  186.  *
  187.  * Revision 1.6  2000/05/02 04:32:24  robertj
  188.  * Fixed copyright notice comment.
  189.  *
  190.  * Revision 1.5  2000/04/11 03:10:40  robertj
  191.  * Added ability to reject reason on gatekeeper requests.
  192.  * Added ability to get the transport being used to talk to the gatekeeper.
  193.  *
  194.  * Revision 1.4  2000/04/10 17:37:13  robertj
  195.  * Added access function to get the gatekeeper identification string.
  196.  *
  197.  * Revision 1.3  1999/12/09 21:49:17  robertj
  198.  * Added reregister on unregister and time to live reregistration
  199.  *
  200.  * Revision 1.2  1999/09/14 06:52:54  robertj
  201.  * Added better support for multi-homed client hosts.
  202.  *
  203.  * Revision 1.1  1999/08/31 12:34:18  robertj
  204.  * Added gatekeeper support.
  205.  *
  206.  */
  207.  
  208. #ifndef __OPAL_GKCLIENT_H
  209. #define __OPAL_GKCLIENT_H
  210.  
  211.  
  212. #include "h225ras.h"
  213. #include "h235auth.h"
  214.  
  215. #ifdef P_USE_PRAGMA
  216. #pragma interface
  217. #endif
  218.  
  219.  
  220. class H225_ArrayOf_AliasAddress;
  221. class H225_H323_UU_PDU;
  222. class H225_AlternateGK;
  223. class H225_ArrayOf_AlternateGK;
  224. class H225_ArrayOf_ServiceControlSession;
  225.  
  226.  
  227. ///////////////////////////////////////////////////////////////////////////////
  228.  
  229. /**This class embodies the H.225.0 RAS protocol to gatekeepers.
  230.   */
  231. class H323Gatekeeper : public H225_RAS
  232. {
  233.     PCLASSINFO(H323Gatekeeper, H225_RAS);
  234.   public:
  235.   /**@name Construction */
  236.   //@{
  237.     /**Create a new gatekeeper.
  238.      */
  239.     H323Gatekeeper(
  240.       H323EndPoint & endpoint,  /// Endpoint gatekeeper is associated with.
  241.       H323Transport * transport       /// Transport over which gatekeepers communicates.
  242.     );
  243.  
  244.     /**Destroy gatekeeper.
  245.      */
  246.     ~H323Gatekeeper();
  247.   //@}
  248.  
  249.   /**@name Overrides from H225_RAS */
  250.   //@{
  251.     BOOL OnReceiveGatekeeperConfirm(const H225_GatekeeperConfirm & gcf);
  252.     BOOL OnReceiveGatekeeperReject(const H225_GatekeeperReject & grj);
  253.     BOOL OnReceiveRegistrationConfirm(const H225_RegistrationConfirm & rcf);
  254.     BOOL OnReceiveRegistrationReject(const H225_RegistrationReject & rrj);
  255.     BOOL OnReceiveUnregistrationRequest(const H225_UnregistrationRequest & urq);
  256.     BOOL OnReceiveUnregistrationConfirm(const H225_UnregistrationConfirm & ucf);
  257.     BOOL OnReceiveUnregistrationReject(const H225_UnregistrationReject & urj);
  258.     BOOL OnReceiveAdmissionConfirm(const H225_AdmissionConfirm & acf);
  259.     BOOL OnReceiveAdmissionReject(const H225_AdmissionReject & arj);
  260.     BOOL OnReceiveDisengageRequest(const H225_DisengageRequest & drq);
  261.     BOOL OnReceiveBandwidthConfirm(const H225_BandwidthConfirm & bcf);
  262.     BOOL OnReceiveBandwidthRequest(const H225_BandwidthRequest & brq);
  263.     BOOL OnReceiveInfoRequest(const H225_InfoRequest & irq);
  264.     BOOL OnReceiveServiceControlIndication(const H225_ServiceControlIndication &);
  265.     void OnSendGatekeeperRequest(H225_GatekeeperRequest & grq);
  266.     void OnSendAdmissionRequest(H225_AdmissionRequest & arq);
  267.   //@}
  268.  
  269.   /**@name Protocol operations */
  270.   //@{
  271.     /**Discover a gatekeeper on the local network.
  272.      */
  273.     BOOL DiscoverAny();
  274.  
  275.     /**Discover a gatekeeper on the local network.
  276.        If the identifier string is empty then the first gatekeeper to respond
  277.        to a broadcast is used.
  278.      */
  279.     BOOL DiscoverByName(
  280.       const PString & identifier  /// Gatekeeper identifier to find
  281.     );
  282.  
  283.     /**Discover a gatekeeper on the local network.
  284.        If the address string is empty then the first gatekeeper to respond
  285.        to a broadcast is used.
  286.      */
  287.     BOOL DiscoverByAddress(
  288.       const H323TransportAddress & address /// Address of gatekeeper.
  289.     );
  290.  
  291.     /**Discover a gatekeeper on the local network.
  292.        Combination of DiscoverByName() and DiscoverByAddress().
  293.      */
  294.     BOOL DiscoverByNameAndAddress(
  295.       const PString & identifier,
  296.       const H323TransportAddress & address
  297.     );
  298.  
  299.     /**Register with gatekeeper.
  300.      */
  301.     BOOL RegistrationRequest(
  302.       BOOL autoReregister = TRUE  /// Automatic register on unregister
  303.     );
  304.  
  305.     /**Unregister with gatekeeper.
  306.      */
  307.     BOOL UnregistrationRequest(
  308.       int reason      /// Reason for unregistration
  309.     );
  310.  
  311.     /**Location request to gatekeeper.
  312.      */
  313.     BOOL LocationRequest(
  314.       const PString & alias,          /// Alias name we wish to find.
  315.       H323TransportAddress & address  /// Resultant transport address.
  316.     );
  317.  
  318.     /**Location request to gatekeeper.
  319.      */
  320.     BOOL LocationRequest(
  321.       const PStringList & aliases,    /// Alias names we wish to find.
  322.       H323TransportAddress & address  /// Resultant transport address.
  323.     );
  324.  
  325.     struct AdmissionResponse {
  326.       AdmissionResponse();
  327.  
  328.       unsigned rejectReason;                      /// Reject reason if returns FALSE
  329.  
  330.       BOOL gatekeeperRouted;                      /// Flag for call is through gk
  331.       PINDEX endpointCount;                       /// Number of endpoints that can be returned
  332.       H323TransportAddress * transportAddress;    /// Transport address or remote endpoint.
  333.       PBYTEArray * accessTokenData;               /// iNow Gatekeeper Access Token data
  334.  
  335.       H225_ArrayOf_AliasAddress * aliasAddresses; /// DestinationInfo to use in SETUP if not empty
  336.       H225_ArrayOf_AliasAddress * destExtraCallInfo; /// DestinationInfo to use in SETUP if not empty
  337.     };
  338.  
  339.     /**Admission request to gatekeeper.
  340.      */
  341.     BOOL AdmissionRequest(
  342.       H323Connection & connection,      /// Connection we wish to change.
  343.       AdmissionResponse & response,     /// Response parameters to ARQ
  344.       BOOL ignorePreGrantedARQ = FALSE  /// Flag to force ARQ to be sent
  345.     );
  346.  
  347.     /**Disengage request to gatekeeper.
  348.      */
  349.     BOOL DisengageRequest(
  350.       const H323Connection & connection,  /// Connection we wish admitted.
  351.       unsigned reason                     /// Reason code for disengage
  352.     );
  353.  
  354.     /**Bandwidth request to gatekeeper.
  355.      */
  356.     BOOL BandwidthRequest(
  357.       H323Connection & connection,    /// Connection we wish to change.
  358.       unsigned requestedBandwidth     /// New bandwidth wanted in 0.1kbps
  359.     );
  360.  
  361.     /**Send an unsolicited info response to the gatekeeper.
  362.      */
  363.     void InfoRequestResponse();
  364.  
  365.     /**Send an unsolicited info response to the gatekeeper.
  366.      */
  367.     void InfoRequestResponse(
  368.       const H323Connection & connection  /// Connection to send info about
  369.     );
  370.  
  371.     /**Send an unsolicited info response to the gatekeeper.
  372.      */
  373.     void InfoRequestResponse(
  374.       const H323Connection & connection,  /// Connection to send info about
  375.       const H225_H323_UU_PDU & pdu,       /// PDU that was sent or received
  376.       BOOL sent                           /// Flag for PDU was sent or received
  377.     );
  378.  
  379.     /**Handle incoming service control session information.
  380.      */
  381.     virtual void OnServiceControlSessions(
  382.       const H225_ArrayOf_ServiceControlSession & serviceControl,
  383.       H323Connection * connection
  384.     );
  385.   //@}
  386.  
  387.   /**@name Member variable access */
  388.   //@{
  389.     /**Determine if the endpoint has discovered the gatekeeper.
  390.       */
  391.     BOOL IsDiscoveryComplete() const { return discoveryComplete; }
  392.  
  393.     /**Determine if the endpoint is registered with the gatekeeper.
  394.       */
  395.     BOOL IsRegistered() const { return registrationFailReason == RegistrationSuccessful; }
  396.  
  397.     enum RegistrationFailReasons {
  398.       RegistrationSuccessful,
  399.       UnregisteredLocally,
  400.       UnregisteredByGatekeeper,
  401.       GatekeeperLostRegistration,
  402.       InvalidListener,
  403.       DuplicateAlias,
  404.       SecurityDenied,
  405.       TransportError,
  406.       NumRegistrationFailReasons,
  407.       RegistrationRejectReasonMask = 0x8000
  408.     };
  409.     /**Get the registration fail reason.
  410.      */
  411.     RegistrationFailReasons GetRegistrationFailReason() const { return registrationFailReason; }
  412.  
  413.     /**Get the gatekeeper name.
  414.        The gets the name of the gatekeeper. It will be of the form id@address
  415.        where id is the gatekeeperIdentifier and address is the transport
  416.        address used. If the gatekeeperIdentifier is empty the '@' is not
  417.        included and only the transport is shown. The transport is minimised
  418.        also, with the type removed if IP is used and the :port removed if the
  419.        default port is used.
  420.       */
  421.     PString GetName() const;
  422.  
  423.     /** Get the endpoint identifier
  424.       */
  425.     const PString & GetEndpointIdentifier() const { return endpointIdentifier; }
  426.  
  427.     /**Set the H.235 password in the gatekeeper.
  428.        If no username is present then it will default to the endpoint local
  429.        user name (ie first alias).
  430.       */
  431.     void SetPassword(
  432.       const PString & password,            /// New password
  433.       const PString & username = PString() /// Username for password
  434.     );
  435.   //@}
  436.     
  437.  
  438.   protected:
  439.     BOOL StartDiscovery(const H323TransportAddress & address);
  440.     unsigned SetupGatekeeperRequest(H323RasPDU & request);
  441.     
  442.     void Connect(const H323TransportAddress & address, const PString & gatekeeperIdentifier);
  443.     PDECLARE_NOTIFIER(PThread, H323Gatekeeper, MonitorMain);
  444.     PDECLARE_NOTIFIER(PTimer, H323Gatekeeper, TickleMonitor);
  445.     void RegistrationTimeToLive();
  446.  
  447.     void SetInfoRequestRate(
  448.       const PTimeInterval & rate
  449.     );
  450.     void ClearInfoRequestRate();
  451.     H225_InfoRequestResponse & BuildInfoRequestResponse(
  452.       H323RasPDU & response,
  453.       unsigned seqNum
  454.     );
  455.     BOOL SendUnsolicitedIRR(
  456.       H225_InfoRequestResponse & irr,
  457.       H323RasPDU & response
  458.     );
  459.  
  460.     void SetAlternates(
  461.       const H225_ArrayOf_AlternateGK & alts,
  462.       BOOL permanent
  463.     );
  464.  
  465.     virtual BOOL MakeRequest(
  466.       Request & request
  467.     );
  468.     BOOL MakeRequestWithReregister(
  469.       Request & request,
  470.       unsigned unregisteredTag
  471.     );
  472.  
  473.  
  474.     // Gatekeeper registration state variables
  475.     BOOL     discoveryComplete;
  476.     PString  endpointIdentifier;
  477.     RegistrationFailReasons registrationFailReason;
  478.  
  479.     class AlternateInfo : public PObject {
  480.         PCLASSINFO(AlternateInfo, PObject);
  481.       public:
  482.         AlternateInfo(H225_AlternateGK & alt);
  483.     ~AlternateInfo();
  484.         Comparison Compare(const PObject & obj);
  485.         void PrintOn(ostream & strm) const;
  486.  
  487.         H323TransportAddress rasAddress;
  488.         PString              gatekeeperIdentifier;
  489.         unsigned             priority;
  490.         enum {
  491.           NoRegistrationNeeded,
  492.           NeedToRegister,
  493.           Register,
  494.           IsRegistered,
  495.           RegistrationFailed
  496.         } registrationState;
  497.  
  498.       private:
  499.         // Disable copy constructor and assignment
  500.         AlternateInfo(const AlternateInfo &) { }
  501.         AlternateInfo & operator=(const AlternateInfo &) { return *this; }
  502.     };
  503.     PSortedList<AlternateInfo> alternates;
  504.     BOOL               alternatePermanent;
  505.     PSemaphore         requestMutex;
  506.     H235Authenticators authenticators;
  507.  
  508.     enum {
  509.       RequireARQ,
  510.       PregrantARQ,
  511.       PreGkRoutedARQ
  512.     } pregrantMakeCall, pregrantAnswerCall;
  513.     H323TransportAddress gkRouteAddress;
  514.  
  515.     // Gatekeeper operation variables
  516.     BOOL       autoReregister;
  517.     BOOL       reregisterNow;
  518.     PTimer     timeToLive;
  519.     BOOL       requiresDiscovery;
  520.     PTimer     infoRequestRate;
  521.     BOOL       willRespondToIRR;
  522.     PThread  * monitor;
  523.     BOOL       monitorStop;
  524.     PSyncPoint monitorTickle;
  525.  
  526.     PDictionary<POrdinalKey, H323ServiceControlSession> serviceControlSessions;
  527. };
  528.  
  529.  
  530. PLIST(H323GatekeeperList, H323Gatekeeper);
  531.  
  532.  
  533.  
  534. #endif // __OPAL_GKCLIENT_H
  535.  
  536.  
  537. /////////////////////////////////////////////////////////////////////////////
  538.