#include <NATResolver.h>

Inheritance diagram for NATResolver:

[legend]

Collaboration diagram for NATResolver:

[legend]

Public Types
enum	{ kDefaultPort = 4002 }

Public Member Functions
bool	Start (void)

bool	Stop (void)

void	SetAutomaticThreadStop (const bool allow=true)
	When the NATResolver becomes inactive for a period of time this allows the thread to stop processing.

void	SetAutomaticHostSocketReads (const bool allow=false)

void	SetEncryptionKey (const void *data, const int length)

bool	BeginHosting (t_XPSocket *socket)

bool	BeginAdvertise (t_XPSocket socket, void userPointer, const bool isAdvertised, const int globalID, const int sessionID, const int nonceID, const bool externalHost=true, const XPAddress *optionalHost=0, const bool persistant=false)
	Advertises a socket with a set of identifying numbers (isAdvertised, globalID, nonceID) which should be globally unique for this socket. More...

bool	BeginResolve (t_XPSocket socket, void userPointer, const bool isAdvertised, const int globalID, const int sessionID, const int nonceID, const bool tryExternalHost=true, const XPAddress optionalHost=0, const XPAddress optionalFirstTargetTry=0)

void	ForgetSocket (const t_XPSocket *socket)
	Removes the socket from the NATResolver index.

void	ForgetUserPointer (const void *userPointer)
	Forgets all sockets with the same userPointer.

void	ForgetResolve (t_XPSocket *socket, const bool isAdvertised, const int globalID, const int sessionID, const int nonceID)
	Removes the specific resolve request.

bool	CallbackParsePacketData (t_XPSocket socket, const XPAddress &addr, void data, size_t length)

void	SetServer (const XPAddress &address)

virtual void	CallbackResolveFailed (t_XPSocket socket, void userPointer, const int titleID, const bool isAdvertised, const int globalID, const int sessionID, const int nonceID)
	A virtual callback that is triggered when a NAT resolve attempt fails.

virtual void	CallbackResolveResult (t_XPSocket socket, void userPointer, const XPAddress &targetAddress, const int titleID, const bool isAdvertised, const int globalID, const int sessionID, const int nonceID)

virtual void	CallbackExternalAddressKnown (t_XPSocket socket, void userPointer, const XPAddress &externalAddress, const int titleID, const bool isAdvertised, const int globalID, const int sessionID, const int nonceID)
	A virtual callback that is triggered when an advertised socket it told the external address from being advertised to an external host.

Detailed Description

This NAT resolver uses incoming data to respond to queries for NAT negotiation. It can also make requests for NAT negotiation. This class can also make queries to NAT resolve. This class is used by TransportNATUDP.

Member Function Documentation

bool BeginAdvertise	(	t_XPSocket *	socket,
		void *	userPointer,
		const bool	isAdvertised,
		const int	globalID,
		const int	sessionID,
		const int	nonceID,
		const bool	externalHost = `true`,
		const XPAddress *	optionalHost = `0`,
		const bool	persistant = `false`
	)

Advertises a socket with a set of identifying numbers (isAdvertised, globalID, nonceID) which should be globally unique for this socket.

If the NATResolver thread has not started then this calls Start() first.

Parameters

socket	The socket to advertise.
userPointer	A user pointer passed to NATResolver callbacks.
isAdvertised	Can be true or false indicating if the socket is advertised with a game server. If being used by TransportNATUDP this detects if AdvertiseClient is advertising a connection.
globalID	Must a globally unique number, for example a hash of the public IP address. If being used by TransportNATUDP this uses the advertised ID from AdvertiseClient or the currently logged in userID.
nonceID	Must be a locally unique number, for example the value from NOnceGen::GetNOnce() or the value of the socket pointer cast to an int. If being used by TransportNATUDP this uses the value from NOnceGen::GetNOnce().
externalHost	If true then this will attempt to ask an external server to help with resolving. The server is set by SetServer() or by default uses the RNLobby NATResolver server.
optionalHost	An optional host to contact to help with resolving.
persistant	Keeps the socket alive for longer in the NATResolver index.

bool BeginHosting ( t_XPSocket * socket )

Hosts a NATResolver server instance on this socket. The socket is automatically polled is SetAutomaticHostSocketReads(true) is used. If the NATResolver thread has not started then this calls Start() first.

bool BeginResolve	(	t_XPSocket *	socket,
		void *	userPointer,
		const bool	isAdvertised,
		const int	globalID,
		const int	sessionID,
		const int	nonceID,
		const bool	tryExternalHost = `true`,
		const XPAddress *	optionalHost = `0`,
		const XPAddress *	optionalFirstTargetTry = `0`
	)

Starts resolving a connection between this socket and the socket advertised with the set of identifying numbers (isAdvertised, globalID, nonceID). Either CallbackResolveFailed() or CallbackResolveResult() will be called. If the NATResolver thread has not started then this calls Start() first.

Parameters

socket	The socket to resolve.
userPointer	A user pointer passed to NATResolver callbacks.
isAdvertised	A value set by BeginAdvertise().
globalID	A value set by BeginAdvertise().
nonceID	A value set by BeginAdvertise().
tryExternalHost	If true then this will attempt to ask an external server to help with resolving. The server is set by SetServer() or by default uses the RNLobby NATResolver server.
optionalHost	An optional host to contact to help with resolving.
optionalFirstTargetTry	An optional address to try first, this could be the local LAN IP address.

bool CallbackParsePacketData	(	t_XPSocket *	socket,
		const XPAddress &	addr,
		void *	data,
		size_t	length
	)

The user may call this function when a packet is received on a socket that where NAT packets can potentially be received. For example, internally the NATUDP Transport uses a reliable UDP manager which calls a hook function, if it exists after is has been installed by RNLobby::RegisterDefaultTransports(), this function then calls CallbackParsePacketData() for any packets that arrive allowing the extension NATUDP transport to automatically NAT resolve without needed an explicit library dependancy between RNXPURL and RNLobby. If the NATResolver thread has not started then this calls Start() first.

Returns: True if the packet is a NAT packet, which implies the packet data doesn't need to be processed by the receiver.; False if the packet isn't a NAT packet.

virtual void CallbackResolveResult	(	t_XPSocket *	socket,
		void *	userPointer,
		const XPAddress &	targetAddress,
		const int	titleID,
		const bool	isAdvertised,
		const int	globalID,
		const int	sessionID,
		const int	nonceID
	)

virtual

A virtual callback that is triggered when a NAT resolve attempt succeeds. /param targetAddress The target address the socket can send packets to.

void SetAutomaticHostSocketReads ( const bool allow = false )

Allows the host socket set by BeginHosting to be automatically read and all packets received on that socket to be parsed. Also calls SetAutomaticThreadStop(false)

void SetEncryptionKey	(	const void *	data,
		const int	length
	)

Sets the encryption key to be used by all queries for this server.

Parameters

data	The data to use as a seed for the key. This can be NULL to use the default key.
length	The length of the data to use for creating the key.

void SetServer ( const XPAddress & address )

Sets the address and port of the server. The default for the instance of the class is localhost and port NATResolver::kDefaultPort or the address resolved by a successful BackendClient::Start().

Parameters

address The new address and port number to use for the server

bool Start ( void )

Starts the NAT resolver thread.

Returns: Success returns true, failure returns false.

bool Stop ( void )

Stops the NAT resolver thread.

Returns: Success returns true, failure returns false.

Public Types

Public Member Functions

Detailed Description

Member Function Documentation