PTLib  Version 2.10.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
PSTUNClient Class Reference

STUN client. More...

#include <pstun.h>

Inheritance diagram for PSTUNClient:
PNatMethod PObject

Public Types

enum  { DefaultPort = 3478 }
enum  NatTypes {
  UnknownNat, OpenNat, ConeNat, RestrictedNat,
  PortRestrictedNat, SymmetricNat, SymmetricFirewall, BlockedNat,
  PartialBlockedNat, NumNatTypes
}
- Public Types inherited from PNatMethod
enum  RTPSupportTypes {
  RTPSupported, RTPIfSendMedia, RTPUnsupported, RTPUnknown,
  NumRTPSupportTypes
}

Public Member Functions

 PSTUNClient ()
 PSTUNClient (const PString &server, WORD portBase=0, WORD portMax=0, WORD portPairBase=0, WORD portPairMax=0)
 PSTUNClient (const PIPSocket::Address &serverAddress, WORD serverPort=DefaultPort, WORD portBase=0, WORD portMax=0, WORD portPairBase=0, WORD portPairMax=0)
void Initialise (const PString &server, WORD portBase=0, WORD portMax=0, WORD portPairBase=0, WORD portPairMax=0)
virtual PString GetName () const
 Get the NAT traversal method name.
virtual bool GetServerAddress (PIPSocket::Address &address, WORD &port) const
 Get the current server address and port being used.
PBoolean SetServer (const PString &server)
 Set the STUN server to use.
PBoolean SetServer (const PIPSocket::Address &serverAddress, WORD serverPort=0)
 Set the STUN server to use by IP address and port.
NatTypes GetNatType (PBoolean force=false)
 Determine via the STUN protocol the NAT type for the router.
PString GetNatTypeName (PBoolean force=false)
 Determine via the STUN protocol the NAT type for the router.
RTPSupportTypes GetRTPSupport (PBoolean force=false)
 Return an indication if the current STUN type supports RTP Use the force variable to guarantee an up to date test.
virtual PBoolean GetExternalAddress (PIPSocket::Address &externalAddress, const PTimeInterval &maxAge=1000)
 Determine the external router address.
virtual bool GetInterfaceAddress (PIPSocket::Address &internalAddress) const
 Return the interface NAT router is using.
void InvalidateCache ()
 Invalidates the cached addresses and modes.
PBoolean CreateSocket (PUDPSocket *&socket, const PIPSocket::Address &binding=PIPSocket::GetDefaultIpAny(), WORD localPort=0)
 Create a single socket.
virtual PBoolean CreateSocketPair (PUDPSocket *&socket1, PUDPSocket *&socket2, const PIPSocket::Address &binding=PIPSocket::GetDefaultIpAny())
 Create a socket pair.
const PTimeInterval GetTimeout () const
 Get the timeout for responses from STUN server.
void SetTimeout (const PTimeInterval &timeout)
 Set the timeout for responses from STUN server.
PINDEX GetRetries () const
 Get the number of retries for responses from STUN server.
void SetRetries (PINDEX retries)
 Set the number of retries for responses from STUN server.
PINDEX GetSocketsForPairing () const
 Get the number of sockets to create in attempt to get a port pair.
void SetSocketsForPairing (PINDEX numSockets)
 Set the number of sockets to create in attempt to get a port pair.
virtual bool IsAvailable (const PIPSocket::Address &binding=PIPSocket::GetDefaultIpAny())
 Returns whether the Nat Method is ready and available in assisting in NAT Traversal.
- Public Member Functions inherited from PNatMethod
 PNatMethod ()
 Default Contructor.
 ~PNatMethod ()
 Deconstructor.
virtual void PrintOn (ostream &strm) const
 Output the contents of the object to the stream.
virtual PString GetServer () const
 Get the current server address name.
virtual PBoolean CreateSocketPair (PUDPSocket *&socket1, PUDPSocket *&socket2, const PIPSocket::Address &binding, void *userData)
 Create a socket pair.
virtual void Activate (bool active)
 Acrivate Activate/DeActivate the NAT Method on a call by call basis Default does notthing.
virtual void SetAlternateAddresses (const PStringArray &addresses, void *userData=NULL)
 Set Alternate Candidate (ICE) or probe (H.460.24A) addresses.
virtual void SetPortRanges (WORD portBase, WORD portMax=0, WORD portPairBase=0, WORD portPairMax=0)
 Set the port ranges to be used on local machine.
- Public Member Functions inherited from PObject
virtual ~PObject ()
virtual PObjectClone () const
 Create a copy of the class on the heap.
virtual PINDEX HashFunction () const
 This function yields a hash value required by the PDictionary class.
virtual const char * GetClass (unsigned ancestor=0) const
 Get the current dynamic type of the object instance.
PBoolean IsClass (const char *cls) const
virtual PBoolean InternalIsDescendant (const char *clsName) const
 Determine if the dynamic type of the current instance is a descendent of the specified class.
virtual Comparison Compare (const PObject &obj) const
 Compare the two objects and return their relative rank.
