#include <OsNatDatagramSocket.h>

Inheritance diagram for OsNatDatagramSocket:

[legend]

Collaboration diagram for OsNatDatagramSocket:

[legend]

Public Member Functions
	OsNatDatagramSocket (int remoteHostPort, const char remoteHostName, int localHostPort=PORT_DEFAULT, const char localHostName=NULL, OsNotification *pNotification=NULL)

virtual	~OsNatDatagramSocket ()

virtual OsSocket *	getSocket ()

virtual int	read (char *buffer, int bufferLength)

virtual int	read (char buffer, int bufferLength, UtlString ipAddress, int *port)

virtual int	read (char buffer, int bufferLength, struct in_addr ipAddress, int *port)

virtual int	read (char *buffer, int bufferLength, long waitMilliseconds)

virtual int	write (const char *buffer, int bufferLength)

virtual int	socketWrite (const char buffer, int bufferLength, const char ipAddress, int port, PacketType packetType=UNKNOWN_PACKET)

virtual int	write (const char buffer, int bufferLength, const char ipAddress, int port)

virtual int	write (const char *buffer, int bufferLength, long waitMilliseconds)

virtual void	enableStun (const char *szStunServer, int stunPort, int iKeepAlive, int stunOptions, bool bReadFromSocket)

virtual void	disableStun ()

virtual void	enableTurn (const char szTurnSever, int turnPort, int iKeepAlive, const char username, const char *password, bool bReadFromSocket)

virtual void	disableTurn ()

virtual bool	waitForBinding (NAT_BINDING binding, bool bWaitUntilReady)

virtual void	enableTransparentReads (bool bEnable)

virtual void	addAlternateDestination (const char *szAddress, int iPort, int priority)

virtual void	setReadNotification (OsNotification *pNotification)

virtual void	readyDestination (const char *szAddress, int iPort)

virtual void	setNotifier (OsNotification *pNotification)

virtual UtlBoolean	addCrLfKeepAlive (const char szRemoteIp, const int remotePort, const int keepAliveSecs, OsNatKeepaliveListener pListener)

virtual UtlBoolean	removeCrLfKeepAlive (const char *szRemoteIp, const int remotePort)

virtual UtlBoolean	addStunKeepAlive (const char szRemoteIp, const int remotePort, const int keepAliveSecs, OsNatKeepaliveListener pListener)

virtual UtlBoolean	removeStunKeepAlive (const char *szRemoteIp, const int remotePort)

virtual UtlBoolean	getMappedIp (UtlString ip, int port)

virtual UtlBoolean	getRelayIp (UtlString ip, int port)

virtual UtlBoolean	getBestDestinationAddress (UtlString &address, int &iPort)

virtual UtlBoolean	applyDestinationAddress (const char *szAddress, int iPort)

virtual void	destroy ()

Public Member Functions inherited from OsDatagramSocket
	OsDatagramSocket (int remoteHostPort, const char remoteHostName, int localHostPort=PORT_DEFAULT, const char localHostName=NULL)

virtual	~OsDatagramSocket ()

virtual UtlBoolean	reconnect ()

void	doConnect (int remotePort, const char *remoteHostName, UtlBoolean simulateConnect=FALSE)

virtual OsSocket::IpProtocolSocketType	getIpProtocol () const

virtual void	getRemoteHostIp (struct in_addr remoteHostAddress, int remotePort=NULL)

Public Member Functions inherited from OsSocket
virtual UtlContainableType	getContainableType () const
	Determine whether or not the values in a containable are comparable. More...

	OsSocket ()

virtual	~OsSocket ()

virtual void	close ()
	param: waitMilliseconds - The maximum number of milliseconds to block. This may be set to zero in which case it does not block. More...

virtual void	makeNonblocking ()

virtual void	makeBlocking ()

virtual int	getSocketDescriptor () const

virtual void	getLocalHostIp (UtlString *localHostAddress) const

