include/ptclib/pstun.h

   1 /*
   2  * pstun.h
   3  *
   4  * STUN client
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 2003 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 Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Contributor(s): ______________________________________.
  25  *
  26  * $Log$
  27  * Revision 1.17  2007/08/22 05:04:39  rjongbloed
  28  * Added ability to set a specific local port for STUN created sockets.
  29  *
  30  * Revision 1.16  2007/07/22 03:07:31  rjongbloed
  31  * Added parameter so can bind STUN socket to specific interface.
  32  *
  33  * Revision 1.15  2007/04/19 04:33:53  csoutheren
  34  * Fixed problems with pre-compiled headers
  35  *
  36  * Revision 1.14  2007/02/11 13:13:18  shorne
  37  * Added GetName function
  38  *
  39  * Revision 1.13  2006/12/23 15:08:00  shorne
  40  * Now Factory loaded for ease of addition of new NAT Methods
  41  *
  42  * Revision 1.12  2005/11/30 12:47:37  csoutheren
  43  * Removed tabs, reformatted some code, and changed tags for Doxygen
  44  *
  45  * Revision 1.11  2005/07/13 11:15:15  csoutheren
  46  * Backported NAT abstraction files from isvo branch
  47  *
  48  * Revision 1.10  2005/06/20 10:55:16  rjongbloed
  49  * Changed the timeout and retries so if there is a blocking firewall it does not take 15 seconds to find out!
  50  * Added access functions so timeout and retries are application configurable.
  51  * Added function (and << operator) to get NAT type enum as string.
  52  *
  53  * Revision 1.9.4.1  2005/04/25 13:21:36  shorne
  54  * Add Support for other NAT methods
  55  *
  56  * Revision 1.9  2004/11/25 07:23:46  csoutheren
  57  * Added IsSupportingRTP function to simplify detecting when STUN supports RTP
  58  *
  59  * Revision 1.8  2004/03/14 05:47:52  rjongbloed
  60  * Fixed incorrect detection of symmetric NAT (eg Linux masquerading) and also
  61  *   some NAT systems which are partially blocked due to firewall rules.
  62  *
  63  * Revision 1.7  2004/02/24 11:15:48  rjongbloed
  64  * Added function to get external router address, also did a bunch of documentation.
  65  *
  66  * Revision 1.6  2004/01/17 17:54:02  rjongbloed
  67  * Added function to get server name from STUN client.
  68  *
  69  * Revision 1.5  2003/10/05 00:56:25  rjongbloed
  70  * Rewrite of STUN to not to use imported code with undesirable license.
  71  *
  72  * Revision 1.4  2003/02/05 06:26:49  robertj
  73  * More work in making the STUN usable for Symmetric NAT systems.
  74  *
  75  * Revision 1.3  2003/02/04 07:01:02  robertj
  76  * Added ip/port version of constructor.
  77  *
  78  * Revision 1.2  2003/02/04 05:05:55  craigs
  79  * Added new functions
  80  *
  81  * Revision 1.1  2003/02/04 03:31:04  robertj
  82  * Added STUN
  83  *
  84  */
  85
  86 #ifndef _PSTUN_H
  87 #define _PSTUN_H
  88
  89 #ifdef P_USE_PRAGMA
  90 #pragma interface
  91 #endif
  92
  93 #ifndef _PTLIB_H
  94 #include <ptlib.h>
  95 #endif
  96
  97 #include <ptclib/pnat.h>
  98 #include <ptlib/sockets.h>
  99
 100
 101 /**UDP socket that has been created by the STUN client.
 102   */
 103 class PSTUNUDPSocket : public PUDPSocket
 104 {
 105   PCLASSINFO(PSTUNUDPSocket, PUDPSocket);
 106   public:
 107     PSTUNUDPSocket();
 108
 109     virtual BOOL GetLocalAddress(
 110       Address & addr    ///< Variable to receive hosts IP address
 111     );
 112     virtual BOOL GetLocalAddress(
 113       Address & addr,    ///< Variable to receive peer hosts IP address
 114       WORD & port        ///< Variable to receive peer hosts port number
 115     );
 116
 117   protected:
 118     PIPSocket::Address externalIP;
 119
 120   friend class PSTUNClient;
 121 };
 122
 123
 124 /**STUN client.
 125   */
 126 class PSTUNClient : public PNatMethod
 127 {
 128   PCLASSINFO(PSTUNClient, PNatMethod);
 129   public:
 130     enum {
 131       DefaultPort = 3478
 132     };
 133
 134     PSTUNClient();
 135
 136     PSTUNClient(
 137       const PString & server,
 138       WORD portBase = 0,
 139       WORD portMax = 0,
 140       WORD portPairBase = 0,
 141       WORD portPairMax = 0
 142     );
 143     PSTUNClient(
 144       const PIPSocket::Address & serverAddress,
 145       WORD serverPort = DefaultPort,
 146       WORD portBase = 0,
 147       WORD portMax = 0,
 148       WORD portPairBase = 0,
 149       WORD portPairMax = 0
 150     );
 151
 152
 153     void Initialise(
 154       const PString & server,
 155       WORD portBase = 0,
 156       WORD portMax = 0,
 157       WORD portPairBase = 0,
 158       WORD portPairMax = 0
 159     );
 160
 161     /**Get the NAT Method Name
 162      */
 163     static PStringList GetNatMethodName() { return PStringList("STUN"); }
 164
 165     virtual PStringList GetName() const
 166       { return GetNatMethodName(); }
 167
 168     /**Get the current STUN server address and port being used.
 169       */
 170     PString GetServer() const;
 171
 172     /**Set the STUN server to use.
 173        The server string may be of the form host:port. If :port is absent
 174        then the default port 3478 is used. The substring port can also be
 175        a service name as found in /etc/services. The host substring may be
 176        a DNS name or explicit IP address.
 177       */
 178     BOOL SetServer(
 179       const PString & server
 180     );
 181
 182     /**Set the STUN server to use by IP address and port.
 183        If serverPort is zero then the default port of 3478 is used.
 184       */
 185     BOOL SetServer(
 186       const PIPSocket::Address & serverAddress,
 187       WORD serverPort = 0
 188     );
 189
 190     enum NatTypes {
 191       UnknownNat,
 192       OpenNat,
 193       ConeNat,
 194       RestrictedNat,
 195       PortRestrictedNat,
 196       SymmetricNat,
 197       SymmetricFirewall,
 198       BlockedNat,
 199       PartialBlockedNat,
 200       NumNatTypes
 201     };
 202
 203     /**Determine via the STUN protocol the NAT type for the router.
 204        This will cache the last determine NAT type. Use the force variable to
 205        guarantee an up to date value.
 206       */
 207     NatTypes GetNatType(
 208       BOOL force = FALSE    ///< Force a new check
 209     );
 210
 211     /**Determine via the STUN protocol the NAT type for the router.
 212        As for GetNatType() but returns an English string for the type.
 213       */
 214     PString GetNatTypeName(
 215       BOOL force = FALSE    ///< Force a new check
 216     ) { return GetNatTypeString(GetNatType(force)); }
 217
 218     /**Get NatTypes enumeration as an English string for the type.
 219       */
 220     static PString GetNatTypeString(
 221       NatTypes type   ///< NAT Type to get name of
 222     );
 223
 224     enum RTPSupportTypes {
 225       RTPOK,
 226       RTPUnknown,
 227       RTPUnsupported,
 228       RTPIfSendMedia
 229     };
 230
 231     /**Return an indication if the current STUN type supports RTP
 232       Use the force variable to guarantee an up to date test
 233       */
 234     RTPSupportTypes IsSupportingRTP(
 235       BOOL force = FALSE    ///< Force a new check
 236     );
 237
 238     /**Determine the external router address.
 239        This will send UDP packets out using the STUN protocol to determine
 240        the intervening routers external IP address.
 241
 242        A cached address is returned provided it is no older than the time
 243        specified.
 244       */
 245     virtual BOOL GetExternalAddress(
 246       PIPSocket::Address & externalAddress, ///< External address of router
 247       const PTimeInterval & maxAge = 1000   ///< Maximum age for caching
 248     );
 249
 250     /**Create a single socket.
 251        The STUN protocol is used to create a socket for which the external IP
 252        address and port numbers are known. A PUDPSocket descendant is returned
 253        which will, in response to GetLocalAddress() return the externally
 254        visible IP and port rather than the local machines IP and socket.
 255
 256        The will create a new socket pointer. It is up to the caller to make
 257        sure the socket is deleted to avoid memory leaks.
 258
 259        The socket pointer is set to NULL if the function fails and returns
 260        FALSE.
 261       */
 262     BOOL CreateSocket(
 263       PUDPSocket * & socket,
 264       const PIPSocket::Address & binding = PIPSocket::GetDefaultIpAny(),
 265       WORD localPort = 0
 266     );
 267
 268     /**Create a socket pair.
 269        The STUN protocol is used to create a pair of sockets with adjacent
 270        port numbers for which the external IP address and port numbers are
 271        known. PUDPSocket descendants are returned which will, in response
 272        to GetLocalAddress() return the externally visible IP and port rather
 273        than the local machines IP and socket.
 274
 275        The will create new socket pointers. It is up to the caller to make
 276        sure the sockets are deleted to avoid memory leaks.
 277
 278        The socket pointers are set to NULL if the function fails and returns
 279        FALSE.
 280       */
 281     virtual BOOL CreateSocketPair(
 282       PUDPSocket * & socket1,
 283       PUDPSocket * & socket2,
 284       const PIPSocket::Address & binding = PIPSocket::GetDefaultIpAny()
 285     );
 286
 287     /**Get the timeout for responses from STUN server.
 288       */
 289     const PTimeInterval GetTimeout() const { return replyTimeout; }
 290
 291     /**Set the timeout for responses from STUN server.
 292       */
 293     void SetTimeout(
 294       const PTimeInterval & timeout   ///< New timeout in milliseconds
 295     ) { replyTimeout = timeout; }
 296
 297     /**Get the number of retries for responses from STUN server.
 298       */
 299     PINDEX GetRetries() const { return pollRetries; }
 300
 301     /**Set the number of retries for responses from STUN server.
 302       */
 303     void SetRetries(
 304       PINDEX retries    ///< Number of retries
 305     ) { pollRetries = retries; }
 306
 307     /**Get the number of sockets to create in attempt to get a port pair.
 308        RTP requires a pair of consecutive ports. To get this several sockets
 309        must be opened and fired through the NAT firewall to get a pair. The
 310        busier the firewall the more sockets will be required.
 311       */
 312     PINDEX GetSocketsForPairing() const { return numSocketsForPairing; }
 313
 314     /**Set the number of sockets to create in attempt to get a port pair.
 315        RTP requires a pair of consecutive ports. To get this several sockets
 316        must be opened and fired through the NAT firewall to get a pair. The
 317        busier the firewall the more sockets will be required.
 318       */
 319     void SetSocketsForPairing(
 320       PINDEX numSockets   ///< Number opf sockets to create
 321     ) { numSocketsForPairing = numSockets; }
 322
 323     /**Returns whether the Nat Method is ready and available in
 324        assisting in NAT Traversal. The principal is this function is
 325        to allow the EP to detect various methods and if a method
 326        is detected then this method is available for NAT traversal.
 327        The availablity of the STUN Method is dependant on the Type
 328        of NAT being used.
 329      */
 330     virtual BOOL IsAvailable();
 331
 332   protected:
 333     PIPSocket::Address serverAddress;
 334     WORD               serverPort;
 335     PTimeInterval      replyTimeout;
 336     PINDEX             pollRetries;
 337     PINDEX             numSocketsForPairing;
 338
 339     bool OpenSocket(PUDPSocket & socket, PortInfo & portInfo, const PIPSocket::Address & binding) const;
 340
 341     NatTypes           natType;
 342     PIPSocket::Address cachedExternalAddress;
 343     PTime              timeAddressObtained;
 344 };
 345
 346
 347 inline ostream & operator<<(ostream & strm, PSTUNClient::NatTypes type) { return strm << PSTUNClient::GetNatTypeString(type); }
 348
 349 /// Factory loader
 350 typedef PSTUNClient PNatMethod_STUN;
 351 PWLIB_STATIC_LOAD_PLUGIN(STUN, PNatMethod);
 352
 353
 354 #endif // _PSTUN_H
 355
 356
 357 // End of file ////////////////////////////////////////////////////////////////