Funzione WlanGetNetworkBssList (wlanapi.h)

Articolo
02/01/2024

Nota

Alcune informazioni sono relative a un prodotto non definitivo, che potrebbe subire modifiche sostanziali prima del rilascio sul mercato. Microsoft non offre alcuna garanzia, esplicita o implicita, relativamente alle informazioni fornite.

Importante

Questa API sarà interessata dalle modifiche imminenti al comportamento del sistema operativo, previsto per l'autunno 2024. Per altre informazioni, vedere Modifiche al comportamento dell'API per Wi-Fi l'accesso e la posizione.

La funzione WlanGetNetworkBssList recupera un elenco delle voci del set di servizi di base (BSS) della rete wireless o delle reti in una determinata interfaccia LAN wireless.

Sintassi

DWORD WlanGetNetworkBssList(
  [in]       HANDLE            hClientHandle,
  [in]       const GUID        *pInterfaceGuid,
  [optional] const PDOT11_SSID pDot11Ssid,
  [in]       DOT11_BSS_TYPE    dot11BssType,
  [in]       BOOL              bSecurityEnabled,
             PVOID             pReserved,
  [out]      PWLAN_BSS_LIST    *ppWlanBssList
);

Parametri

[in] hClientHandle

Handle di sessione del client, ottenuto da una chiamata precedente alla funzione WlanOpenHandle .

[in] pInterfaceGuid

Puntatore al GUID dell'interfaccia LAN wireless su cui eseguire query.

Il GUID di ogni interfaccia LAN wireless abilitata in un computer locale può essere determinato usando la funzione WlanEnumInterfaces .

[optional] pDot11Ssid

Puntatore a una struttura DOT11_SSID che specifica l'SSID della rete da cui viene richiesto l'elenco BSS. Questo parametro è facoltativo e, Se impostato su NULL, l'elenco restituito contiene tutte le voci BSS disponibili in un'interfaccia LAN wireless.

Se viene specificato un puntatore a una struttura DOT11_SSID , la lunghezza SSID specificata nel membro uSSIDLength della struttura DOT11_SSID deve essere minore o uguale a DOT11_SSID_MAX_LENGTH definita nel file di intestazione Wlantypes.h . Inoltre, il parametro dot11BssType deve essere impostato su dot11_BSS_type_infrastructure o dot11_BSS_type_independent e il parametro bSecurityEnabled deve essere specificato.

[in] dot11BssType

Tipo BSS della rete. Questo parametro viene ignorato se l'SSID della rete per l'elenco BSS non è specificato (il parametro pDot11Ssid è NULL).

Questo parametro può essere uno dei valori seguenti definiti nell'enumerazione DOT11_BSS_TYPE definita nel file di intestazione Wlantypes.h .

Valore	Significato
dot11_BSS_type_infrastructure	Una rete BSS dell'infrastruttura.
dot11_BSS_type_independent	Una rete BSS (IBSS) indipendente (una rete ad hoc).
dot11_BSS_type_any	Qualsiasi rete BSS.

[in] bSecurityEnabled

Valore che indica se la sicurezza è abilitata nella rete. Questo parametro è valido solo quando viene specificato il valore SSID della rete per l'elenco BSS (il parametro pDot11Ssid non è NULL).

pReserved

Riservato per utilizzi futuri. Questo parametro deve essere impostato su NULL.

[out] ppWlanBssList

Puntatore all'archiviazione per un puntatore per ricevere l'elenco restituito di voci BSS in una struttura di WLAN_BSS_LIST .

Il buffer per il WLAN_BSS_LIST restituito viene allocato dalla funzione WlanGetNetworkBssList se la chiamata ha esito positivo.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici restituiti seguenti.

