Dual-STA query e configurazione

Articolo
03/11/2025

Nota

Per sviluppare per le funzionalità descritte in questo argomento, è necessario Windows 11 SDK (10.0.22000.194) e versioni successive.

Esistono due tipi di interfacce associate alle schede che supportano connessioni dual station (dual-STA), ovvero interfacce STA primarie e interfacce STA secondarie. Tutte le schede espongono un'interfaccia STA primaria, ma solo le schede che supportano la funzionalità dual-STA espongono interfacce STA secondarie.

Per impostazione predefinita, Windows si connette solo sull'interfaccia STA primaria. Windows si connetterà all'interfaccia STA secondaria solo se vengono soddisfatte tutte le condizioni seguenti:

Il driver indica il supporto per le interfacce STA secondarie nelle relative funzionalità.
Non esistono criteri che impediscono la connettività sta secondaria.
È presente almeno un'applicazione che ha chiamato il WlanSetInterface con il codice operativo wlan_intf_opcode_secondary_sta_synchronized_connections con il parametro impostato su TRUE.

Esecuzione di query su interfacce dual-STA

Per determinare se un adattatore è configurato per dual-STA e ottenere l'elenco dell'interfaccia STA secondaria GUIDs, l'applicazione deve chiamare WlanQueryInterface (wlanapi.h) con il codice operativo wlan_intf_opcode_secondary_sta_interfaces.

Tale codice operativo accetta come parametro l'GUID dell'interfaccia della stazione primaria (STA) (che può essere ottenuta da una chiamata a WlanEnumInterfaces) e restituisce un elenco di interfacce STA secondarie associate all'interfaccia STA primaria.

Ecco un esempio di come ottenere l'elenco di interfacce STA secondarie.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <wlanapi.h>
#include <Windot11.h> // for DOT11_SSID struct
#include <objbase.h>
#include <wtypes.h>

#include <stdio.h>
#include <stdlib.h>

// Need to link with Wlanapi.lib and Ole32.lib
#pragma comment(lib, "wlanapi.lib")
#pragma comment(lib, "ole32.lib")

DWORD QueryDualStaInterfaces()
{
    HANDLE hClient;
    DWORD version;
    DWORD dwResult = WlanOpenHandle(WLAN_API_VERSION_2_0, nullptr, &version, &hClient);
    if (dwResult != ERROR_SUCCESS)
    {
        wprintf(L"WlanOpenHandle failed with error: %u\n", dwResult);
        return dwResult;

    }

    PWLAN_INTERFACE_INFO_LIST pPrimaryIntfList = nullptr;
    dwResult = WlanEnumInterfaces(hClient, nullptr, &pPrimaryIntfList);
    if (dwResult != ERROR_SUCCESS)
    {
        wprintf(L"WlanEnumInterfaces FAILed, error = %u\n", dwResult);
        WlanCloseHandle(hClient, NULL);
        return dwResult;
    }

    wprintf(L"There are %u primary interfaces in the system\n", pPrimaryIntfList->dwNumberOfItems);
    for (UINT i = 0; i < pPrimaryIntfList->dwNumberOfItems; i++)
    {
        WCHAR* strPrimaryUuid = nullptr;
        if (UuidToStringW(&pPrimaryIntfList->InterfaceInfo[i].InterfaceGuid, reinterpret_cast<RPC_WSTR*>(&strPrimaryUuid)) != RPC_S_OK)
        {
            strPrimaryUuid = nullptr;
        }

        DWORD dwDataSize = 0;
        PWLAN_INTERFACE_INFO_LIST pSecondaryIntfList = nullptr;
        dwResult = WlanQueryInterface(
            hClient,
            &pPrimaryIntfList->InterfaceInfo[i].InterfaceGuid,
            wlan_intf_opcode_secondary_sta_interfaces,
            NULL,
            &dwDataSize,
            reinterpret_cast<PVOID*>(&pSecondaryIntfList),
            NULL);
        if (dwResult == ERROR_SUCCESS)
        {
            wprintf(
                L"\t[%d]\tInterface %ws (State = %d) has %u Secondary interfaces\n",
                i,
                strPrimaryUuid ? strPrimaryUuid : L"Unknown",
                pPrimaryIntfList->InterfaceInfo[i].isState,
                pSecondaryIntfList->dwNumberOfItems);
            for (UINT j = 0; j < pSecondaryIntfList->dwNumberOfItems; j++)
            {
                WCHAR* strSecondaryUuid = nullptr;
                if (UuidToStringW(&pSecondaryIntfList->InterfaceInfo[j].InterfaceGuid, reinterpret_cast<RPC_WSTR*>(&strSecondaryUuid)) == RPC_S_OK)
                {
                    wprintf(
                        L"\t\t[%d]\tSecondary Interface GUID: %ws, (State = %d)\n",
                        j,
                        strSecondaryUuid,
                        pSecondaryIntfList->InterfaceInfo[j].isState);
                    RpcStringFreeW(reinterpret_cast<RPC_WSTR*>(&strSecondaryUuid));
                }
            }
            WlanFreeMemory(pSecondaryIntfList);
        }
        else
        {
            wprintf(L"\t[%d]\tInterface %ws has 0 Secondary interfaces, error = %u\n", i, strPrimaryUuid ? strPrimaryUuid : L"Unknown", dwResult);
        }

        if (strPrimaryUuid)
        {
            RpcStringFreeW(reinterpret_cast<RPC_WSTR*>(&strPrimaryUuid));
        }
    }

    WlanFreeMemory(pPrimaryIntfList);
    WlanCloseHandle(hClient, NULL);

    return dwResult;
}