virtual Comparison CompareObjectMemoryDirect (const PObject &obj) const
 Determine the byte wise comparison of two objects.
bool operator== (const PObject &obj) const
 Compare the two objects.
bool operator!= (const PObject &obj) const
 Compare the two objects.
bool operator< (const PObject &obj) const
 Compare the two objects.
bool operator> (const PObject &obj) const
 Compare the two objects.
bool operator<= (const PObject &obj) const
 Compare the two objects.
bool operator>= (const PObject &obj) const
 Compare the two objects.
virtual void ReadFrom (istream &strm)
 Input the contents of the object from the stream.

Static Public Member Functions

static PStringList GetNatMethodName ()
 Get the NAT Method Name.
static PString GetNatTypeString (NatTypes type)
 Get NatTypes enumeration as an English string for the type.
- Static Public Member Functions inherited from PNatMethod
static PNatMethodCreate (const PString &name, PPluginManager *pluginMgr=NULL)
 Factory Create.

Protected Member Functions

bool OpenSocket (PUDPSocket &socket, PortInfo &portInfo, const PIPSocket::Address &binding)
- Protected Member Functions inherited from PNatMethod
WORD RandomPortPair (unsigned int start, unsigned int end)
 RandomPortPair This function returns a random port pair base number in the specified range for the creation of the RTP port pairs (this used to avoid issues with multiple NATed devices opening the same local ports and experiencing issues with the behaviour of the NAT device Refer: draft-jennings-behave-test-results-04 sect 3.
- Protected Member Functions inherited from PObject
 PObject ()
 Constructor for PObject, made protected so cannot ever create one on its own.

Protected Attributes

PString serverHost
WORD serverPort
PTimeInterval replyTimeout
PINDEX pollRetries
PINDEX numSocketsForPairing
NatTypes natType
PIPSocket::Address cachedServerAddress
PIPSocket::Address cachedExternalAddress
PIPSocket::Address interfaceAddress
PTime timeAddressObtained
- Protected Attributes inherited from PNatMethod
struct PNatMethod::PortInfo singlePortInfo
struct PNatMethod::PortInfo pairedPortInfo

Detailed Description

STUN client.

Member Enumeration Documentation

anonymous enum
Enumerator:
DefaultPort 
Enumerator:
UnknownNat 
OpenNat 
ConeNat 
RestrictedNat 
PortRestrictedNat 
SymmetricNat 
SymmetricFirewall 
BlockedNat 
PartialBlockedNat 
NumNatTypes 

Constructor & Destructor Documentation

PSTUNClient::PSTUNClient ( )
PSTUNClient::PSTUNClient ( const PString server,
WORD  portBase = 0,
WORD  portMax = 0,
WORD  portPairBase = 0,
WORD  portPairMax = 0 
)
PSTUNClient::PSTUNClient ( const PIPSocket::Address serverAddress,
WORD  serverPort = DefaultPort,
WORD  portBase = 0,
WORD  portMax = 0,
WORD  portPairBase = 0,
WORD  portPairMax = 0 
)

Member Function Documentation

PBoolean PSTUNClient::CreateSocket ( PUDPSocket *&  socket,
const PIPSocket::Address binding = PIPSocket::GetDefaultIpAny(),
WORD  localPort = 0 
)
virtual

Create a single socket.

The STUN protocol is used to create a socket for which the external IP address and port numbers are known. A PUDPSocket descendant is returned which will, in response to GetLocalAddress() return the externally visible IP and port rather than the local machines IP and socket.

The will create a new socket pointer. It is up to the caller to make sure the socket is deleted to avoid memory leaks.

The socket pointer is set to NULL if the function fails and returns false.

Implements PNatMethod.

virtual PBoolean PSTUNClient::CreateSocketPair ( PUDPSocket *&  socket1,
PUDPSocket *&  socket2,
const PIPSocket::Address binding = PIPSocket::GetDefaultIpAny() 
)
virtual

Create a socket pair.

The STUN protocol is used to create a pair of sockets with adjacent port numbers for which the external IP address and port numbers are known. PUDPSocket descendants are returned which will, in response to GetLocalAddress() return the externally visible IP and port rather than the local machines IP and socket.

The will create new socket pointers. It is up to the caller to make sure the sockets are deleted to avoid memory leaks.

The socket pointers are set to NULL if the function fails and returns false.

Implements PNatMethod.

virtual PBoolean PSTUNClient::GetExternalAddress ( PIPSocket::Address externalAddress,
const PTimeInterval maxAge = 1000 
)
virtual

Determine the external router address.

This will send UDP packets out using the STUN protocol to determine the intervening routers external IP address.

A cached address is returned provided it is no older than the time specified.

Parameters
externalAddressExternal address of router
maxAgeMaximum age for caching

Implements PNatMethod.

virtual bool PSTUNClient::GetInterfaceAddress ( PIPSocket::Address internalAddress) const
virtual

Return the interface NAT router is using.

Implements PNatMethod.

virtual PString PSTUNClient::GetName ( ) const
inlinevirtual

Get the NAT traversal method name.

Implements PNatMethod.

static PStringList PSTUNClient::GetNatMethodName ( )
inlinestatic

Get the NAT Method Name.

NatTypes PSTUNClient::GetNatType ( PBoolean  force = false)

Determine via the STUN protocol the NAT type for the router.

This will cache the last determine NAT type. Use the force variable to guarantee an up to date value.

Parameters
forceForce a new check

Referenced by GetNatTypeName().

PString PSTUNClient::GetNatTypeName ( PBoolean  force = false)
inline

Determine via the STUN protocol the NAT type for the router.

As for GetNatType() but returns an English string for the type.

Parameters
forceForce a new check

References GetNatType(), and GetNatTypeString().

static PString PSTUNClient::GetNatTypeString ( NatTypes  type)
static

Get NatTypes enumeration as an English string for the type.

Parameters
typeNAT Type to get name of

Referenced by GetNatTypeName(), and operator<<().

PINDEX PSTUNClient::GetRetries ( ) const
inline

Get the number of retries for responses from STUN server.

References pollRetries.

RTPSupportTypes PSTUNClient::GetRTPSupport ( PBoolean  force = false)
virtual

Return an indication if the current STUN type supports RTP Use the force variable to guarantee an up to date test.

Parameters
forceForce a new check

Implements PNatMethod.

virtual bool PSTUNClient::GetServerAddress ( PIPSocket::Address address,
WORD &  port 
) const
virtual

Get the current server address and port being used.

Parameters
addressAddress of server
portPort server is using.

Implements PNatMethod.

PINDEX PSTUNClient::GetSocketsForPairing ( ) const
inline

Get the number of sockets to create in attempt to get a port pair.

RTP requires a pair of consecutive ports. To get this several sockets must be opened and fired through the NAT firewall to get a pair. The busier the firewall the more sockets will be required.

References numSocketsForPairing.

const PTimeInterval PSTUNClient::GetTimeout ( ) const
inline

Get the timeout for responses from STUN server.

References replyTimeout.

void PSTUNClient::Initialise ( const PString server,
WORD  portBase = 0,
WORD  portMax = 0,
WORD  portPairBase = 0,
WORD  portPairMax = 0 
)
void PSTUNClient::InvalidateCache ( )

Invalidates the cached addresses and modes.

This allows to lazily update the external address cache at the next attempt to get the external address.

virtual bool PSTUNClient::IsAvailable ( const PIPSocket::Address binding = PIPSocket::GetDefaultIpAny())
virtual

Returns whether the Nat Method is ready and available in assisting in NAT Traversal.

The principal is this function is to allow the EP to detect various methods and if a method is detected then this method is available for NAT traversal. The availablity of the STUN Method is dependant on the Type of NAT being used.

Parameters
bindingInterface to see if NAT is available on

Implements PNatMethod.

bool PSTUNClient::OpenSocket ( PUDPSocket socket,
PortInfo portInfo,
const PIPSocket::Address binding 
)
protected
void PSTUNClient::SetRetries ( PINDEX  retries)
inline

Set the number of retries for responses from STUN server.

Parameters
retriesNumber of retries

References pollRetries.

PBoolean PSTUNClient::SetServer ( const PString server)

Set the STUN server to use.

The server string may be of the form host:port. If :port is absent then the default port 3478 is used. The substring port can also be a service name as found in /etc/services. The host substring may be a DNS name or explicit IP address.

PBoolean PSTUNClient::SetServer ( const PIPSocket::Address serverAddress,
WORD  serverPort = 0 
)

Set the STUN server to use by IP address and port.

If serverPort is zero then the default port of 3478 is used.

void PSTUNClient::SetSocketsForPairing ( PINDEX  numSockets)
inline

Set the number of sockets to create in attempt to get a port pair.

RTP requires a pair of consecutive ports. To get this several sockets must be opened and fired through the NAT firewall to get a pair. The busier the firewall the more sockets will be required.

Parameters
numSocketsNumber opf sockets to create

References numSocketsForPairing.

void PSTUNClient::SetTimeout ( const PTimeInterval timeout)
inline

Set the timeout for responses from STUN server.

Parameters
timeoutNew timeout in milliseconds

References replyTimeout.

Member Data Documentation

PIPSocket::Address PSTUNClient::cachedExternalAddress
protected
PIPSocket::Address PSTUNClient::cachedServerAddress
protected
PIPSocket::Address PSTUNClient::interfaceAddress
protected
NatTypes PSTUNClient::natType
protected
PINDEX PSTUNClient::numSocketsForPairing
protected
PINDEX PSTUNClient::pollRetries
protected

Referenced by GetRetries(), and SetRetries().

PTimeInterval PSTUNClient::replyTimeout
protected

Referenced by GetTimeout(), and SetTimeout().

PString PSTUNClient::serverHost
protected
WORD PSTUNClient::serverPort
protected
PTime PSTUNClient::timeAddressObtained
protected

The documentation for this class was generated from the following file: