Network.TestConnection

Description

Test this machines network connection.

Two types of tests are performed depending on if the machine has a public IP address present or if it only has a private address (or addresses).

The public IP address test is primarily for when running a server as no tests are needed for clients with public addresses. In order for the public IP test to succeed a server instance must be started. A test server will try to connect to the IP and port of the local server and thus it is shown in the server is connectable. If not then a firewall is most likely blocking the server port. A server instance needs to be running so that the test server has something to connect to.

The other test is for checking NAT punchthrough capabilities. This is a valid test for both servers and clients and can be performed without any prior setup. There are 4 types of NAT test results (see ConnectionTesterStatus): __Full Cone_, Address Restricted Cone, Port restricted and Symmetric.

First two types offer full NAT punchthrough support and can connect to any type. Port restricted type cannot connect to or receive a connection from symmetric type. Symmetric if worst and cannot connect to other symmetric types or port restricted type. The latter two are labelled as offering limited NAT punchthrough support.

This function is asynchronous and might not return a valid result right away because the tests needs some time to complete (1-2 seconds). After test completion the test result is only returned when the function is called again, a full network test is not redone. That way it is safe to poll the function frequently. If another test is desired, like if the network connection has been altered, then the forceTest parameter should be passed as true.

The function returns a ConnectionTesterStatus enum.

var testStatus = "Testing network connection capabilities.";
var testMessage = "Test in progress";
var shouldEnableNatMessage : String = "";
var doneTesting = false;
var probingPublicIP = false;
var serverPort = 9999;
var connectionTestResult = ConnectionTesterStatus.Undetermined;

// Indicates if the useNat parameter be enabled when starting a server
var useNat = false;

function OnGUI() {
    GUILayout.Label("Current Status: " + testStatus);
    GUILayout.Label("Test result : " + testMessage);
    GUILayout.Label(shouldEnableNatMessage);
    if (!doneTesting)
        TestConnection();
}