Esecuzione di query sullo stato delle connessioni sincronizzate dual-STA

Per determinare se un adattatore si connetterà automaticamente tramite l'interfaccia STA secondaria dopo una connessione sull'interfaccia STA primaria, l'applicazione può eseguire una query sullo stato corrente chiamando WlanQueryInterface con il codice operativo wlan_intf_opcode_secondary_sta_synchronized_connections.

Tale codice operativo restituisce un valore bool che indica se le connessioni STA primarie e secondarie sono sincronizzate.

Ecco un esempio di come eseguire una query su questo stato.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <wlanapi.h>
#include <Windot11.h> // for DOT11_SSID struct
#include <objbase.h>
#include <wtypes.h>

#include <stdio.h>
#include <stdlib.h>

// Need to link with Wlanapi.lib and Ole32.lib
#pragma comment(lib, "wlanapi.lib")
#pragma comment(lib, "ole32.lib")

DWORD QueryDualStaConnectivity()
{
    HANDLE hClient;
    DWORD version;
    DWORD dwResult = WlanOpenHandle(WLAN_API_VERSION_2_0, nullptr, &version, &hClient);
    if (dwResult != ERROR_SUCCESS)
    {
        wprintf(L"WlanOpenHandle failed with error: %u\n", dwResult);
        return dwResult;
    }
    PWLAN_INTERFACE_INFO_LIST pPrimaryIntfList = nullptr;
    dwResult = WlanEnumInterfaces(hClient, nullptr, &pPrimaryIntfList);
    if (dwResult != ERROR_SUCCESS)
    {
        wprintf(L"WlanEnumInterfaces FAILed, error = %u\n", dwResult);
        WlanCloseHandle(hClient, NULL);
        return dwResult;
    }

    //
    // Need to call the API only once to query/change the state.
    //
    if (pPrimaryIntfList->dwNumberOfItems)
    {
        WCHAR* strPrimaryUuid = nullptr;
        if (UuidToStringW(&pPrimaryIntfList->InterfaceInfo[0].InterfaceGuid, reinterpret_cast<RPC_WSTR*>(&strPrimaryUuid)) != RPC_S_OK)
        {
            strPrimaryUuid = nullptr;
        }

        DWORD dwDataSize = 0;
        PBOOL bQueriedValue = NULL;
        dwResult = WlanQueryInterface(
            hClient,
            &pPrimaryIntfList->InterfaceInfo[0].InterfaceGuid,
            wlan_intf_opcode_secondary_sta_synchronized_connections,
            NULL,
            &dwDataSize,
            (PVOID*)&bQueriedValue,
            NULL);
        if (dwResult == ERROR_SUCCESS)
        {

            wprintf(L"Secondary Sta Synchronized connections is currently %ws\n", *bQueriedValue ? L"Enabled" : L"Disabled");
            WlanFreeMemory(bQueriedValue);
        }
        else
        {
            wprintf(L"Failed to query Secondary Sta Synchronized connections - error = %u\n", dwResult);
        }

        if (strPrimaryUuid)
        {
            RpcStringFreeW(reinterpret_cast<RPC_WSTR*>(&strPrimaryUuid));
        }
    }

    WlanFreeMemory(pPrimaryIntfList);
    WlanCloseHandle(hClient, NULL);

    return dwResult;
}

Abilitazione delle connessioni nell'interfaccia STA secondaria

