QWlanManager is a Qt library allowing to manage WLAN interfaces and network easily without worrying about OS dependencies.
Tip
Latest development/pull requests will be committed into main branch.
Each stable release have their dedicated branch:
1.0.x: branchdev/1.01.1.x: branchdev/1.1- etc...
Table of contents :
This cross-platform library allow to control interfaces operations (perform a scan, connect to a network, etc...) and manage all related events through the class qwm::Manager. Main features of the library are:
- Asynchronous operations: no blocking operations, all event-driven
- Catch "external" wifi events (wifi status changed through OS UI, from other apps, etc...)
- Interfaces added or removed are detected
- UTF-8 networks are supported
- Datas classes are QML compatible
- Implicit shared datas (via
shared_ptr) reducing number of copies (passing by value is cheap) - Library is thread-safe, no need for external synchronisation management
- Allow to manage permissions of the Operating System: some OSes required Wlan related authorizations. Class
qwm::Permissionswill help to manage those. - Allow to enable/disable a cache feature: Some OSes can return a partial scan, it doesn't fail but will be partial (due to hardware error, wrong timing, etc...). Having a cache can help to smooth the list of network management
- Allow to enable/disable a request feature: Performing interface operations in the same time (like a connection during a scan, a scan during connection, etc...) can trigger an unexpected behaviour. Request feature allow to queue those operations.
What the library doesn't support (yet!):
- WPA2/WPA3 enterprise networks
- Hidden networks are ignored
- Peer-to-peer/ad-hoc networks are ignored
Note
Custom application QWlanManagerApp is available and used as a demo application to discover how this library can be used.
One OS can have multiple backend or differ according to the OS version used, this table will reflect those differences:
| OS | Backend engine | Permissions backend | Status | Comments |
|---|---|---|---|---|
| Windows 7/8 | WlanAPI IpHlpAPI |
🚫 | ✅ | Custom CMake options QWLANMANAGER_WINDOWS_COMPAT_PREWIN10 requiredQt5.15 will be needed for those platforms (Qt6 isn't compatible with those) |
| Windows 10/11 | WlanAPI IpHlpAPI |
WinRT (via AppCapabilityAccess) |
✅ | Package cppwinrt required for permissions backend |
| Windows 11 | WinRT (via WifiAdapter) |
WinRT (via AppCapabilityAccess) |
🕚 | Package cppwinrt required for wifi and permissions backend |
| MacOS | CoreWlan | CoreLocation | ✅ | Please refer to section specific behaviour - MacOS |
| Linux | NetworkManager | ❓ | 🕚 | / |
Note
Legends:
- 🚫: No support on native API
- 🕚: Planned
- 📝: In progress
- ✅: Complete support
Under MacOS, location permissions key NSLocationUsageDescription must be declared inside your Info.plist application file in order to perform a network scan:
<key>NSLocationUsageDescription</key>
<string>Used to scan nearby Wi-Fi networks</string>This library requires at least C++ 17 standard
Below, list of required dependencies:
| Dependencies | VCPKG package | Comments |
|---|---|---|
| Qt | / | Compatible with Qt6.x Compatible with Qt5.15.x |
| Native APIs | / | Please refer to section supported platform for more details |
Note
Dependency manager VCPKG is not mandatory, this is only a note to be able to list needed packages
This library can be use as an embedded library in a subdirectory of your project (like a git submodule for example) :
- In the root CMakeLists, add instructions :
add_subdirectory(qwlanmanager) # Or if library is put in a folder "dependencies": add_subdirectory(dependencies/qwlanmanager)- In the application/library CMakeLists, add instructions :
# Link needed libraries
target_link_libraries(${PROJECT_NAME} PRIVATE qwlanmanager)This library provide some CMake build options:
QWLANMANAGER_WINDOWS_COMPAT_PREWIN10(default:OFF): Use this option to enable compatibility with Windows version earlier than Windows 10. Enabling this option will disable some features in order to keep compatibility, so better to disable it for Windows 10 and newer. Internally, this is due to the missing support of C++/WinRT library, impacted features will be :qwm:Permissions: no support for permissions control, each permissions method will use a mock version, allowing users of the library to not have to make distinction code, permissions will simply return an unknown status.
Please refer to qwm::Manager class documentation for more details.
This library use the PImpl Idiom in order to preserve ABI compatibility (Qt wiki also have a great tutorial on the PImpl idiom).
So only major release (this project use the semantic versioning) should break the ABI.
In order to easily check at compilation time library version (to manage compatibility between multiple versions for example), macro QWLANMAN_VERSION_ENCODE (defined inside qwlanman_global.h file) can be used:
#if QWLANMAN_VERSION >= QWLANMAN_VERSION_ENCODE(2,0,0)
// Do stuff for version 2.0.0 or higher
#else
// Do stuff for earlier versions
#endifSince library header used during final application build could differ from the actual library version, it is recommended to use the method:
#include "qwlanmanager/qwlantypes.h"
const QVersionNumber libSemver = qwm::getLibraryVersion();All classes/methods has been documented with Doxygen utility and automatically generated at online website documentation.
Note
This repository contains two kinds of documentation:
- Public API: Available via online website documentation or locally via Doxyfile
docs/fragments/Doxyfile-public-api.in - Internal: Available locally only via
docs/fragments/Doxyfile-internal.in
To generate documentation locally, we can use:
doxygen ./docs/fragments/Doxyfile-nameTip
You can also load the Doxyfile into Doxywizard (Doxygen GUI) and run generation.
This library is licensed under MIT license.