virtual const UtlString &	getLocalIp () const

virtual void	setLocalIp (const UtlString &localIp)

virtual int	getLocalHostPort () const

virtual void	getRemoteHostName (UtlString *remoteHostName) const

virtual void	getRemoteHostIp (UtlString remoteHostAddress, int remotePort=NULL)

virtual int	getRemoteHostPort () const

virtual UtlBoolean	isOk () const

virtual UtlBoolean	isConnected () const

virtual UtlBoolean	isReadyToReadEx (long waitMilliseconds, UtlBoolean &rSocketError) const

virtual UtlBoolean	isReadyToRead (long waitMilliseconds=0) const

virtual UtlBoolean	isReadyToWrite (long waitMilliseconds=0) const

Public Member Functions inherited from UtlContainableAtomic
virtual unsigned	hash () const
	Calculate a hash code for this object. More...

virtual int	compareTo (UtlContainable const *) const
	Compare this object to another object. More...

Public Member Functions inherited from UtlContainable
virtual	~UtlContainable ()

unsigned	directHash () const
	Provides a hash function that uses the object pointer as the hash value. More...

virtual UtlBoolean	isEqual (UtlContainable const *) const
	Test this object to another object for equality. More...

virtual UtlBoolean	isInstanceOf (const UtlContainableType type) const
	Determine if this object is a derivative of the specified UtlContainableType. More...

Public Member Functions inherited from OsNatSocketBaseImpl
	OsNatSocketBaseImpl ()

virtual	~OsNatSocketBaseImpl ()

Public Member Functions inherited from IStunSocket
virtual	~IStunSocket ()

Protected Member Functions
void	setStunAddress (const UtlString &address, const int iPort)

void	setTurnAddress (const UtlString &address, const int iPort)

void	markStunFailure ()

void	markStunSuccess (bool bAddressChanged)

void	markTurnFailure ()

void	markTurnSuccess ()

void	evaluateDestinationAddress (const UtlString &address, int iPort, int priority)

Protected Member Functions inherited from OsDatagramSocket
	OsDatagramSocket ()

int	bind (int localHostPortNum=PORT_DEFAULT, const char *localHost=NULL)

Protected Member Functions inherited from OsNatSocketBaseImpl
void	markReadTime ()

void	markWriteTime ()

virtual bool	getFirstReadTime (OsDateTime &time)

virtual bool	getLastReadTime (OsDateTime &time)

virtual bool	getFirstWriteTime (OsDateTime &time)

virtual bool	getLastWriteTime (OsDateTime &time)

virtual void	handleStunMessage (char *pBuf, int length, UtlString &fromAddress, int fromPort)

virtual void	handleTurnMessage (char *pBuf, int length, UtlString &fromAddress, int fromPort)

virtual int	handleTurnDataIndication (char buffer, int bufferLength, UtlString pRecvFromIp, int *pRecvFromPort)

virtual bool	handleSturnData (char *buffer, int &bufferLength, UtlString &receivedIp, int &receivedPort)

Protected Attributes
int	miDestPriority

UtlString	mDestAddress

int	miDestPort

Protected Attributes inherited from OsSocket
OsAtomicLightInt	socketDescriptor

int	localHostPort

int	remoteHostPort

UtlString	mLocalIp

UtlString	localHostName

UtlString	remoteHostName

UtlString	mRemoteIpAddress

UtlBoolean	mIsConnected

Protected Attributes inherited from OsNatSocketBaseImpl
unsigned int	miRecordTimes

OsDateTime	mFirstRead

OsDateTime	mLastRead

OsDateTime	mFirstWrite

OsDateTime	mLastWrite

OsMutex	mReadNotificationLock

OsNotification *	mpReadNotification

Friends
class	OsNatAgentTask

Additional Inherited Members
Public Types inherited from OsSocket
enum	IpProtocolSocketType { UNKNOWN = -1, TCP = 0, UDP = 1, MULTICAST = 2, SSL_SOCKET = 3, CUSTOM = 4 }

