QWlanManager

QWlanManager is a Qt library allowing to manage WLAN interfaces and network easily without worrying about OS dependencies.

Remarks

Latest development/pull requests will be committed into main branch.
Each stable release have their dedicated branch:

• 1.0.x: branch dev/1.0
• 1.1.x: branch dev/1.1
• etc...

Table of contents :

• 1. Library details
  • 1.1. Features
  • 1.2. Supported platforms
    • 1.2.1. Status
    • 1.2.2. Specific behaviours
      • 1.2.2.1. MacOS
• 2. Requirements
  • 2.1. C++ Standards
  • 2.2. Dependencies
• 3. How to build
  • 3.1. CMake usage
  • 3.2. CMake options
• 4. How to use
  • 4.1. Usage
  • 4.2. Library version
    • 4.2.1. Compatibility
    • 4.2.2. Compilation time
    • 4.2.3. Runtime
• 5. Documentation
• 6. License

1. Library details

1.1. Features

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::Permissions will 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

1.2. Supported platforms

1.2.1. Status

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` required Qt5.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

1.2.2. Specific behaviours

1.2.2.1. MacOS

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>

2. Requirements

2.1. C++ Standards

This library requires at least C++ 17 standard

2.2. Dependencies

Below, list of required dependencies:

Dependencies	VCPKG package	Comments
Qt	/	Compatible with Qt6.xCompatible 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

3. How to build

3.1. CMake usage

This library can be use as an embedded library in a subdirectory of your project (like a git submodule for example) :

1. In the root CMakeLists, add instructions :

   add_subdirectory(qwlanmanager) # Or if library is put in a folder "dependencies": add_subdirectory(dependencies/qwlanmanager)

2. In the application/library CMakeLists, add instructions :

   # Link needed libraries
   target_link_libraries(${PROJECT_NAME} PRIVATE qwlanmanager)

3.2. CMake options

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.

4. How to use

4.1. Usage

Please refer to qwm::Manager class documentation for more details.

4.2. Library version

4.2.1. Compatibility

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.

4.2.2. Compilation time

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
#endif

4.2.3. Runtime

Since 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();

5. Documentation

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-name

Remarks

You can also load the Doxyfile into Doxywizard (Doxygen GUI) and run generation.

6. License

This library is licensed under [MIT license][repo-license].