File netcheck.lua

NetCheck provides functions to detect changes in network connectivity. This module will create no global, it returns the netcheck table with the defined functions (see below).
 
NetCheck is free software under the MIT/X11 license.

Copyright ©2011 Thijs Schreijer

Release: Version 0.1.0, NetCheck to detect network connection changes

Functions

netcheck.check (oldState) Checks the network connection of the system and detects changes in connection or IP adress.
netcheck.getchecker () Wraps the check function in a single function.

Tables

networkstate State table with network parameters retrieved and used for comparison to detect changes.


Functions

netcheck.check (oldState)
Checks the network connection of the system and detects changes in connection or IP adress. Call repeatedly to check status for changes. With every call include the previous results to compare with.

Parameters:

  • oldState: (table) previous result (networkstate-table) to compare with, or nil if not called before

Usage:

    local netcheck = require("netcheck")
    function test()
        print ("TEST: entering endless check loop, change connection settings and watch the changes come in...")
        require ("base") -- from stdlib to pretty print the table
        local change, data
        while true do
            change, data = netcheck.check(data)
            if change then
                print (prettytostring(data))
            end
        end
    end

Return values:

  1. changed (boolean) same as newstate.changed
  2. newState (table) networkstate-table

See also:

netcheck.getchecker ()
Wraps the check function in a single function. By wrapping it and creating an upvalue for the oldState parameter, the result can be called directly for changes.

Usage:

    -- create function
    local do_check = require("netcheck").getchecker()
     
    -- watch for changes, short version
    while true do
        if do_check() then
            print ("Network connection changed!")
        end
    end
     
    -- alternative, to find out what changed...
    while true do
        local changed, newState, oldState = do_check()
        if changed then
            print ("Network connection changed!")
            -- here you can compare oldState with newState to find out exactly what changed
        end
    end

Return value:

    function that can be used to detect changes. This function takes no parameters and returns three values when called;
    1. changed (boolean) indicating whether there was a change (same as newState.changed)
    2. newState (table) current check result (see networkstate)
    3. oldState (table) previous check result (see networkstate)

See also:

Tables

networkstate
State table with network parameters retrieved and used for comparison to detect changes. The table contains the same regular info from socket.dns calls (see luasocket documentation), but extended with the following fields;

Fields:

  • localhostname: (string) name of localhost (only field that can be set, defaults to 'localhost')
  • localhostip: (string) ip address resolved for localhostname
  • connected: (string) either 'yes', 'no', or 'loopback' (loopback means connected to localhost, no external connection)
  • changed: (boolean) true if comparison done was different on either; name, connected, or ip[1] properties

Valid XHTML 1.0!