Windows non si connetterà alle interfacce STA secondarie, a meno che non esista un'applicazione che userà la connessione STA secondaria. Per controllare se Windows si connette all'interfaccia STA secondaria, l'applicazione deve chiamare WlanSetInterface con il codice operativo wlan_intf_opcode_secondary_sta_synchronized_connections, con un parametro BOOL che specifica se abilitare o disabilitare le connessioni nell'interfaccia STA secondaria. Un valore di TRUE indica che si vuole abilitare la connettività STA secondaria, mentre un valore di FALSE indica che non è più necessaria la connettività sta secondaria.

La chiamata all'API con il stesso valore di (TRUE o FALSE) più volte è ridondante e solo la prima istanza di un nuovo valore fa sì che la funzionalità venga modificata. Quando l'applicazione abilita la connettività STA secondaria, è necessario mantenere aperto l'handle per il servizio per la durata prevista per l'uso della connessione STA secondaria. Dopo che l'applicazione disabilita la connettività STA secondaria in modo esplicito (chiamando WlanSetInterface con il wlan_intf_opcode_secondary_sta_synchronized_connections opcode e il valore del parametro di FALSEoppure chiamando WlanCloseHandle) o in modo implicito (chiudendo), Windows disabiliterà la connettività sull'interfaccia STA secondaria in un determinato momento successivo.

La connettività STA secondaria rimarrà abilitata finché almeno una volta l'applicazione la richiede.

Ecco un esempio che illustra come abilitare o disabilitare la connettività STA secondaria.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <wlanapi.h>
#include <Windot11.h> // for DOT11_SSID struct
#include <objbase.h>
#include <wtypes.h>

#include <stdio.h>
#include <stdlib.h>

// Need to link with Wlanapi.lib and Ole32.lib
#pragma comment(lib, "wlanapi.lib")
#pragma comment(lib, "ole32.lib")

DWORD SetDualStaConnectivity(BOOL bEnable)
{
    HANDLE hClient;
    DWORD version;
    DWORD dwResult = WlanOpenHandle(WLAN_API_VERSION_2_0, nullptr, &version, &hClient);
    if (dwResult != ERROR_SUCCESS)
    {
        wprintf(L"WlanOpenHandle failed with error: %u\n", dwResult);
        return dwResult;
    }
    PWLAN_INTERFACE_INFO_LIST pPrimaryIntfList = nullptr;
    dwResult = WlanEnumInterfaces(hClient, nullptr, &pPrimaryIntfList);
    if (dwResult != ERROR_SUCCESS)
    {
        wprintf(L"WlanEnumInterfaces FAILed, error = %u\n", dwResult);
        WlanCloseHandle(hClient, NULL);
        return dwResult;
    }

    //
    // Only need to call the API once to query/change the state
    //
    if (pPrimaryIntfList->dwNumberOfItems)
    {
        WCHAR* strPrimaryUuid = nullptr;
        if (UuidToStringW(&pPrimaryIntfList->InterfaceInfo[0].InterfaceGuid, reinterpret_cast<RPC_WSTR*>(&strPrimaryUuid)) != RPC_S_OK)
        {
            strPrimaryUuid = nullptr;
        }

        dwResult = WlanSetInterface(
            hClient,
            &pPrimaryIntfList->InterfaceInfo[0].InterfaceGuid,
            wlan_intf_opcode_secondary_sta_synchronized_connections,
            sizeof(bEnable),
            reinterpret_cast<PBYTE>(&bEnable),
            NULL);
        if (dwResult == ERROR_SUCCESS)
        {
            wprintf(L"Successfully set Sec Sta opcode = %x on Primary Interface %ws\n", bEnable, strPrimaryUuid);
        }
        else
        {
            wprintf(L"FAILed set Sec Sta opcode = %x on Primary Interface %ws -- error = %u\n", bEnable, strPrimaryUuid, dwResult);
        }

        if (strPrimaryUuid)
        {
            RpcStringFreeW(reinterpret_cast<RPC_WSTR*>(&strPrimaryUuid));
        }
    }

    WlanFreeMemory(pPrimaryIntfList);

    // Close the handle only when the app no longer needs the dual-sta connection
    //
    WlanCloseHandle(hClient, NULL);
    return dwResult;
}

Condividi tramite

Dual-STA query e configurazione

Esecuzione di query su interfacce dual-STA

Esecuzione di query sullo stato delle connessioni sincronizzate dual-STA

Abilitazione delle connessioni nell'interfaccia STA secondaria

Commenti e suggerimenti

Risorse aggiuntive