# hs.wifi.watcher

Watch for changes to the associated wifi network

# API Overview

Constants - Useful values which cannot be changed

eventTypes

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

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

start
stop
watchingFor

# API Documentation

# Constants

# eventTypes


Signature	`hs.wifi.watcher.eventTypes[]`
Type	Constant
Description	A table containing the possible event types that this watcher can monitor for.
Notes	The following events are available for monitoring: "SSIDChange" - monitor when the associated network for the Wi-Fi interface changes "BSSIDChange" - monitor when the base station the Wi-Fi interface is connected to changes "countryCodeChange" - monitor when the adopted country code of the Wi-Fi interface changes "linkChange" - monitor when the link state for the Wi-Fi interface changes "linkQualityChange" - monitor when the RSSI or transmit rate for the Wi-Fi interface changes "modeChange" - monitor when the operating mode of the Wi-Fi interface changes "powerChange" - monitor when the power state of the Wi-Fi interface changes "scanCacheUpdated" - monitor when the scan cache of the Wi-Fi interface is updated with new information
Source	extensions/wifi/libwifi_watcher.m line 364

# Constructors

# new


Signature	`hs.wifi.watcher.new(fn) -> watcher`
Type	Constructor
Description	Creates a new watcher for WiFi network events
Parameters	fn - A function that will be called when a WiFi event that is being monitored occurs. The function should expect 2 or 4 arguments as described in the notes below.
Returns	A `hs.wifi.watcher` object
Notes	For backwards compatibility, only "SSIDChange" is watched for by default, so existing code can continue to ignore the callback function arguments unless you add or change events with the hs.wifi.watcher:watchingFor. The callback function should expect between 3 and 5 arguments, depending upon the events being watched. The possible arguments are as follows: `watcher`, "SSIDChange", `interface` - occurs when the associated network for the Wi-Fi interface changes `watcher` - the watcher object itself `message` - the message specifying the event, in this case "SSIDChange" `interface` - the name of the interface for which the event occurred Use `hs.wifi.currentNetwork([interface])` to identify the new network, which may be nil when you leave a network. `watcher`, "BSSIDChange", `interface` - occurs when the base station the Wi-Fi interface is connected to changes `watcher` - the watcher object itself `message` - the message specifying the event, in this case "BSSIDChange" `interface` - the name of the interface for which the event occurred `watcher`, "countryCodeChange", `interface` - occurs when the adopted country code of the Wi-Fi interface changes `watcher` - the watcher object itself `message` - the message specifying the event, in this case "countryCodeChange" `interface` - the name of the interface for which the event occurred `watcher`, "linkChange", `interface` - occurs when the link state for the Wi-Fi interface changes `watcher` - the watcher object itself `message` - the message specifying the event, in this case "linkChange" `interface` - the name of the interface for which the event occurred `watcher`, "linkQualityChange", `interface` - occurs when the RSSI or transmit rate for the Wi-Fi interface changes `watcher` - the watcher object itself `message` - the message specifying the event, in this case "linkQualityChange" `interface` - the name of the interface for which the event occurred `rssi` - the RSSI value for the currently associated network on the Wi-Fi interface `rate` - the transmit rate for the currently associated network on the Wi-Fi interface `watcher`, "modeChange", `interface` - occurs when the operating mode of the Wi-Fi interface changes `watcher` - the watcher object itself `message` - the message specifying the event, in this case "modeChange" `interface` - the name of the interface for which the event occurred `watcher`, "powerChange", `interface` - occurs when the power state of the Wi-Fi interface changes `watcher` - the watcher object itself `message` - the message specifying the event, in this case "powerChange" `interface` - the name of the interface for which the event occurred `watcher`, "scanCacheUpdated", `interface` - occurs when the scan cache of the Wi-Fi interface is updated with new information `watcher` - the watcher object itself `message` - the message specifying the event, in this case "scanCacheUpdated" `interface` - the name of the interface for which the event occurred
Examples	None
Source	extensions/wifi/libwifi_watcher.m line 215

# Methods

# start


Signature	`hs.wifi.watcher:start() -> watcher`
Type	Method
Description	Starts the SSID watcher
Parameters	None
Returns	The `hs.wifi.watcher` object
Notes	None
Examples	None
Source	extensions/wifi/libwifi_watcher.m line 282

# stop


Signature	`hs.wifi.watcher:stop() -> watcher`
Type	Method
Description	Stops the SSID watcher
Parameters	None
Returns	The `hs.wifi.watcher` object
Notes	None
Examples	None
Source	extensions/wifi/libwifi_watcher.m line 300

# watchingFor


Signature	`hs.wifi.watcher:watchingFor([messages]) -> watcher \| current-value`
Type	Method
Description	Get or set the specific types of wifi events to generate a callback for with this watcher.
Parameters	`messages` - an optional table of or list of strings specifying the types of events this watcher should invoke a callback for. You can specify multiple types of events to watch for. Defaults to `{ "SSIDChange" }`.
Returns	if a value is provided, returns the watcher object; otherwise returns the current values as a table of strings.
Notes	the possible values for this method are described in hs.wifi.watcher.eventTypes. the special string "all" specifies that all event types should be watched for.
Examples	None
Source	extensions/wifi/libwifi_watcher.m line 318