Fonction WlanGetNetworkBssList (wlanapi.h)

Article
10/19/2023

Notes

Certaines informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.

Important

Cette API sera affectée par les modifications à venir du comportement du système d’exploitation, prévues pour l’automne 2024. Pour plus d’informations, consultez Modifications du comportement de l’API pour l’accès Wi-Fi et l’emplacement.

La fonction WlanGetNetworkBssList récupère une liste des entrées BSS (Basic Service Set) du ou des réseaux sans fil sur une interface LAN sans fil donnée.

Syntaxe

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

Paramètres

[in] hClientHandle

Handle de session du client, obtenu par un appel précédent à la fonction WlanOpenHandle .

[in] pInterfaceGuid

Pointeur vers le GUID de l’interface LAN sans fil à interroger.

Le GUID de chaque interface LAN sans fil activée sur un ordinateur local peut être déterminé à l’aide de la fonction WlanEnumInterfaces .

[optional] pDot11Ssid

Pointeur vers une structure DOT11_SSID qui spécifie le SSID du réseau à partir duquel la liste BSS est demandée. Ce paramètre est facultatif. Lorsqu’elle est définie sur NULL, la liste retournée contient toutes les entrées BSS disponibles sur une interface LAN sans fil.

Si un pointeur vers une structure de DOT11_SSID est spécifié, la longueur SSID spécifiée dans le membre uSSIDLength de DOT11_SSID structure doit être inférieure ou égale à DOT11_SSID_MAX_LENGTH définie dans le fichier d’en-tête Wlantypes.h . En outre, le paramètre dot11BssType doit être défini sur dot11_BSS_type_infrastructure ou dot11_BSS_type_independent et le paramètre bSecurityEnabled doit être spécifié.

[in] dot11BssType

Type BSS du réseau. Ce paramètre est ignoré si le SSID du réseau pour la liste BSS n’est pas spécifié (le paramètre pDot11Ssid est NULL).

Ce paramètre peut être l’une des valeurs suivantes définies dans l’énumération DOT11_BSS_TYPE définie dans le fichier d’en-tête Wlantypes.h .

Valeur	Signification
dot11_BSS_type_infrastructure	Un réseau BSS d’infrastructure.
dot11_BSS_type_independent	Un réseau BSS (IBSS) indépendant (réseau ad hoc).
dot11_BSS_type_any	Tout réseau BSS.

[in] bSecurityEnabled

Valeur qui indique si la sécurité est activée sur le réseau. Ce paramètre n’est valide que lorsque le SSID du réseau pour la liste BSS est spécifié (le paramètre pDot11Ssid n’est pas NULL).

pReserved

Réservé pour un usage futur. Ce paramètre doit être défini sur NULL.

[out] ppWlanBssList

Pointeur vers le stockage pour qu’un pointeur reçoive la liste retournée d’entrées BSS dans une structure de WLAN_BSS_LIST .

La mémoire tampon pour le WLAN_BSS_LIST retourné est allouée par la fonction WlanGetNetworkBssList si l’appel réussit.

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour peut être l’un des codes de retour suivants.

Code de retour	Description
ERROR_INVALID_HANDLE	Le handle hClientHandle est introuvable dans la table de handles.
ERROR_INVALID_PARAMETER	Un paramètre est incorrect. Cette erreur est retournée si le paramètre hClientHandle, pInterfaceGuid ou ppWlanBssList a la valeur NULL. Cette erreur est retournée si pReserved n’a pas la valeur NULL. Cette erreur est également retournée si le hClientHandle, le SSID spécifié dans le paramètre pDot11Ssid ou le type BSS spécifié dans le paramètre dot11BssType n’est pas valide.
ERROR_NDIS_DOT11_POWER_STATE_INVALID	La radio associée à l’interface est désactivée. La liste BSS n’est pas disponible lorsque la radio est désactivée.
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible est insuffisante pour traiter cette requête et allouer de la mémoire aux résultats de la requête.
ERROR_NOT_FOUND	L'élément est introuvable. Cette erreur est retournée si le GUID de l’interface à interroger qui a été spécifié dans le paramètre pInterfaceGuid est introuvable.
ERROR_NOT_SUPPORTED	La demande n'est pas prise en charge. Cette erreur est retournée si cette fonction a été appelée à partir d’un windows XP avec SP3 ou de l’API LAN sans fil pour Windows XP avec un client SP2. Cette erreur est également retournée si le service de configuration automatique WLAN est désactivé.
ERROR_SERVICE_NOT_ACTIVE	Le service Wlan AutoConfig n’a pas été démarré.
RPC_STATUS	Différents codes d’erreur.