Codice restituito	Descrizione
ERROR_INVALID_HANDLE	L'handle hClientHandle non è stato trovato nella tabella handle.
ERROR_INVALID_PARAMETER	Un parametro non è corretto. Questo errore viene restituito se il parametro hClientHandle, pInterfaceGuid o ppWlanBssList è NULL. Questo errore viene restituito se pReserved non è NULL. Questo errore viene restituito anche se hClientHandle, il SSID specificato nel parametro pDot11Ssid o il tipo BSS specificato nel parametro dot11BssType non è valido.
ERROR_NDIS_DOT11_POWER_STATE_INVALID	La radio associata all'interfaccia è disattivata. L'elenco BSS non è disponibile quando la radio è disattivata.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per elaborare questa richiesta e allocare memoria per i risultati della query.
ERROR_NOT_FOUND	Impossibile trovare l'elemento. Questo errore viene restituito se non è stato possibile trovare il GUID dell'interfaccia su cui è stata eseguita una query specificata nel parametro pInterfaceGuid .
ERROR_NOT_SUPPORTED	La richiesta non è supportata. Questo errore viene restituito se questa funzione è stata chiamata da un'API Windows XP con SP3 o LAN wireless per Windows XP con il client SP2. Questo errore viene restituito anche se il servizio WLAN AutoConfig è disabilitato.
ERROR_SERVICE_NOT_ACTIVE	Il servizio WLAN AutoConfig non è stato avviato.
RPC_STATUS	Vari codici di errore.

Commenti

La funzione WlanGetNetworkBssList recupera l'elenco dei set di servizi di base per ogni rete wireless o rete accessibile in una determinata interfaccia. L'elenco di informazioni restituite per ogni rete wireless contiene anche un elenco di elementi informativi restituiti da ogni punto di accesso per una rete BSS dell'infrastruttura o un peer di rete per una rete BSS indipendente (rete ad hoc). Le informazioni vengono restituite come puntatore a una struttura WLAN_BSS_LIST nel parametro ppWlanBssList . La struttura WLAN_BSS_LIST contiene un conteggio di elementi seguito da una matrice di WLAN_BSS_ENTRY voci della struttura.

Poiché le informazioni restituite dalla funzione WlanGetNetworkBssList vengono inviate da un punto di accesso per una rete BSS dell'infrastruttura o da un peer di rete per una rete BSS indipendente (rete ad hoc), le informazioni restituite non devono essere attendibili. I membri ulIeOffset e ulIeSize nella struttura WLAN_BSS_ENTRY devono essere usati per determinare le dimensioni del BLOB di dati dell'elemento informativo nella struttura WLAN_BSS_ENTRY , non i dati nel BLOB di dati dell'elemento informativo stesso. La funzione WlanGetNetworkBssList non convalida che nessuna informazione restituita nel BLOB di dati dell'elemento informativo a cui punta il membro ulIeOffset è un elemento informativo valido, come definito dagli standard IEEE 802.11 per le reti LAN wireless.

Se il parametro pDot11Ssid è specificato (non NULL), il parametro dot11BssType specificato deve essere impostato su dot11_BSS_type_infrastructure per una rete BSS dell'infrastruttura o dot11_BSS_type_independent per una rete BSS indipendente (rete ad hoc). Se il parametro dot11BssType è impostato su dot11_BSS_type_any, la funzione WlanGetNetworkBssList restituisce ERROR_SUCCESS ma non verranno restituite voci BSS.

Per restituire un elenco di tutte le reti BSS dell'infrastruttura e delle reti BSS indipendenti (reti ad hoc) in un'interfaccia LAN wireless, impostare il parametro pDot11Ssid su NULL. Quando l'interfaccia LAN wireless funziona anche come rete ospitata wireless, l'elenco BSS conterrà una voce per il BSS creato per la rete ospitata wireless.

La funzione WlanGetNetworkBssList restituisce ERROR_SUCCESS quando viene restituito un elenco BSS vuoto dal servizio WLAN AutoConfig. Un'applicazione che chiama la funzione WlanGetNetworkBssList deve verificare che il membro dwNumberOfItems del WLAN_BSS_LIST a cui punta il parametro ppWlanBssList non sia zero prima di accedere al membro wlanBssEntries[0] nella struttura WLAN_BSS_LIST .

La funzione WlanGetNetworkBssList alloca memoria per l'elenco dei set di servizi di base restituito in un buffer a cui punta il parametro ppWlanBssList quando la funzione ha esito positivo. La memoria utilizzata per il buffer a cui punta il parametro ppWlanBssList deve essere rilasciata chiamando la funzione WlanFreeMemory dopo che il buffer non è più necessario.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wlanapi.h (include Wlanapi.h)
Libreria	Wlanapi.lib
DLL	Wlanapi.dll