include/transports.h

   1 /*
   2  * transports.h
   3  *
   4  * H.323 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  * Vovida Networks, Inc. http://www.vovida.com.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.51  2006/07/05 04:37:44  csoutheren
  31  * Applied 1488904 - SetPromiscuous(AcceptFromLastReceivedOnly) for T.38
  32  * Thanks to Vyacheslav Frolov
  33  *
  34  * Revision 1.50  2006/06/23 03:21:03  shorne
  35  * Added unsolicited Information support
  36  *
  37  * Revision 1.49  2006/01/20 00:32:24  csoutheren
  38  * First check-in of signalling aggregation code - incomplete and disabled by default
  39  *
  40  * Revision 1.48  2005/11/30 13:05:01  csoutheren
  41  * Changed tags for Doxygen
  42  *
  43  * Revision 1.47  2005/11/21 21:07:41  shorne
  44  * Added GnuGK Nat support
  45  *
  46  * Revision 1.46  2005/01/16 20:39:43  csoutheren
  47  * Fixed problem with IPv6 INADDR_ANY
  48  *
  49  * Revision 1.45  2004/08/24 08:11:25  csoutheren
  50  * Added initial support for receiving broadcasts on Linux
  51  *
  52  * Revision 1.44  2004/05/13 02:26:13  dereksmithies
  53  * Fixes so make docs does not generate warning messages about brackets.
  54  *
  55  * Revision 1.43  2003/12/29 13:28:45  dominance
  56  * fixed docbook syntax trying to generate LaTeX formula with ip$10.x.x.x.
  57  *
  58  * Revision 1.42  2003/04/10 09:44:55  robertj
  59  * Added associated transport to new GetInterfaceAddresses() function so
  60  *   interfaces can be ordered according to active transport links. Improves
  61  *   interoperability.
  62  * Replaced old listener GetTransportPDU() with GetInterfaceAddresses()
  63  *   and H323SetTransportAddresses() functions.
  64  *
  65  * Revision 1.41  2003/04/10 01:03:25  craigs
  66  * Added functions to access to lists of interfaces
  67  *
  68  * Revision 1.40  2003/03/21 05:24:02  robertj
  69  * Added setting of remote port in UDP transport constructor.
  70  *
  71  * Revision 1.39  2003/02/06 04:29:23  robertj
  72  * Added more support for adding things to H323TransportAddressArrays
  73  *
  74  * Revision 1.38  2002/11/21 06:39:56  robertj
  75  * Changed promiscuous mode to be three way. Fixes race condition in gkserver
  76  *   which can cause crashes or more PDUs to be sent to the wrong place.
  77  *
  78  * Revision 1.37  2002/11/10 08:10:43  robertj
  79  * Moved constants for "well known" ports to better place (OPAL change).
  80  *
  81  * Revision 1.36  2002/09/16 01:14:15  robertj
  82  * Added #define so can select if #pragma interface/implementation is used on
  83  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  84  *
  85  * Revision 1.35  2002/07/22 09:40:15  robertj
  86  * Added ability to automatically convert string arrays, lists sorted lists
  87  *   directly to H323TransportAddressArray.
  88  *
  89  * Revision 1.34  2002/07/02 10:02:29  robertj
  90  * Added H323TransportAddress::GetIpAddress() so don't have to provide port
  91  *   when you don't need it as in GetIpAndPort(),.
  92  *
  93  * Revision 1.33  2002/06/28 03:34:25  robertj
  94  * Fixed issues with address translation on gatekeeper RAS channel.
  95  *
  96  * Revision 1.32  2002/06/12 03:51:59  robertj
  97  * Added function to compare two transport addresses in a more intelligent
  98  *   way that strict string comparison. Takes into account wildcarding.
  99  *
 100  * Revision 1.31  2002/02/11 04:20:25  robertj
 101  * Fixed documentation errors, thanks Horacio J. Peña
 102  *
 103  * Revision 1.30  2002/02/05 23:29:23  robertj
 104  * Changed default for H.323 listener to reuse addresses.
 105  *
 106  * Revision 1.29  2001/12/22 01:48:12  robertj
 107  * Added ability to use local and remote port from transport channel as well
 108  *   as explicit port in H.245 address PDU setting routine.
 109  * Added PrintOn() to listener and transport for tracing purposes.
 110  *
 111  * Revision 1.28  2001/07/17 04:44:29  robertj
 112  * Partial implementation of T.120 and T.38 logical channels.
 113  *
 114  * Revision 1.27  2001/06/25 02:30:46  robertj
 115  * Allowed TCP listener socket to be opened in non-exclusive mode
 116  *   (ie SO_REUSEADDR) to avoid daemon restart problems.
 117  *
 118  * Revision 1.26  2001/06/22 00:14:14  robertj
 119  * Added ConnectTo() function to conencto specific address.
 120  * Added promiscuous mode for UDP channel.
 121  *
 122  * Revision 1.25  2001/05/17 06:37:02  robertj
 123  * Added multicast gatekeeper discovery support.
 124  *
 125  * Revision 1.24  2001/04/09 08:43:39  robertj
 126  * Added ability to get transport address for a listener.
 127  *
 128  * Revision 1.23  2001/03/02 06:59:57  robertj
 129  * Enhanced the globally unique identifier class.
 130  *
 131  * Revision 1.22  2001/02/09 05:16:24  robertj
 132  * Added #pragma interface for GNU C++.
 133  *
 134  * Revision 1.21  2001/01/23 05:08:04  robertj
 135  * Fixed bug when trying to clear call while waiting on H.245 channel connect, thanks Yura Aksyonov.
 136  *
 137  * Revision 1.20  2000/10/20 06:18:58  robertj
 138  * Fixed very small race condition on creating new connectionon incoming call.
 139  * Fixed memory/socket leak if do TCP connect and don't send valid setup PDU.
 140  *
 141  * Revision 1.19  2000/10/04 05:59:09  robertj
 142  * Minor reorganisation of the H.245 secondary channel start up to make it simpler
 143  *    to override its behaviour.
 144  *
 145  * Revision 1.18  2000/09/25 12:59:16  robertj
 146  * Added StartListener() function that takes a H323TransportAddress to start
 147  *     listeners bound to specific interfaces.
 148  *
 149  * Revision 1.17  2000/09/22 01:35:03  robertj
 150  * Added support for handling LID's that only do symmetric codecs.
 151  *
 152  * Revision 1.16  2000/06/07 05:47:55  robertj
 153  * Added call forwarding.
 154  *
 155  * Revision 1.15  2000/05/22 05:21:36  robertj
 156  * Fixed race condition where controlChannel variable could be used before set.
 157  *
 158  * Revision 1.14  2000/05/18 11:53:34  robertj
 159  * Changes to support doc++ documentation generation.
 160  *
 161  * Revision 1.13  2000/05/08 14:07:26  robertj
 162  * Improved the provision and detection of calling and caller numbers, aliases and hostnames.
 163  *
 164  * Revision 1.12  2000/05/02 04:32:25  robertj
 165  * Fixed copyright notice comment.
 166  *
 167  * Revision 1.11  1999/11/06 05:37:44  robertj
 168  * Complete rewrite of termination of connection to avoid numerous race conditions.
 169  *
 170  * Revision 1.10  1999/10/16 03:47:57  robertj
 171  * Fixed termination of gatekeeper RAS thread problem
 172  *
 173  * Revision 1.9  1999/10/10 08:59:47  robertj
 174  * Fixed race condition in connection shutdown
 175  *
 176  * Revision 1.8  1999/09/14 06:52:54  robertj
 177  * Added better support for multi-homed client hosts.
 178  *
 179  * Revision 1.7  1999/09/10 09:43:59  robertj
 180  * Removed attempt at determining local interface for gatekeeper, so still has problem on multi-homed hosts.
 181  *
 182  * Revision 1.6  1999/08/31 12:34:18  robertj
 183  * Added gatekeeper support.
 184  *
 185  * Revision 1.5  1999/08/25 05:14:21  robertj
 186  * Fixed problem with calling modal dialog from a background thread.
 187  *
 188  * Revision 1.4  1999/07/14 06:06:14  robertj
 189  * Fixed termination problems (race conditions) with deleting connection object.
 190  *
 191  * Revision 1.3  1999/07/09 06:09:49  robertj
 192  * Major implementation. An ENORMOUS amount of stuff added everywhere.
 193  *
 194  * Revision 1.2  1999/06/13 12:41:14  robertj
 195  * Implement logical channel transmitter.
 196  * Fixed H245 connect on receiving call.
 197  *
 198  * Revision 1.1  1999/06/09 05:26:20  robertj
 199  * Major restructuring of classes.
 200  *
 201  */
 202
 203 #ifndef __TRANSPORTS_H
 204 #define __TRANSPORTS_H
 205
 206 #ifdef P_USE_PRAGMA
 207 #pragma interface
 208 #endif
 209
 210
 211 #include <ptlib/sockets.h>
 212
 213
 214 class H225_Setup_UUIE;
 215 class H225_TransportAddress;
 216 class H225_ArrayOf_TransportAddress;
 217 class H225_TransportAddress_ipAddress;
 218
 219 class H245_TransportAddress;
 220
 221 class H323SignalPDU;
 222 class H323RasPDU;
 223 class H323EndPoint;
 224 class H323Connection;
 225 class H323Listener;
 226 class H323Transport;
 227 class H323Gatekeeper;
 228
 229
 230
 231 ///////////////////////////////////////////////////////////////////////////////
 232
 233 /**String representation of a transport address.
 234  */
 235
 236 class H323TransportAddress : public PString
 237 {
 238   PCLASSINFO(H323TransportAddress, PString);
 239   public:
 240     H323TransportAddress() { }
 241     H323TransportAddress(const char *);
 242     H323TransportAddress(const PString &);
 243     H323TransportAddress(const H225_TransportAddress &);
 244     H323TransportAddress(const H245_TransportAddress &);
 245     H323TransportAddress(const PIPSocket::Address &, WORD);
 246
 247     BOOL SetPDU(H225_TransportAddress & pdu) const;
 248     BOOL SetPDU(H245_TransportAddress & pdu) const;
 249
 250     /**Determine if the two transport addresses are equivalent.
 251       */
 252     BOOL IsEquivalent(
 253       const H323TransportAddress & address
 254     );
 255
 256     /**Extract the ip address from transport address.
 257        Returns FALSE, if the address is not an IP transport address.
 258       */
 259     BOOL GetIpAddress(
 260       PIPSocket::Address & ip
 261     ) const;
 262
 263     /**Extract the ip address and port number from transport address.
 264        Returns FALSE, if the address is not an IP transport address.
 265       */
 266     BOOL GetIpAndPort(
 267       PIPSocket::Address & ip,
 268       WORD & port,
 269       const char * proto = "tcp"
 270     ) const;
 271
 272     /**Translate the transport address to a more human readable form.
 273        Returns the hostname if using IP.
 274       */
 275     PString GetHostName() const;
 276
 277     /**Create a listener based on this transport address.
 278
 279        For example an address of "#ip$10.0.0.1:1720#" would create a TCP
 280        listening socket that would be bound to the specific interface
 281        10.0.0.1 and listens on port 1720. Note that the address
 282        "#ip$*:1720#" can be used to bind to INADDR_ANY.
 283
 284        Also note that if the address has a trailing '+' character then the
 285        socket will be bound using the REUSEADDR option.
 286       */
 287     H323Listener * CreateListener(
 288       H323EndPoint & endpoint   ///<  Endpoint object for transport creation.
 289     ) const;
 290
 291     /**Create a listener compatible for this address type.
 292        This is similar to CreateListener() but does not use the TSAP specified
 293        in the H323Transport. For example an address of "#ip$10.0.0.1:1720#"
 294        would create a TCP listening socket that would be bound to the specific
 295        interface 10.0.0.1 but listens on a random OS allocated port number.
 296       */
 297     H323Listener * CreateCompatibleListener(
 298       H323EndPoint & endpoint   ///<  Endpoint object for transport creation.
 299     ) const;
 300
 301     /**Create a transport suitable for this address type.
 302       */
 303     H323Transport * CreateTransport(
 304       H323EndPoint & endpoint   ///<  Endpoint object for transport creation.
 305     ) const;
 306
 307   protected:
 308     void Validate();
 309 };
 310
 311
 312 PDECLARE_ARRAY(H323TransportAddressArray, H323TransportAddress)
 313 #ifdef DOC_PLUS_PLUS
 314 {
 315 #endif
 316   public:
 317     H323TransportAddressArray(
 318       const H323TransportAddress & address
 319     ) { AppendAddress(address); }
 320     H323TransportAddressArray(
 321       const H225_ArrayOf_TransportAddress & addresses
 322     );
 323     H323TransportAddressArray(
 324       const PStringArray & array
 325     ) { AppendStringCollection(array); }
 326     H323TransportAddressArray(
 327       const PStringList & list
 328     ) { AppendStringCollection(list); }
 329     H323TransportAddressArray(
 330       const PSortedStringList & list
 331     ) { AppendStringCollection(list); }
 332
 333     void AppendString(
 334       const char * address
 335     );
 336     void AppendString(
 337       const PString & address
 338     );
 339     void AppendAddress(
 340       const H323TransportAddress & address
 341     );
 342
 343   protected:
 344     void AppendStringCollection(
 345       const PCollection & coll
 346     );
 347 };
 348
 349
 350 /**This class describes a "listener" on a transport protocol.
 351    A "listener" is an object that listens for incoming connections on the
 352    particular transport. It is executed as a separate thread.
 353
 354    The Main() function is used to handle incoming H.323 connections and
 355    dispatch them in new threads based on the actual H323Transport class. This
 356    is defined in the descendent class that knows what the low level transport
 357    is, eg H323ListenerIP for the TCP/IP protocol.
 358
 359    An application may create a descendent off this class and override
 360    functions as required for operating the channel protocol.
 361  */
 362 class H323Listener : public PThread
 363 {
 364   PCLASSINFO(H323Listener, PThread);
 365
 366   public:
 367   /**@name Construction */
 368   //@{
 369     /**Create a new listener.
 370      */
 371     H323Listener(
 372       H323EndPoint & endpoint      ///<  Endpoint instance for channel
 373     );
 374   //@}
 375
 376   /**@name Overrides from PObject */
 377   //@{
 378     virtual void PrintOn(
 379       ostream & strm
 380     ) const;
 381   //@}
 382
 383   /**@name Operations */
 384   //@{
 385     /** Open the listener.
 386       */
 387     virtual BOOL Open() = 0;
 388
 389     /**Stop the listener thread and no longer accept incoming connections.
 390      */
 391     virtual BOOL Close() = 0;
 392
 393     /**Accept a new incoming transport.
 394       */
 395     virtual H323Transport * Accept(
 396       const PTimeInterval & timeout  ///<  Time to wait for incoming connection
 397     ) = 0;
 398
 399     /**Get the local transport address on which this listener may be accessed.
 400       */
 401     virtual H323TransportAddress GetTransportAddress() const = 0;
 402
 403     /**Set up a transport address PDU for bidirectional logical channels.
 404       */
 405     virtual BOOL SetUpTransportPDU(
 406       H245_TransportAddress & pdu,         ///<  Transport addresses listening on
 407       const H323Transport & associatedTransport ///<  Associated transport for precendence and translation
 408     ) = 0;
 409   //@}
 410
 411   protected:
 412     H323EndPoint & endpoint;  /// Endpoint that owns the listener.
 413 };
 414
 415
 416 PLIST(H323ListenerList, H323Listener);
 417
 418
 419 /** Return a list of transport addresses corresponding to a listener list
 420   */
 421 H323TransportAddressArray H323GetInterfaceAddresses(
 422   const H323ListenerList & listeners, ///<  List of listeners
 423   BOOL excludeLocalHost = TRUE,       ///<  Flag to exclude 127.0.0.1
 424   H323Transport * associatedTransport = NULL
 425                           ///<  Associated transport for precedence and translation
 426 );
 427
 428 H323TransportAddressArray H323GetInterfaceAddresses(
 429   const H323TransportAddress & addr,  ///<  Possible INADDR_ANY address
 430   BOOL excludeLocalHost = TRUE,       ///<  Flag to exclude 127.0.0.1
 431   H323Transport * associatedTransport = NULL
 432                           ///<  Associated transport for precedence and translation
 433 );
 434
 435 /**Set the PDU field for the list of transport addresses
 436   */
 437 void H323SetTransportAddresses(
 438   const H323Transport & associatedTransport,   ///<  Transport for NAT address translation
 439   const H323TransportAddressArray & addresses, ///<  Addresses to set
 440   H225_ArrayOf_TransportAddress & pdu          ///<  List of PDU transport addresses
 441 );
 442
 443
 444 /**This class describes a I/O transport protocol..
 445    A "transport" is an object that listens for incoming connections on the
 446    particular transport.
 447  */
 448 class H323Transport : public PIndirectChannel
 449 {
 450   PCLASSINFO(H323Transport, PIndirectChannel);
 451
 452   public:
 453   /**@name Construction */
 454   //@{
 455     /**Create a new transport channel.
 456      */
 457     H323Transport(H323EndPoint & endpoint);
 458     ~H323Transport();
 459   //@}
 460
 461   /**@name Overrides from PObject */
 462   //@{
 463     virtual void PrintOn(
 464       ostream & strm
 465     ) const;
 466   //@}
 467
 468   /**@name Operations */
 469   //@{
 470     /**Get the transport address of the local endpoint.
 471       */
 472     virtual H323TransportAddress GetLocalAddress() const = 0;
 473
 474     /**Get the transport address of the remote endpoint.
 475       */
 476     virtual H323TransportAddress GetRemoteAddress() const = 0;
 477
 478     /**Set remote address to connect to.
 479        Note that this does not necessarily initiate a transport level
 480        connection, but only indicates where to connect to. The actual
 481        connection is made by the Connect() function.
 482       */
 483     virtual BOOL SetRemoteAddress(
 484       const H323TransportAddress & address
 485     ) = 0;
 486
 487     /**Connect to the remote address.
 488       */
 489     virtual BOOL Connect() = 0;
 490
 491     /**Connect to the specified address.
 492       */
 493     BOOL ConnectTo(
 494       const H323TransportAddress & address
 495     ) { return SetRemoteAddress(address) && Connect(); }
 496
 497     /**Close the channel.
 498       */
 499     virtual BOOL Close();
 500
 501     /**Check that the transport address PDU is compatible with transport.
 502       */
 503     virtual BOOL IsCompatibleTransport(
 504       const H225_TransportAddress & pdu
 505     ) const;
 506
 507     /**Set up a transport address PDU for RAS channel.
 508       */
 509     virtual void SetUpTransportPDU(
 510       H225_TransportAddress & pdu,
 511       BOOL localTsap
 512     ) const;
 513
 514     enum {
 515       UseLocalTSAP = 0x10001,
 516       UseRemoteTSAP
 517     };
 518
 519     /**Set up a transport address PDU for logical channel.
 520        If tsap is UseLocalTSAP or UseRemoteTSAP then the local or remote port
 521        of the transport is used, otherwise the explicit port number is used.
 522       */
 523     virtual void SetUpTransportPDU(
 524       H245_TransportAddress & pdu,
 525       unsigned tsap
 526     ) const;
 527
 528     /// Promiscious modes for transport
 529     enum PromisciousModes {
 530       AcceptFromRemoteOnly,
 531       AcceptFromAnyAutoSet,
 532       AcceptFromAny,
 533       AcceptFromLastReceivedOnly,
 534       NumPromisciousModes
 535     };
 536
 537     /**Set read to promiscuous mode.
 538        Normally only reads from the specifed remote address are accepted. This
 539        flag allows packets to be accepted from any remote, provided the
 540        underlying protocol can do so. For example TCP will do nothing.
 541
 542        The Read() call may optionally set the remote address automatically to
 543        whatever the sender host of the last received message was.
 544
 545        Default behaviour does nothing.
 546       */
 547     virtual void SetPromiscuous(
 548       PromisciousModes promiscuous
 549     );
 550
 551     /**Get the transport address of the last received PDU.
 552
 553        Default behaviour returns GetRemoteAddress().
 554       */
 555     virtual H323TransportAddress GetLastReceivedAddress() const;
 556
 557     /**Read a protocol data unit from the transport.
 558        This will read using the transports mechanism for PDU boundaries, for
 559        example UDP is a single Read() call, while for TCP there is a TPKT
 560        header that indicates the size of the PDU.
 561       */
 562     virtual BOOL ReadPDU(
 563       PBYTEArray & pdu   ///<  PDU read from transport
 564     ) = 0;
 565
 566     /**Extract a protocol data unit from the transport
 567        This is used by the aggregator to deblock the incoming data stream
 568        into valid PDUs.
 569       */
 570     virtual BOOL ExtractPDU(
 571       const PBYTEArray & pdu,
 572       PINDEX & len
 573     ) = 0;
 574
 575     /**Write a protocol data unit from the transport.
 576        This will write using the transports mechanism for PDU boundaries, for
 577        example UDP is a single Write() call, while for TCP there is a TPKT
 578        header that indicates the size of the PDU.
 579       */
 580     virtual BOOL WritePDU(
 581       const PBYTEArray & pdu  ///<  PDU to write
 582     ) = 0;
 583   //@}
 584
 585   /**@name Signalling Channel */
 586   //@{
 587         /** Handle the PDU Reading for the first connection object
 588           */
 589     BOOL HandleSignallingSocket(H323SignalPDU & pdu);
 590
 591     /**Wait for first PDU and find/create connection object.
 592        If returns FALSE, then the transport is deleted by the calling thread.
 593       */
 594     BOOL HandleFirstSignallingChannelPDU();
 595   //@}
 596
 597   /**@name Control Channel */
 598   //@{
 599     /**Begin the opening of a control channel.
 600        This sets up the channel so that the remote endpoint can connect back
 601        to this endpoint. This would be called on the signalling channel
 602        instance of a H323Transport.
 603       */
 604     virtual H323Transport * CreateControlChannel(
 605       H323Connection & connection
 606     );
 607
 608     /**Finish the opening of a control channel.
 609        This waits for the connect backfrom the remote endpoint, completing the
 610        control channel open sequence.
 611       */
 612     virtual BOOL AcceptControlChannel(
 613       H323Connection & connection
 614     );
 615
 616     /**Connect the control channel.
 617       */
 618     virtual void StartControlChannel(
 619       H323Connection & connection
 620     );
 621   //@}
 622
 623   /**@name RAS Channel */
 624   //@{
 625     /**Discover a Gatekeeper on the network.
 626        This locates a gatekeeper on the network and associates this transport
 627        object with packet exchange with that gatekeeper.
 628       */
 629     virtual BOOL DiscoverGatekeeper(
 630       H323Gatekeeper & gk,                  ///<  Gatekeeper to set on discovery.
 631       H323RasPDU & pdu,                     ///<  GatekeeperRequest PDU
 632       const H323TransportAddress & address  ///<  Address of gatekeeper (if present)
 633     );
 634   //@}
 635
 636
 637   /**@name Member variable access */
 638   //@{
 639     /**Get the associated endpoint to this transport.
 640       */
 641     H323EndPoint & GetEndPoint() const { return endpoint; }
 642
 643     /**Attach a thread to the transport.
 644       */
 645     void AttachThread(
 646       PThread * thread
 647     );
 648
 649     /**Wait for associated thread to terminate.
 650       */
 651     void CleanUpOnTermination();
 652   //@}
 653
 654   protected:
 655     H323EndPoint & endpoint;    /// Endpoint that owns the listener.
 656     PThread      * thread;      /// Thread handling the transport
 657     BOOL canGetInterface;
 658 };
 659
 660
 661
 662 ///////////////////////////////////////////////////////////////////////////////
 663 // Transport classes for IP
 664
 665 /**This class represents a particular H323 transport using IP.
 666    It is used by the TCP and UDP transports.
 667  */
 668 class H323TransportIP : public H323Transport
 669 {
 670   PCLASSINFO(H323TransportIP, H323Transport);
 671
 672   public:
 673     /**Create a new transport channel.
 674      */
 675     H323TransportIP(
 676       H323EndPoint & endpoint,    ///<  H323 End Point object
 677       PIPSocket::Address binding, ///<  Local interface to use
 678       WORD remPort                ///<  Remote port to use
 679     );
 680
 681     /**Get the transport dependent name of the local endpoint.
 682       */
 683     virtual H323TransportAddress GetLocalAddress() const;
 684
 685     /**Get the transport dependent name of the remote endpoint.
 686       */
 687     virtual H323TransportAddress GetRemoteAddress() const;
 688
 689     /**Check that the transport address PDU is compatible with transport.
 690       */
 691     virtual BOOL IsCompatibleTransport(
 692       const H225_TransportAddress & pdu
 693     ) const;
 694
 695     /**Set up a transport address PDU for RAS channel.
 696       */
 697     virtual void SetUpTransportPDU(
 698       H225_TransportAddress & pdu,
 699       BOOL localTsap
 700     ) const;
 701
 702     /**Set up a transport address PDU for logical channel.
 703       */
 704     virtual void SetUpTransportPDU(
 705       H245_TransportAddress & pdu,
 706       unsigned tsap
 707     ) const;
 708
 709
 710   protected:
 711     PIPSocket::Address localAddress;  // Address of the local interface
 712     WORD               localPort;
 713     PIPSocket::Address remoteAddress; // Address of the remote host
 714     WORD               remotePort;
 715 };
 716
 717
 718 ///////////////////////////////////////////////////////////////////////////////
 719 // Transport classes for TCP/IP
 720
 721 /**This class manages H323 connections using TCP/IP transport.
 722  */
 723 class H323ListenerTCP : public H323Listener
 724 {
 725   PCLASSINFO(H323ListenerTCP, H323Listener);
 726
 727   public:
 728     /**Create a new listener for the TCP/IP protocol.
 729      */
 730     H323ListenerTCP(
 731       H323EndPoint & endpoint,    ///<  Endpoint instance for channel
 732       PIPSocket::Address binding, ///<  Local interface to listen on
 733       WORD port,                  ///<  TCP port to listen for connections
 734       BOOL exclusive = FALSE      ///<  Fail if listener port in use
 735     );
 736
 737     /** Destroy the listener thread.
 738       */
 739     ~H323ListenerTCP();
 740
 741   // Overrides from H323Listener
 742     /** Open the listener.
 743       */
 744     virtual BOOL Open();
 745
 746     /**Stop the listener thread and no longer accept incoming connections.
 747      */
 748     virtual BOOL Close();
 749
 750     /**Accept a new incoming transport.
 751       */
 752     virtual H323Transport * Accept(
 753       const PTimeInterval & timeout  ///<  Time to wait for incoming connection
 754     );
 755
 756     /**Get the local transport address on which this listener may be accessed.
 757       */
 758     virtual H323TransportAddress GetTransportAddress() const;
 759
 760     /**Set up a transport address PDU for bidirectional logical channels.
 761       */
 762     virtual BOOL SetUpTransportPDU(
 763       H245_TransportAddress & pdu,        ///<  Transport addresses listening on
 764       const H323Transport & associatedTransport ///<  Associated transport for precendence and translation
 765     );
 766
 767     WORD GetListenerPort() const { return listener.GetPort(); }
 768
 769
 770   protected:
 771     /**Handle incoming H.323 connections and dispatch them in new threads
 772        based on the H323Transport class. This is defined in the descendent
 773        class that knows what the low level transport is, eg H323ListenerIP
 774        for the TCP/IP protocol.
 775
 776        Note this function does not return until the Close() function is called
 777        or there is some other error.
 778      */
 779     virtual void Main();
 780
 781
 782     PTCPSocket listener;
 783     PIPSocket::Address localAddress;
 784     BOOL exclusiveListener;
 785 };
 786
 787
 788 /**This class represents a particular H323 transport using TCP/IP.
 789  */
 790 class H323TransportTCP : public H323TransportIP
 791 {
 792   PCLASSINFO(H323TransportTCP, H323TransportIP);
 793
 794   public:
 795     /**Create a new transport channel.
 796      */
 797     H323TransportTCP(
 798       H323EndPoint & endpoint,    ///<  H323 End Point object
 799       PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(), ///<  Local interface to use
 800       BOOL listen = FALSE         ///<  Flag for need to wait for remote to connect
 801     );
 802
 803     /**Destroy transport channel.
 804      */
 805     ~H323TransportTCP();
 806
 807     /**Set default remote address to connect to.
 808        Note that this does not necessarily initiate a transport level
 809        connection, but only indicates where to connect to. The actual
 810        connection is made by the Connect() function.
 811       */
 812     virtual BOOL SetRemoteAddress(
 813       const H323TransportAddress & address
 814     );
 815
 816     /**Connect to the remote party.
 817       */
 818     virtual BOOL Connect();
 819
 820     /**Close the channel.
 821       */
 822     virtual BOOL Close();
 823
 824     /**Read a protocol data unit from the transport.
 825        This will read using the transports mechanism for PDU boundaries, for
 826        example UDP is a single Read() call, while for TCP there is a TPKT
 827        header that indicates the size of the PDU.
 828       */
 829     BOOL ReadPDU(
 830       PBYTEArray & pdu   ///<  PDU read from transport
 831     );
 832
 833     /**Extract a protocol data unit from the transport
 834       */
 835     BOOL ExtractPDU(
 836       const PBYTEArray & pdu,
 837       PINDEX & len
 838     );
 839
 840     /**Write a protocol data unit from the transport.
 841        This will write using the transports mechanism for PDU boundaries, for
 842        example UDP is a single Write() call, while for TCP there is a TPKT
 843        header that indicates the size of the PDU.
 844       */
 845     BOOL WritePDU(
 846       const PBYTEArray & pdu  ///<  PDU to write
 847     );
 848
 849     /**Begin the opening of a control channel.
 850        This sets up the channel so that the remote endpoint can connect back
 851        to this endpoint.
 852       */
 853     virtual H323Transport * CreateControlChannel(
 854       H323Connection & connection
 855     );
 856
 857     /**Finish the opening of a control channel.
 858        This waits for the connect backfrom the remote endpoint, completing the
 859        control channel open sequence.
 860       */
 861     virtual BOOL AcceptControlChannel(
 862       H323Connection & connection
 863     );
 864
 865     /**Indicate we are waiting from remote to connect back to us.
 866       */
 867     virtual BOOL IsListening() const;
 868
 869
 870   protected:
 871     /**This callback is executed when the Open() function is called with
 872        open channels. It may be used by descendent channels to do any
 873        handshaking required by the protocol that channel embodies.
 874
 875        The default behaviour is to simply return TRUE.
 876
 877        @return
 878        Returns TRUE if the protocol handshaking is successful.
 879      */
 880     virtual BOOL OnOpen();
 881
 882
 883     PTCPSocket * h245listener;
 884 };
 885
 886
 887 ///////////////////////////////////////////////////////////////////////////////
 888 // Transport classes for UDP/IP
 889
 890 /**This class represents a particular H323 transport using UDP/IP.
 891  */
 892 class H323TransportUDP : public H323TransportIP
 893 {
 894   PCLASSINFO(H323TransportUDP, H323TransportIP);
 895
 896   public:
 897     /**Create a new transport channel.
 898      */
 899     H323TransportUDP(
 900       H323EndPoint & endpoint,                  ///<  H323 End Point object
 901       PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(),  ///<  Local interface to listen on
 902       WORD localPort = 0,                       ///<  Local port to listen on
 903       WORD remotePort = 0                       ///<  Remote port to connect on
 904     );
 905     ~H323TransportUDP();
 906
 907     /**Set default remote address to connect to.
 908        Note that this does not necessarily initiate a transport level
 909        connection, but only indicates where to connect to. The actual
 910        connection is made by the Connect() function.
 911       */
 912     virtual BOOL SetRemoteAddress(
 913       const H323TransportAddress & address
 914     );
 915
 916     /**Connect to the remote party.
 917       */
 918     virtual BOOL Connect();
 919
 920     /**Set read to promiscuous mode.
 921        Normally only reads from the specifed remote address are accepted. This
 922        flag allows packets to be accepted from any remote, provided the
 923        underlying protocol can do so.
 924
 925        The Read() call may optionally set the remote address automatically to
 926        whatever the sender host of the last received message was.
 927
 928        Default behaviour sets the internal flag, so that Read() operates as
 929        described.
 930       */
 931     virtual void SetPromiscuous(
 932       PromisciousModes promiscuous
 933     );
 934
 935     /**Get the transport address of the last received PDU.
 936
 937        Default behaviour returns the lastReceivedAddress member variable.
 938       */
 939     virtual H323TransportAddress GetLastReceivedAddress() const;
 940
 941     /**Read a protocol data unit from the transport.
 942        This will read using the transports mechanism for PDU boundaries, for
 943        example UDP is a single Read() call, while for TCP there is a TPKT
 944        header that indicates the size of the PDU.
 945       */
 946     virtual BOOL ReadPDU(
 947       PBYTEArray & pdu   ///<  PDU read from transport
 948     );
 949
 950     /**Extract a protocol data unit from the transport
 951       */
 952     BOOL ExtractPDU(
 953       const PBYTEArray & pdu,
 954       PINDEX & len
 955     );
 956
 957     /**Write a protocol data unit from the transport.
 958        This will write using the transports mechanism for PDU boundaries, for
 959        example UDP is a single Write() call, while for TCP there is a TPKT
 960        header that indicates the size of the PDU.
 961       */
 962     virtual BOOL WritePDU(
 963       const PBYTEArray & pdu  ///<  PDU to write
 964     );
 965
 966     /**Discover a Gatekeeper on the local network.
 967        This locates a gatekeeper on the network and associates this transport
 968        object with packet exchange with that gatekeeper. This broadcasts a UDP
 969        packet on the local network to find the gatekeeper's IP address.
 970       */
 971     virtual BOOL DiscoverGatekeeper(
 972       H323Gatekeeper & gk,                  ///<  Gatekeeper to set on discovery.
 973       H323RasPDU & pdu,                     ///<  GatekeeperRequest PDU
 974       const H323TransportAddress & address  ///<  Address of gatekeeper (if present)
 975     );
 976
 977     /**Get the transport address of the local endpoint.
 978       */
 979     virtual H323TransportAddress GetLocalAddress() const;
 980
 981   protected:
 982     PromisciousModes     promiscuousReads;
 983     H323TransportAddress lastReceivedAddress;
 984     PIPSocket::Address   lastReceivedInterface;
 985     WORD interfacePort;
 986 };
 987
 988
 989 #endif // __TRANSPORTS_H
 990
 991
 992 /////////////////////////////////////////////////////////////////////////////