netwatch

README

NetWatch

A network interface watcher for windows

What is this?

Does your app need to know when a network interface connects? When it disconnects? Maybe you need to do things when an IP address changes? Does your app run on windows? Well I think this library might be for you.

This library also includes some useful network utilities, such as listing all interfaces that satisfy a specific set of flags, or getting the IPv4 address of a given interface

How do I use this?

First you'll want to grab this library

go get github.com/mbaklor/netwatch

next you probably want an app that needs this functionality, here's a simple demo

package main

import (
	"errors"
	"fmt"
	"time"

	"github.com/mbaklor/netwatch"
)

func main() {
	// Create a network monitor
	nm := netwatch.NewNetMonitor()

	// we need to register our monitor to hook into OS notifications
	// passing in true will request a notification to fire when we register, to indicate everything is working
	err := nm.Register(true)
	if err != nil {
		// we need to clean up in case one of the calls in Register succeeded and the other failed
		err1 := nm.Unregister()
		panic(errors.Join(err, err1))
	}

	// now we listen for notifications for the next 10 seconds, before finally unregistering and exiting the program
	for {
		select {
		case n := <-nm.MonitorNotificationChan:
			fmt.Println(n)
		case <-time.After(time.Second * 10):
			fmt.Println("Done")
			err := nm.Unregister()
			if err != nil {
				fmt.Println("error unregistering", err)
			}
			return
		}
	}
}

Roadmap

I don't know if I'll ever end up taking the time to add cross platform compatibility, but it's on the list of things I'd like to do, so:

• MacOS
• Linux

Documentation

Index

• func GetInterfaceIPv4Addr(ifi net.Interface) (net.IP, error)
• func InterfaceCount() (int, error)
• type CallerContext
  • func (cc CallerContext) String() string
• type MibNotificationType
  • func (mnt MibNotificationType) String() string
• type MonitorNotification
• type NetAddr
  • func AllInterfaces() ([]NetAddr, error)
  • func InterfaceList(includeFlags, excludeFlags net.Flags) ([]NetAddr, error)
• type NetMonitor
  • func NewNetMonitor() *NetMonitor
  • func (nm *NetMonitor) Register(initialNotification bool) error
  • func (nm *NetMonitor) Unregister() error

Functions

func GetInterfaceIPv4Addr

func GetInterfaceIPv4Addr(ifi net.Interface) (net.IP, error)

Gets the net.IP as IPv4 of a specified network interface

func InterfaceCount

func InterfaceCount() (int, error)

Returns the number of network interfaces available on the machine

Types

type CallerContext

type CallerContext uint8

Indicates what callback was called in the notification

const (
	CONTEXT_NOTIFY_IP_INTERFACE_CHANGE CallerContext = iota
	CONTEXT_NOTIFY_UNICAST_IP_ADDRESS_CHANGE
)

func (CallerContext) String

func (cc CallerContext) String() string

type MibNotificationType

type MibNotificationType uint8

The MIB_NOTIFICATION_TYPE enumeration type defines the notification type that is passed to a callback function when a notification occurs.

const (
	// A parameter was changed.
	MIB_PARAMETER_NOTIFICATION MibNotificationType = iota
	// A new MIB instance was added.
	MIB_ADD_INSTANCE
	// A new MIB instance was added.
	MIB_DELETE_INSTANCE
	// A notification that is invoked immediately after registration for change notification completes.
	// This initial notification does not indicate that a change occurred to a MIB instance.
	// The purpose of this initial notification type is to provide confirmation that the callback function is properly registered.
	MIB_INITIAL_NOTIFICATION
)

func (MibNotificationType) String

func (mnt MibNotificationType) String() string

type MonitorNotification

type MonitorNotification struct {
	CallerContext    CallerContext
	NotificationType MibNotificationType
	InterfaceIndex   int
	InterfaceAddress net.IP
}

type NetAddr

type NetAddr struct {
	Index int
	Name  string
	IP    net.IP
}

NetAddr represents a network interface with an index, a name and an IP

func AllInterfaces

func AllInterfaces() ([]NetAddr, error)

Returns a list of all network interfaces as []NetAddr without any filtering

func InterfaceList

func InterfaceList(includeFlags, excludeFlags net.Flags) ([]NetAddr, error)

Returns a list of network interfaces as []NetAddr filtering them by includeFlags and excludeFlags

a common includeFlags is net.FlagRunning to only get the enabled interfaces, and a common excludeFlags is net.FlagLoopback to remove the loopback interface from the list

type NetMonitor

type NetMonitor struct {
	MonitorNotificationChan chan MonitorNotification
	// contains filtered or unexported fields
}

NetMonitor represents a registered monitor to the network interfaces on windows machines once registered, any change to a network name or ip address is sent to the MonitorChan

func NewNetMonitor

func NewNetMonitor() *NetMonitor

Creates a new NetMonitor and initiates its channel

func (*NetMonitor) Register

func (nm *NetMonitor) Register(initialNotification bool) error

Registers the network monitor to the windows notifier

If returns error it's possible the error came from either notification hooks registering, so it is up to the caller to clean up by calling Unregister() as well

func (*NetMonitor) Unregister

func (nm *NetMonitor) Unregister() error

Removes the windows notifier to the network interfaces