Kawaiifi.Net 0.1.0-preview.1

Kawaiifi.Net

Kawaiifi.Net is a Wi-Fi scanning library for Linux, macOS, and Windows.

It wraps kawaiifi-ffi and handles all P/Invoke interop, memory management, and platform differences internally. Callers never need to write unsafe code or manage native memory directly.

Building

First, build the native kawaiifi-ffi library:

cargo build -p kawaiifi-ffi --release

Then build the .NET solution:

dotnet build

Usage

Obtaining a Wi-Fi Interface

Use Interface.Default() to get the first available interface.

using var defaultInterface = Interface.Default();

Use Interface.All() to get all available interfaces.

using var interfaces = Interface.All();
Console.WriteLine($"Found {interfaces.Count} interface(s)");

Some Interface properties are platform-specific.

if (OperatingSystem.IsLinux())
{
    Console.WriteLine($"Index: {defaultInterface?.Index}");
}

if (OperatingSystem.IsMacOS())
{
    Console.WriteLine($"Noise: {defaultInterface?.NoiseDbm} dBm");
}

if (OperatingSystem.IsWindows())
{
    Console.WriteLine($"Description: {defaultInterface?.Description}");
}

Triggering a Wi-Fi Scan

On Linux, scans can be triggered through either NetworkManager or nl80211 (Netlink), so a Backend must be specified.

On macOS and Windows, scans are triggered through CoreWLAN and Native Wifi respectively.

using var defaultInterface = Interface.Default();

if (OperatingSystem.IsLinux())
{
    using var scan = defaultInterface?.Scan(Backend.NetworkManager);
    Console.WriteLine($"Found {scan?.BssList.Count} BSS(s)");
}

if (OperatingSystem.IsMacOS() || OperatingSystem.IsWindows())
{
    using var scan = defaultInterface?.Scan();
    Console.WriteLine($"Found {scan?.BssList.Count} BSS(s)");
}

See Scan/Program.cs.

Accessing BSS Data

Scan contains a list of BSSs that are accessed through Scan.BssList.

BssList bssList = scan.BssList;
Console.WriteLine($"Found {bssList.Count} BSS(s)");

Bss exposes common properties that are available on all platforms.

Console.WriteLine($"BSSID: {BitConverter.ToString(bss.Bssid).Replace('-', ':')}");
Console.WriteLine($"SSID: {bss.Ssid}");
Console.WriteLine($"Frequency: {bss.FrequencyMhz} MHz");
Console.WriteLine($"Band: {bss.Band.ToDisplayString()}");
Console.WriteLine($"Channel: {bss.ChannelNumber}");
Console.WriteLine($"Channel Width: {bss.ChannelWidth.ToDisplayString()}");
Console.WriteLine($"Signal: {bss.SignalDbm} dBm");
Console.WriteLine($"Security: {bss.SecurityProtocols.ToString()}");
Console.WriteLine($"Wi-Fi Protocols: {bss.WifiProtocols.ToString()}");
Console.WriteLine($"Wi-Fi Amendments: {bss.WifiAmendments.ToString()}");
Console.WriteLine($"Max Rate: {bss.MaxRateMbps:F2} Mbps");

Some Bss properties are platform-specific.

if (OperatingSystem.IsLinux())
{
    Console.WriteLine($"Status: {bss.Status}");
}

if (OperatingSystem.IsMacOS())
{
    Console.WriteLine($"Noise: {bss.NoiseDbm} dBm");
}

if (OperatingSystem.IsWindows())
{
    Console.WriteLine($"Link Quality: {bss.LinkQuality}");
}

See BssData/Program.cs.

Accessing Information Elements

Bss contains a list of 802.11 Information Elements (IEs) that are accessed through Bss.Ies.

IReadOnlyList<Ie> ies = bss.Ies;
Console.WriteLine($"Found {ies.Count} IE(s)");

Ie exposes basic properties such as the information element's name, ID, and a summary.

Console.WriteLine($"{ie.Name} ({ie.Id}) - {ie.Summary}");

Ie also exposes its decoded fields through Ie.Fields. Each Field has a Title, Value, optional Units, and nested Subfields.

using FieldList fields = ie.Fields;
foreach (Field field in fields)
{
    Console.WriteLine($"{field.Title}: {field.Value}");
}

See Ies/Program.cs.

Platform-Specific APIs

Kawaiifi.Net exposes platform-specific APIs via [SupportedOSPlatform] attributes. The Roslyn analyzer will warn if platform-specific APIs are called without an OS check.

For example, on Linux and macOS, Interface has a Name property, while on Windows, Interface has a Description property.

using var defaultInterface = Interface.Default();

if (OperatingSystem.IsLinux() || OperatingSystem.IsMacOS())
{
    Console.WriteLine($"Interface name: {defaultInterface?.Name}");
}
else if (OperatingSystem.IsWindows())
{
    Console.WriteLine($"Interface description: {defaultInterface?.Description}");
}

Troubleshooting

See the repository troubleshooting notes for platform-specific permissions and location-services behavior.

Changelog

See the repository changelog for release notes.

License

Dual-licensed under MIT or Apache 2.0.