Index by title

API Reference

    class NatTest
    {
        public Start ()
        {
            // Hook into the events so you know when a router has been detected or has gone offline
            NatUtility.DeviceFound += DeviceFound;
            NatUtility.DeviceLost += DeviceLost;

            // Start searching for upnp enabled routers
            NatUtility.StartDiscovery ();
        }

        void DeviceFound(object sender, DeviceEventArgs args)
        {
            // This is the upnp enabled router
            INatDevice device = args.Device;

            // Create a mapping to forward external port 3000 to local port 1500
            device.CreatePortMap(new Mapping(Protocol.Tcp, 1500, 3000));

            // Retrieve the details for the port map for external port 3000
            Mapping m = device.GetSpecificMapping(Protocol.Tcp, 3000);

            // Get all the port mappings on the device and delete them
            foreach (Mapping mp in device.GetAllMappings())
                device.DeletePortMap(mp);

            // Get the external IP address
            IPAddress externalIP = device.GetExternalIP();
        }

        private void DeviceLost (object sender, DeviceEventArgs args)
        {
            INatDevice device = args.Device;

            Console.WriteLine ("Device Lost");
            Console.WriteLine ("Type: {0}", device.GetType().Name);
        }
    }

Debugging the reason why your router cannot be found

The uPnP specification is (generally speaking) badly implemented by a lot of router vendors. There are so many different quirks that I've come across that it's very hard to say whether or not a specific router will work with Mono.Nat. For the cases where your router does not work, here's how to debug the issue.

If you are unable to debug the issue yourself, if you attach the verbose output of Mono.Nat to an email and send it to me, I should be able to offer some suggestions to get your device working.

Step 0: Enabling debug output

If you're running in a console application you can print debug information straight to the screen:

NatUtility.Logger = Console.Out;

If you want to log to a file, it's just as easy:

NatUtility.Logger = new StreamWriter (File.OpenWrite ("logfile.txt"));

If you fail to get past step 1 below, or just want all the debug output, you should enable verbose mode:

NatUtility.Verbose = true

Step 1: Detecting available services

In order to detect what services are available on the local network, a udp broadcast message is sent. There are two kinds of message:
  1. The 'tell me everything you support' message
  2. The 'respond if you support service X' message

Mono.Nat uses the 'tell me everything you support' style message. I haven't come across a router which has failed to respond to this, though there are some which fail to respond to the second type of message. If your router fails at this step, then this is probably why. Typical output from this step is a dozen or so copies of the following:

UPnP Response: HTTP/1.1 200 OK
SERVER: Ambit OS/1.0 UPnP/1.0 AMBIT-UPNP/1.0
EXT:
LOCATION: http://192.168.0.10:80/Public_UPNP_gatedesc.xml
CACHE-CONTROL: max-age=3600
ST: upnp:rootdevice
USN: uuid:e346a71d-99ef-86a6-3222-e9ba2bb3dfa0::upnp:rootdevice

UPnP Response: HTTP/1.1 200 OK
SERVER: Ambit OS/1.0 UPnP/1.0 AMBIT-UPNP/1.0
EXT:
LOCATION: http://192.168.0.10:80/Public_UPNP_gatedesc.xml
CACHE-CONTROL: max-age=3600
ST: urn:schemas-upnp-org:device:InternetGatewayDevice:1
USN: uuid:e346a71d-99ef-86a6-3222-e9ba2bb3dfa0::urn:schemas-upnp-org:device:InternetGatewayDevice:1

Step 2: Getting the service listing

If your router advertises one of the three services that Mono.Nat assumes will allow port forwarding, you will see output similar to this:

UPnP Response: Router advertised a 'urn:schemas-upnp-org:service:WANIPConnection:' service
Found device at: http://192.168.0.10:80/Public_UPNP_gatedesc.xml
Parsed device as: 192.168.0.10:80
Fetching service list: 192.168.0.10:80

Step 3: Parsing a service listing

The service listing contains the details required to connect to the upnp service on the router. If the listing can be retrieved and parsed, you'll see output similar to this:

192.168.0.10:80: Parsed services list
192.168.0.10:80: Found service: urn:schemas-upnp-org:service:Layer3Forwarding:1
192.168.0.10:80: Found service: urn:schemas-upnp-org:service:WANCommonInterfaceConfig:1
192.168.0.10:80: Found service: urn:schemas-upnp-org:service:WANIPConnection:1
192.168.0.10:80: Found upnp service at: /Public_UPNP_C3
192.168.0.10:80: Assuming control Uri is relative: /Public_UPNP_C3
192.168.0.10:80: Handshake Complete

Step 4: Your device has been found

Once the control Uri has been discovered, you will be passed the device via the DeviceFound event. You should store this object locally to avoid the time consuming process of detection every time you want to use it. Steps 1 - 4 can take anywhere between a few hundred milliseconds to 30 seconds to complete, though usually they will take less than 5 seconds.

Some routers will not support all the available methods. For example not all routers will support listing all the existing mappings, others may not support retrieving the external ip address. If calling these methods throws an exception, it's not necessarily a Mono.Nat bug. However, sometimes it might be possible to work around the issue by applying a device-specific fix. If a method is failing for you but you think your router should support it, send me the exception and stacktrace and I'll see what I can do.

Submitting patches so your router works without modifications

If your router requires a fix to be detected with Mono.Nat, please let me know and supply a patch with the required changes. I'll gladly incorporate any changes which increase compatibility with different router models.


Main page

API Reference

Debugging the reason why your router cannot be found