NetStumbler Scripting Guide

To use scripting in NetStumbler, you should be fluent in a scripting language that supports Active Scripting on the Windows platform. Examples of such languages are VBScript and JScript, which are available on most Windows platforms; others you might consider are PerlScript and Python, available from ActiveState.

Functions called by the application

OnEnableScan

Arguments

None.

Description

This is called when the user requests that scanning be started.

OnDisableScan

Arguments

None.

Description

This is called when the user requests that scanning be stopped.

OnScanComplete

Arguments

  1. FoundNew (Integer) - the number of networks that were discovered that did not already exist in the current scan document.
  2. SeenBefore (Integer) - the number of networks that were found but already exist in the current scan document.
  3. LostContact (Integer) - the number of networks that were found in the last scan, but did not respond in this one.
  4. BestSNR (Integer) - the highest detected signal-to-noise ratio, in units provided by the card. Usually this is in dB but some cards use their own arbitrary units.

Description

This is called when all of the results from the current scan have been processed.

OnScanResult

Arguments

  1. SSID (String) - the SSID (Network name)
  2. BSSID (String) - the BSSID (MAC address)
  3. CapFlags (Integer) - 802.11 capability flags
  4. Signal (Integer) - signal level, in units provided by the hardware. This may be dBm or arbitrary units of RSSI.
  5. Noise (Integer) - noise level, if the hardware reported it. Usually this is in dBm.
  6. LastSeen (Time) - When this BSSID was last seen

Description

This is called just after the application has received all scan results. It is called once for each item that was found. Since this is called frequently while scanning, the script should not perform complex operations that might take a long time to complete.

OnScanStart

Arguments

None.

Description

This is called just before the application initiates a scan.

OnGPSTimeout

Arguments

None.

Description

This is called when the GPS is not responding, most typically because it is unplugged or configured incorrectly. For most GPS protocols, this will be called once every few seconds.

OnGPSNoFix

Arguments

None.

Description

This is called when the GPS indicates that it is unable to provide a position fix. Usually this is caused by poor satellite visibility.

OnGPSPosition

Arguments

  1. Latitude (Double) - Current latitude in degrees. North is positive, South is negative.
  2. Longitude (Double) - Current longitude in degrees. East is positive, West is negative.
  3. Altitude (Double) - Current altitude above mean sea level in meters.

Description

This is called when the GPS indicates the current position.

OnGPSSpeed

This is called when the GPS indicates the current speed.

Arguments

  1. Speed (Double) - Current speed in knots.

OnIPChange

Called while scanning only when the IP address is reported to be changed. The IP address reported is the first one on the currently scanning adapter. NOTE: There are a number of cases where this function will get called but the IP address has not really changed - for example, the address changed on another adapter, or the IP routing or DNS information changed.

Arguments

  1. Addr (String) - New IP address, dotted format
  2. Mask (String) - New IP subnet mask, dotted format

OnPositionChange

Called to indicate that NetStumbler has changed its location information for a BSSID.

NOTE: A BSSID's location is currently determined to be the location where the strongest signal was seen, which is almost never the actual location. It is likely that a future version of NetStumbler will perform some postprocessing on results, which will make it possible for OnPositionChange to be called long after the BSSID was seen, unlike the current behavior.

Arguments

  1. SSID : String : SSID (Network name)
  2. BSSID : String : BSSID (MAC address)
  3. CapFlags : Integer : 802.11 capability flags
  4. MaxSNR: Integer : highest seen signal-to-noise ratio (dB) that had a position fix associated with it
  5. Lat : Double : Newly calculated latitude, degrees
  6. Lon : Double : Newly calculated longitude, degrees
  7. Alt : Double : Newly calculated altitude (currently not calculated)
  8. FixType : Integer : Reserved for future use

Functions provided by the application

In addition to the standard runtime provided by the scripting host, the application makes some additional functions available for use by scripts.

AddItemContextMenu

Arguments

  1. Callback (String) - Function to be called when menu item is selected
  2. MenuItem (String) - Text to appear on menu item

Description

Adds a custom item to the popup context menu for all networks. If the user selects this menu item, the named callback in the script is called with the BSSID and SSID of the network.

Example

Let us suppose you have custom VBScript that contains the following:

Sub LaserCallback (bssid, ssid)

  If Robot Is Nothing Then Set Robot = CreateObject("Skynet.T9000")

  Robot.PointLaserAt(bssid)

  Robot.Say "Hasta la vista, " & ssid

  Robot.FireLaser

End Sub

 

AddItemContextMenu "LaserCallback", "Fire Laser"

 

The last line of code registers the callback with NetStumbler. After this executes, every network's context menu will include an item labelled "Fire Laser". When selected, this menu item will cause the network's BSSID and SSID to be passed to "LaserCallback", which executes the custom code shown.

PlaySound

Arguments

  1. Sound (String)

Return Value

Boolean value indicating whether the operation succeeded. True indicates success, False indicates failure.

Description

Plays the requested sound file.

Internally, this calls the Win32 PlaySound API function with  hModule = Null and fdwSound = SND_ASYNC | SND_NODEFAULT.

PlaySoundLoop

Arguments

  1. Sound (String)

Return Value

Boolean value indicating whether the operation succeeded. True indicates success, False indicates failure.

Description

Plays the requested sound file repeatedly. To stop playback, call the function again, passing an empty string.

Internally, this calls the Win32 PlaySound API function with  hModule = Null and fdwSound = SND_ASYNC | SND_NODEFAULT | SND_LOOP.