# hs.network.reachability

This sub-module can be used to determine the reachability of a target host. A remote host is considered reachable when a data packet, sent by an application into the network stack, can leave the local device. Reachability does not guarantee that the data packet will actually be received by the host.

It is important to remember that this module works by determining if the computer has a route for network traffic bound to a specific destination. An active internet connection provides a default route for any network that the host is not a member of, so care must be used when testing for specific VPN or local networks to avoid false positives. Some examples follow:

This is a simple watcher which will be invoked whenever the computer's active internet connection changes state:

    hs.network.reachability.internet():setCallback(function(self, flags)
        if (flags & hs.network.reachability.flags.reachable) > 0 then
            -- a default route exists, so an active internet connection is present
        else
            -- no default route exists, so no active internet connection is present
        end
   end):start()

Note that when an active internet connection is up (reachable), any specific network test that does not include an address pair will be reachable, since internet reachability is defined as having a default route for all non-local networks.

A specific test for determining if an OpenVPN network is available. This example requires knowing what the local computer's IP address on the VPN network is (OpenVPN does not set the isDirect flag) and has been tested with Tunnelblick.

    hs.network.reachability.forAddress("10.x.y.z"):setCallback(function(self, flags)
        -- note that because having an internet connection at all will show the remote network
        -- as "reachable", we instead look at whether or not our specific address is "local" instead
        if (flags & hs.network.reachability.flags.isLocalAddress) > 0 then
            -- VPN tunnel is up
        else
            -- VPN tunnel is down
        end
   end):start()

Constants - Useful values which cannot be changed

• flags

Constructors - API calls which return an object, typically one that offers API methods

• forAddress
• forAddressPair
• forHostName
• internet
• linkLocal

Methods - API calls which can only be made on an object returned by a constructor

• setCallback
• start
• status
• statusString
• stop