Remarques

La fonction WlanGetNetworkBssList récupère la liste des ensembles de services de base pour chaque ou chaque réseau sans fil accessible sur une interface donnée. La liste des informations retournées pour chaque réseau sans fil contient également une liste d’éléments d’informations retournés par chaque point d’accès pour un réseau BSS d’infrastructure ou un homologue réseau pour un réseau BSS indépendant (réseau ad hoc). Les informations sont retournées en tant que pointeur vers une structure WLAN_BSS_LIST dans le paramètre ppWlanBssList . La structure WLAN_BSS_LIST contient un nombre d’éléments suivi d’un tableau d’entrées de structure WLAN_BSS_ENTRY .

Étant donné que les informations retournées par la fonction WlanGetNetworkBssList sont envoyées par un point d’accès pour un réseau BSS d’infrastructure ou par un homologue réseau pour un réseau BSS indépendant (réseau ad hoc), les informations retournées ne doivent pas être approuvées. Les membres ulIeOffset et ulIeSize dans la structure WLAN_BSS_ENTRY doivent être utilisés pour déterminer la taille de l’objet blob de données d’élément d’information dans la structure WLAN_BSS_ENTRY , et non les données dans l’objet blob de données d’élément d’information lui-même. La fonction WlanGetNetworkBssList ne valide pas que les informations retournées dans l’objet blob de données d’élément d’information pointé par le membre ulIeOffset sont un élément d’information valide tel que défini par les normes IEEE 802.11 pour les réseaux locaux sans fil.

Si le paramètre pDot11Ssid est spécifié (et non NULL), le paramètre dot11BssType spécifié doit être défini sur dot11_BSS_type_infrastructure pour un réseau BSS d’infrastructure ou dot11_BSS_type_independent pour un réseau BSS indépendant (réseau ad hoc). Si le paramètre dot11BssType est défini sur dot11_BSS_type_any, la fonction WlanGetNetworkBssList retourne ERROR_SUCCESS mais aucune entrée BSS ne sera retournée.

Pour renvoyer une liste de tous les réseaux BSS d’infrastructure et réseaux BSS indépendants (réseaux ad hoc) sur une interface LAN sans fil, définissez le paramètre pDot11Ssid sur NULL. Lorsque l’interface LAN sans fil fonctionne également en tant que réseau hébergé sans fil, la liste BSS contient une entrée pour le BSS créé pour le réseau hébergé sans fil.

La fonction WlanGetNetworkBssList retourne ERROR_SUCCESS lorsqu’une liste BSS vide est retournée par le service WLAN AutoConfig. Une application qui appelle la fonction WlanGetNetworkBssList doit case activée que le membre dwNumberOfItems du WLAN_BSS_LIST pointé par le paramètre ppWlanBssList n’est pas zéro avant d’accéder au membre wlanBssEntries[0] dans WLAN_BSS_LIST structure.

La fonction WlanGetNetworkBssList alloue de la mémoire à la liste des ensembles de services de base qui est retournée dans une mémoire tampon pointée par le paramètre ppWlanBssList lorsque la fonction réussit. La mémoire utilisée pour la mémoire tampon pointée vers le paramètre ppWlanBssList doit être libérée en appelant la fonction WlanFreeMemory une fois que la mémoire tampon n’est plus nécessaire.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wlanapi.h (incluez Wlanapi.h)
Bibliothèque	Wlanapi.lib
DLL	Wlanapi.dll