Static Public Member Functions inherited from OsSocket
static UtlBoolean	socketInit ()

static unsigned long	initDefaultAdapterID (UtlString &adapter_id)

static void	setDefaultBindAddress (const unsigned long bind_address)

static const char *	ipProtocolString (OsSocket::IpProtocolSocketType)
	return the string representation of the SocketProtocolType More...

static void	getDomainName (UtlString &domain_name)

static unsigned long	getDefaultBindAddress ()

static void	getHostName (UtlString *hostName)

static void	getHostIp (UtlString *hostAddress)

static UtlBoolean	isIp4Address (const char *address)

static UtlBoolean	isMcastAddr (const char *ipAddress)

static UtlBoolean	isLocalHost (const char *hostAddress)

static UtlBoolean	isSameHost (const char host1, const char host2)

static UtlBoolean	getHostIpByName (const char hostName, UtlString hostAddress)

static void	inet_ntoa_pt (struct in_addr input_address, UtlString &output_address)

static UtlBoolean	isFramed (IpProtocolSocketType type)

Static Public Member Functions inherited from UtlContainable
static unsigned	stringHash (char const *value)
	Provides a hash function appropriate for null-terminated string values. More...

static UtlBoolean	areSameTypes (const UtlContainableType type1, const UtlContainableType type2)
	Are UtlContainable types the same. More...

Static Public Attributes inherited from OsSocket
static UtlBoolean	socketInitialized = FALSE

Static Public Attributes inherited from UtlContainable
static const UtlContainableType	TYPE = "UtlContainable"

Static Protected Attributes inherited from OsSocket
static const UtlContainableType	TYPE = "OsSocket"
	Class type used for runtime checking. More...

static OsBSem	mInitializeSem

Detailed Description

OsNatDatagramSocket extends an OsDatagramSocket by adding an integrated STUN and TURN client. If STUN or TURN is enabled, request will be send to the designated server every refresh period. The external addresses obtained by these mechanisms are retrieved by invoking getMappedIp and getRelayIp.

For this mechanism to work, someone must pump inbound socket data by calling one of the read() methods. Otherwise, the packets will not be received/processed. Internally, the implementation peeks at the read data and passes the message to the OsNatAgentTask for processing.

Constructor & Destructor Documentation

OsNatDatagramSocket	(	int	remoteHostPort,
		const char *	remoteHostName,
		int	localHostPort = `PORT_DEFAULT`,
		const char *	localHostName = `NULL`,
		OsNotification *	pNotification = `NULL`
	)

Constructor accepting the remote host port, name, localhost port, name, and stun attributes.

Parameters

