server.onunexpecteddisconnect(callback)

Description

This method nominates a function to be called if the device is unexpectedly disconnected from the server, but only if the imp has been set to a timeout policy of RETURN_ON_ERROR. If the SUSPEND_ON_ERROR timeout policy is in force, the callback will not be executed when the imp unexpectedly disconnects from the server.

Upon a loss of connectivity, impOS™ immediately attempts to reconnect. Only if the connection is not restored within 60 seconds, is the callback function registered using server.onunexpecteddisconnect() triggered. If the connection is restored within this timeout period, the callback function is not executed. This procedure is followed to ensure that only true outages, not, for example, momentary dips in WiFi signal, trigger the callback.

The function passed into the callback parameter should include a single parameter of its own: reason. This will be passed an integer specifying the reason for the disconnection, whether known or not. The value will be one of the following constants:

The values assigned to the constants may change in a future impOS release.

The callback can be used to perform state-related operations, such as lighting an LED to warn the end-user that the device is not connected. Under the RETURN_ON_ERROR policy, it is up to your application to re-establish a connection to the server. This is typically performed within the callback and actioned by calling server.connect() either immediately or after a short interval appropriate to the application.

Because the callbacks registered with server.connect() and server.onunexpecteddisconnect() take a single integer reason as a parameter, it is commonplace (but not mandatory) to use these methods to register the same callback function, as the example below shows.

• For more information on managing planned disconnections and dealing with unexpected breaks in connectivity, such as WiFi loss, see the guide How To Run An imp-enabled Device Offline.

• For sample code that can be used to manage sudden losses of connectivity, see the imp API Cookbook recipe Unexpected Device Disconnections.

Known Issue

In certain rare circumstances, the function registered with server.onunexpecteddisconnect() may be called twice. For example, if the imp is connected to a WiFi access point that communicates with a router via Ethernet, and the connection between the access point and router is lost, the loss of Internet access will trigger the server.onunexpecteddisconnect()-registered function as described above. However, because is still connected by WiFi, it will attempt to reconnect and when this fails, the server.onunexpecteddisconnect()-registered function will be called again.

One workaround is to set a flag on the first pass through the disconnection handler according to the reason supplied. If the handler is shortly called again with with the same reason and the flag is set, the handler can simply return. Using the example above, we might use:

function disconnectionHandler(reason) {
    // Called if the server connection is broken or re-established, initially by impOS' unexpected disconnect
    // code and then repeatedly by server.connect(), below, as it periodically attempts to reconnect
    if (reason == NO_IP_ADDRESS) {
        if (noIPAddressFlag) return;
        noIPAddressFlag = true;
    }

    if (reason != SERVER_CONNECTED) {
        isConnected = false;

        // Schedule an attempt to re-connect in 'reconnectDelay' seconds
        imp.wakeup(60, function() {
            server.connect(disconnectionHandler, 30);
        });
    } else {
        // The imp is back online - reset state data
        isConnected = true;
        noIPAddressFlag = false;
    }
}