function TestConnection() {
    // Start/Poll the connection test, report the results in a label and
    // react to the results accordingly
    connectionTestResult = Network.TestConnection();
    switch (connectionTestResult) {
        case ConnectionTesterStatus.Error:
            testMessage = "Problem determining NAT capabilities";
            doneTesting = true;
            break;

        case ConnectionTesterStatus.Undetermined:
            testMessage = "Undetermined NAT capabilities";
            doneTesting = false;
            break;

        case ConnectionTesterStatus.PublicIPIsConnectable:
            testMessage = "Directly connectable public IP address.";
            useNat = false;
            doneTesting = true;
            break;

        // This case is a bit special as we now need to check if we can
        // circumvent the blocking by using NAT punchthrough
        case ConnectionTesterStatus.PublicIPPortBlocked:
            testMessage = "Non-connectable public IP address (port " +
                serverPort +" blocked), running a server is impossible.";
            useNat = false;
            // If no NAT punchthrough test has been performed on this public
            // IP, force a test
            if (!probingPublicIP) {
                connectionTestResult = Network.TestConnectionNAT();
                probingPublicIP = true;
                testStatus = "Testing if blocked public IP can be circumvented";
                timer = Time.time + 10;
            }
            // NAT punchthrough test was performed but we still get blocked
            else if (Time.time > timer) {
                probingPublicIP = false;        // reset
                useNat = true;
                doneTesting = true;
            }
            break;
        case ConnectionTesterStatus.PublicIPNoServerStarted:
            testMessage = "Public IP address but server not initialized, "+
                "it must be started to check server accessibility. Restart "+
                "connection test when ready.";
            break;

        case ConnectionTesterStatus.LimitedNATPunchthroughPortRestricted:
            testMessage = "Limited NAT punchthrough capabilities. Cannot "+
                "connect to all types of NAT servers. Running a server "+
                "is ill advised as not everyone can connect.";
            useNat = true;
            doneTesting = true;
            break;

        case ConnectionTesterStatus.LimitedNATPunchthroughSymmetric:
            testMessage = "Limited NAT punchthrough capabilities. Cannot "+
                "connect to all types of NAT servers. Running a server "+
                "is ill advised as not everyone can connect.";
            useNat = true;
            doneTesting = true;
            break;

        case ConnectionTesterStatus.NATpunchthroughAddressRestrictedCone:
        case ConnectionTesterStatus.NATpunchthroughFullCone:
            testMessage = "NAT punchthrough capable. Can connect to all "+
                "servers and receive connections from all clients. Enabling "+
                "NAT punchthrough functionality.";
            useNat = true;
            doneTesting = true;
            break;

        default:
            testMessage = "Error in test routine, got " + connectionTestResult;
    }
    if (doneTesting) {
        if (useNat)
            shouldEnableNatMessage = "When starting a server the NAT "+
                "punchthrough feature should be enabled (useNat parameter)";
        else
            shouldEnableNatMessage = "NAT punchthrough not needed";
        testStatus = "Done testing";
    }
}]></code>
        </example>
        <description>If you know both server and client NAT types you could use the following function to determine if the client can connect to the server or not.</description>
        <example>
          <code lang="js"><![CDATA[
    function CanConnectTo(type1: ConnectionTesterStatus, type2: ConnectionTesterStatus) : boolean
    {
        if (type1 == ConnectionTesterStatus.LimitedNATPunchthroughPortRestricted &&
            type2 == ConnectionTesterStatus.LimitedNATPunchthroughSymmetric)
            return false;
        else if (type1 == ConnectionTesterStatus.LimitedNATPunchthroughSymmetric &&
            type2 == ConnectionTesterStatus.LimitedNATPunchthroughPortRestricted)
            return false;
        else if (type1 == ConnectionTesterStatus.LimitedNATPunchthroughSymmetric &&
            type2 == ConnectionTesterStatus.LimitedNATPunchthroughSymmetric)
            return false;
        return true;
    }

using UnityEngine;
using System.Collections;

public class ExampleClass : MonoBehaviour
{
    string testStatus = "Testing network connection capabilities.";
    string testMessage = "Test in progress";
    string shouldEnableNatMessage  = "";
    bool doneTesting = false;
    bool probingPublicIP = false;
    int serverPort = 9999;
    bool useNat = false;
    float timer = 0.0f;

    ConnectionTesterStatus connectionTestResult = ConnectionTesterStatus.Undetermined;

    void OnGUI()
    {
        GUILayout.Label("Current Status: " + testStatus);
        GUILayout.Label("Test result : " + testMessage);
        GUILayout.Label(shouldEnableNatMessage);

        if (!doneTesting)
            TestConnection();
    }

    void TestConnection()
    {
        // Start/Poll the connection test, report the results in a label and
        // react to the results accordingly
        connectionTestResult = Network.TestConnection();
        switch (connectionTestResult)
        {
            case ConnectionTesterStatus.Error:
                testMessage = "Problem determining NAT capabilities";
                doneTesting = true;
                break;

            case ConnectionTesterStatus.Undetermined:
                testMessage = "Undetermined NAT capabilities";
                doneTesting = false;
                break;

            case ConnectionTesterStatus.PublicIPIsConnectable:
                testMessage = "Directly connectable public IP address.";
                useNat = false;
                doneTesting = true;
                break;

            // This case is a bit special as we now need to check if we can
            // circumvent the blocking by using NAT punchthrough
            case ConnectionTesterStatus.PublicIPPortBlocked:
                testMessage = "Non-connectable public IP address (port " +
                    serverPort + " blocked), running a server is impossible.";
                useNat = false;
                // If no NAT punchthrough test has been performed on this public
                // IP, force a test
                if (!probingPublicIP)
                {
                    connectionTestResult = Network.TestConnectionNAT();
                    probingPublicIP = true;
                    testStatus = "Testing if blocked public IP can be circumvented";
                    timer = Time.time + 10;
                }
                // NAT punchthrough test was performed but we still get blocked
                else if (Time.time > timer)
                {
                    probingPublicIP = false;        // reset
                    useNat = true;
                    doneTesting = true;
                }
                break;

            case ConnectionTesterStatus.PublicIPNoServerStarted:
                testMessage = "Public IP address but server not initialized, " +
                    "it must be started to check server accessibility. Restart " +
                    "connection test when ready.";
                break;

            case ConnectionTesterStatus.LimitedNATPunchthroughPortRestricted:
                testMessage = "Limited NAT punchthrough capabilities. Cannot " +
                    "connect to all types of NAT servers. Running a server " +
                    "is ill advised as not everyone can connect.";
                useNat = true;
                doneTesting = true;
                break;

            case ConnectionTesterStatus.LimitedNATPunchthroughSymmetric:
                testMessage = "Limited NAT punchthrough capabilities. Cannot " +
                    "connect to all types of NAT servers. Running a server " +
                    "is ill advised as not everyone can connect.";
                useNat = true;
                doneTesting = true;
                break;

            case ConnectionTesterStatus.NATpunchthroughAddressRestrictedCone:
            case ConnectionTesterStatus.NATpunchthroughFullCone:
                testMessage = "NAT punchthrough capable. Can connect to all " +
                    "servers and receive connections from all clients. Enabling " +
                    "NAT punchthrough functionality.";
                useNat = true;
                doneTesting = true;
                break;

            default:
                testMessage = "Error in test routine, got " + connectionTestResult;
                break;
        }

        if (doneTesting)
        {
            if (useNat)
                shouldEnableNatMessage = "When starting a server the NAT " +
                    "punchthrough feature should be enabled (useNat parameter)";
            else
                shouldEnableNatMessage = "NAT punchthrough not needed";
            testStatus = "Done testing";
        }
    }
}