remoteHostPort	Port of the remote host for connection-like use of OsDatagramSocket. Alternatively, you can also use the ::WriteTo method and include the host/port at sent time.
remoteHostName	Hostname of remote host for a connection-like use of OsDatagramSocket.
localHostPort	Local port number for the socket, PORT_DEFAULT to autoselect
localHostName	Local host name for the socket (e.g. which interface to bind on.
pNotification	Optional notification event that is signaled upon the initial successful stun response or on failure.

~OsNatDatagramSocket ( )

virtual

Standard Destructor

Member Function Documentation

OsSocket * getSocket ( )

virtual

Implements OsNatSocketBaseImpl.

int read	(	char *	buffer,
		int	bufferLength
	)

virtual

Standard read, see OsDatagramSocket for details.

Reimplemented from OsDatagramSocket.

int read	(	char *	buffer,
		int	bufferLength,
		UtlString *	ipAddress,
		int *	port
	)

virtual

Standard read, see OsDatagramSocket for details.

Reimplemented from OsSocket.

int read	(	char *	buffer,
		int	bufferLength,
		struct in_addr *	ipAddress,
		int *	port
	)

virtual

Standard read, see OsDatagramSocket for details.

Reimplemented from OsSocket.

int read	(	char *	buffer,
		int	bufferLength,
		long	waitMilliseconds
	)

virtual

Standard read, see OsDatagramSocket for details.

Reimplemented from OsSocket.

int write	(	const char *	buffer,
		int	bufferLength
	)

virtual

Standard write, see OsDatagramSocket for details.

Reimplemented from OsDatagramSocket.

int socketWrite	(	const char *	buffer,
		int	bufferLength,
		const char *	ipAddress,
		int	port,
		PacketType	packetType = `UNKNOWN_PACKET`
	)

virtual

Standard write - used to invoke the base class write, without timestamping.

Implements IStunSocket.

int write	(	const char *	buffer,
		int	bufferLength,
		const char *	ipAddress,
		int	port
	)

virtual

Standard write, see OsDatagramSocket for details.

Reimplemented from OsDatagramSocket.

int write	(	const char *	buffer,
		int	bufferLength,
		long	waitMilliseconds
	)

virtual

Standard write, see OsDatagramSocket for details.

Reimplemented from OsSocket.

void enableStun	(	const char *	szStunServer,
		int	stunPort,
		int	iKeepAlive,
		int	stunOptions,
		bool	bReadFromSocket
	)

virtual

Enable STUN. Enabling STUN will reset the the keep alive timer and will force a binding refresh.

Parameters

szStunServer
stunPort
iKeepAlive
stunOptions
bReadFromSocket

Implements IStunSocket.

void disableStun ( )

virtual

Disable STUN. Disabling STUN will stop all keep alives and cause getMappedIp to fail.

void enableTurn	(	const char *	szTurnSever,
		int	turnPort,
		int	iKeepAlive,
		const char *	username,
		const char *	password,
		bool	bReadFromSocket
	)

virtual

Enable STUN. Enabling STUN will reset the the keep alive timer and will force a binding refresh.

Parameters

szTurnSever
turnPort
iKeepAlive
username
password
bReadFromSocket

Implements IStunSocket.

void disableTurn ( )

virtual

Disable TURN. Disabling TURN will stop all keep alives and cause getRelayIp to fail.

bool waitForBinding	(	NAT_BINDING	binding,
		bool	bWaitUntilReady
	)

virtual

Waits for result of STUN/TURN binding on this socket. Must be called after STUN/TURN is enabled and reading is not done from socket.

Parameters

binding	Binding type to wait for.
bWaitUntilReady	Whether we should block until bindings are ready

Returns: True if this function needs to be called again, because some of bindings are not yet available. False if all requested bindings are ready.

void enableTransparentReads ( bool bEnable )

virtual

When a stun packet is received this socket can either call read again to obtain the next packet or return with zero bytes read. By default the socket will transparently call Read again and will block until a non-stun packet is read. Calling this method will effect the next read – in other words it will not unblock an active read.

Parameters

bEnable True to enable transparent stun reads and block until a non-stun packet is received (default) or False to return with zero bytes read if a stun packet is received.

Implements IStunSocket.

void addAlternateDestination	(	const char *	szAddress,
		int	iPort,
		int	priority
	)

virtual

Add an alternate destination to this OsNatDatagramSocket. Alternate destinations are tested by sending stun packets. If a stun response is received and the priority is greater than what has already been selected then that address is used.

Parameters

szAddress	IP address of the alternate destination
iPort	port number of the alternate destination
priority	priority of the alternate where a higher number indicates a higher priority.

Implements IStunSocket.

void setReadNotification ( OsNotification * pNotification )

virtual

Set a notification object to be signaled when the first the data packet is received from the socket. Once this is signaled, the notification object is discarded.

Reimplemented from OsNatSocketBaseImpl.

void readyDestination	(	const char *	szAddress,
		int	iPort
	)

virtual

Prepares a destination under TURN usage.

Implements IStunSocket.

void setNotifier ( OsNotification * pNotification )

virtual

Sets as notification event that is signaled upon the next successful stun response or on failure (did not receive a stun response within (STUN_ABORT_THRESHOLD * STUN_TIMEOUT_RESPONSE_MS). If a notification event was previous set either by calling this method or via the constructor, it will be overridden. If the initial STUN success/failure state has already been determined, this method is undefined.

Parameters

pNotification Notification event signaled on success or failure.

UtlBoolean addCrLfKeepAlive	(	const char *	szRemoteIp,
		const int	remotePort,
		const int	keepAliveSecs,
		OsNatKeepaliveListener *	pListener
	)

virtual

UtlBoolean removeCrLfKeepAlive	(	const char *	szRemoteIp,
		const int	remotePort
	)

virtual

UtlBoolean addStunKeepAlive	(	const char *	szRemoteIp,
		const int	remotePort,
		const int	keepAliveSecs,
		OsNatKeepaliveListener *	pListener
	)

virtual

UtlBoolean removeStunKeepAlive	(	const char *	szRemoteIp,
		const int	remotePort
	)

virtual

UtlBoolean getMappedIp	(	UtlString *	ip,
		int *	port
	)

virtual

Return the external mapped IP address for this socket. This method will return false if stun is disabled, it was unable to retrieve a stun binding, or both the ip and port parameters are null.

Parameters

ip	Buffer to place STUN-discovered IP address
port	Buffer to place STUN-discovered port number

Reimplemented from OsDatagramSocket.

UtlBoolean getRelayIp	(	UtlString *	ip,
		int *	port
	)

virtual

Return the external relay IP address for this socket. This method will return false if stun is disabled, it was unable to retrieve a turn allocation, or both the ip and port parameters are null.

Parameters

ip	Buffer to place TURN-discovered IP address
port	Buffer to place TURN-discovered port number

Implements IStunSocket.

UtlBoolean getBestDestinationAddress	(	UtlString &	address,
		int &	iPort
	)

virtual

TODO: DOCS

Implements IStunSocket.

UtlBoolean applyDestinationAddress	(	const char *	szAddress,
		int	iPort
	)

virtual

TODO: DOCS

Implements IStunSocket.

void destroy ( )

virtual

Cleanup routine.

Implements IStunSocket.

void setStunAddress	(	const UtlString &	address,
		const int	iPort
	)

protectedvirtual

Set the STUN-derived address for this socket.

Parameters

address	STUN-derived hostname/IP address
iPort	STUN-derived port address

Implements IStunSocket.

void setTurnAddress	(	const UtlString &	address,
		const int	iPort
	)

protectedvirtual

Set the TURN-dervied relay address for this socket.

Parameters

address	TURN-derived hostname/IP address
iPort	TURN-derived port address

Implements IStunSocket.

void markStunFailure ( )

protectedvirtual

Report that a stun attempt failed.

Implements IStunSocket.

void markStunSuccess ( bool bAddressChanged )

protectedvirtual

Report that a stun attempt succeeded.

Implements IStunSocket.

void markTurnFailure ( )

protectedvirtual

Report that a stun attempt failed.

Implements IStunSocket.

void markTurnSuccess ( )

protectedvirtual

Report that a stun attempt succeeded.

Implements IStunSocket.

void evaluateDestinationAddress	(	const UtlString &	address,
		int	iPort,
		int	priority
	)

protectedvirtual

Reset the destination address for this OsNatDatagramSocket. This method is called by the OsStunAgentTask when a better address is found via STUN/ICE.

Parameters

address	The new destination address
iPort	The new destination port
priority	Priority of the destination address

Implements IStunSocket.

Friends And Related Function Documentation

friend class OsNatAgentTask

friend

Member Data Documentation

int miDestPriority

protected

Priority of destination address / port.

UtlString mDestAddress

protected

Destination address

int miDestPort

protected

Destination port

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation