This document expands on the README document - you should read that first.
-----------------------------------------------------------------------------

The Grapple Nat Traversal System is a system to allow games to be hosted on
computers that are on the inside of firewalls or NAT address pooling
systems.

-----------------------------------------------------------------------------
AN OVERVIEW OF THE PROBLEM

If you have, lets say three computers on your home network, all connected to
the internet through a router using NAT. This will mean that each of
your computers will connect to the outside world using the IP address of the
NAT router. This is fine, until you want to run a server to come into the
computer, like a game. If you start a game server, how will your router
know that people connecting to the IP address you have are trying to
go to your machine and not one of the other two machines in the house. To the
outside world, they are all the same.
When you start a connection, say to a webpage, the router knows how to respond
to the data being returned, from in this case the webserver, because it knows
that your computer was the one to connect to the webpage.
You can tell your router, when you set up a game, that connections to the game
should to to you.
However this is time consuming and most people have no idea how!

-----------------------------------------------------------------------------

Grapple's NAT traversal performs a series of tasks behind the scenes that
allows you to have connections from the outside go to your computer. This
ONLY currently works for UDP data.
It doesn't always work, some routers are set up to prevent NAT traversal,
and for that there is no current workaround (later versions of Grapple may
include a data relay, which will allow this feature). 

As an example, here is a simple demonstration of how this works.

Firstly, someone must set up a nattrav server. This must be on a computer
that has full unfiltered internet access, so not behind a firewall or NAT

SETTING UP A NATTRAV SERVER
---------------------------
The code to set up a server is simply:

server=grapple_server_init("testgame","1");
grapple_server_ip_set(server,"123.456.78.90");
grapple_server_port_set(server,1234);
grapple_server_protocol_set(server,GRAPPLE_PROTOCOL_UDP);
grapple_server_session_set(server,"Stun Server"); //Can be anything
grapple_server_set_as_nattrav_server(server,"123.456.78.91",1235,1236,1);
grapple_server_start(server);

This new line, grapple_server_set_as_nattrav_server should be explained.

Two different servers are needed for full NAT traversal. They need to be on
different IP addresses. This can be 2 IP addresses on one machine, or on two
separate machines. The 2nd and 3rd parameters passed into this function tells
one server where the second will be located. It should also be on a different
port number.
The 4th parameter is an extra portnumber that the server needs to be able to
fully perform NAT traversal. It can be anything, as long as it isn't the same
as the other ports, or the main port the server is bound to.

The final parameter is whether to enable the TURN protocol. TURN is a
last-ditch method of performing NAT traversal, but it has serious overhead
considerations and should be fully understood before enabling it. TURN is
described below.

So, now you have one server set up, you need to set up the second server, the
one mentioned in this ones setup

server2=grapple_server_init("notused","notused"); //These values are ignored
grapple_server_ip_set(server2,"123.456.78.91");
grapple_server_port_set(server2,1235);
grapple_server_protocol_set(server2,GRAPPLE_PROTOCOL_UDP);
grapple_server_session_set(server2,"Stun Server"); //Can be anything
grapple_server_set_as_nattrav_server(server2,"123.456.78.90",1234,1237);
grapple_server_start(server2);

This server is now pointing back at the first server so that the two can work
as a pair. Note that the parameters set in the function are the same address
as the first server.

That's it for the server. Leave those two running in a loop, and they will just
look after themselves.


SETTING UP A NATTRAV SERVER CLIENT
----------------------------------
Setting up a game server to be a nattrav client is even easier.

server=grapple_server_init("testgame","1.0");
grapple_server_ip_set(server,NULL);
grapple_server_port_set(server,3000);
grapple_server_protocol_set(server,GRAPPLE_PROTOCOL_UDP);
grapple_server_session_set(server,"My Game"); //Can be anything
grapple_server_nattrav_address(server,"123.456.78.90",1234);
grapple_server_start(server);


And that is all. Point the new line, grapple_server_nattrav_address, at either
of the two servers, it doesn't matter. Both act the same.

If, using this code, you printed out the result of
grapple_server_address_get() and grapple_server_port_get() you would see
the address that the rest of the world sees. If you didn't run this extra
line, then if you are behind a firewall or NAT, then there is pretty much no
way to know your address for people to connect to without fiddling
with your router.

Of course, how can you use this. You could have the game print its address 
onscreen and you can tell people the address, or you can use the grapple
lobby. The lobby is designed to connect people to the address that the server
shows it. When NAT Traversal has been used, this will be the address you
want people to see. If you are behind a NAT or Firewall, and connect to a
lobby without using NAT Traversal, you will not be able to let people join 
your game.

To take full advantage of NAT traversal, you must also tell each client where
the server is. At the same point in the negotiation, run

  grapple_client_nattrav_address(client,"87.117.204.74",1999);


If you are NOT behind a NAT or Firewall, then don't worry. You can use Grapple
NAT Traversal anyway, it will just know you are on an open internet
connection and not change anything. It doesn't hurt to use it if you
don't need it.

-----------------------------------------------------------------------------

Downsides to NAT Traversal.

There are a couple of downsides to consider when considering using NAT
Traversal. 

Firstly is that it takes a small amount of time (usually less than a second
but sometimes up to 4 or 5 seconds) longer to start your game, and for each
user to connect to it. Yes, this is a problem but, it prevents the situation
where nobody at all can connect to it ever.

Secondly, is that you need to host two Nat Traversal Servers somewhere. This
is often a difficult problem for people with limited resources. It is common
for the people that make a game that uses NAT Traversal to host the
server for it. Not all game developers will be able to though.

-----------------------------------------------------------------------------
The TURN protocol

TURN is a great way to get round almost any NAT traversal problems. However 
it has a serious downside in that the NAT Traversal Server you have created
will have to relay every single bit of data between the server, and the
TURN requiring clients.

This can lead to enormous bandwidth overheads, and so TURN is enabled
separately from other protocols.

TURN is always used as a last ditch connection method. Only after STUN
and reverse STUN have both failed, will TURN be used.

-----------------------------------------------------------------------------

The technical bit

Currently Grapple's NAT Traversal system implements a version of the STUN
protocol.