Fonction WlanScan (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 Wi-Fi l’accès et l’emplacement.

La fonction WlanScan demande une analyse des réseaux disponibles sur l’interface indiquée.

Syntaxe

DWORD WlanScan(
  [in]           HANDLE               hClientHandle,
  [in]           const GUID           *pInterfaceGuid,
  [in, optional] const PDOT11_SSID    pDot11Ssid,
  [in, optional] const PWLAN_RAW_DATA pIeData,
                 PVOID                pReserved
);

Paramètres

[in] hClientHandle

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

[in] pInterfaceGuid

GUID de l’interface à 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 .

[in, optional] pDot11Ssid

Pointeur vers une structure de DOT11_SSID qui spécifie le SSID du réseau à analyser. Ce paramètre est facultatif. Lorsqu’elle est définie sur NULL, la liste retournée contient tous les réseaux disponibles. Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Ce paramètre doit avoir la valeur NULL.

[in, optional] pIeData

Pointeur vers un élément d’information à inclure dans les demandes de sonde. Ce paramètre pointe vers une structure WLAN_RAW_DATA qui peut inclure des informations de disponibilité de l’approvisionnement du client et des exigences d’authentification 802.1X. Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Ce paramètre doit avoir la valeur NULL.

pReserved

Réservé pour un usage futur. Doit être défini sur NULL.

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_PARAMETER	hClientHandle a la valeur NULL ou non valide, pInterfaceGuid a la valeur NULL ou pReserved n’est pas NULL.
ERROR_INVALID_HANDLE	Le handle hClientHandle est introuvable dans la table handle.
RPC_STATUS	Différents codes d’erreur.
ERROR_NOT_ENOUGH_MEMORY	Échec de l’allocation de mémoire pour les résultats de la requête.

Remarques

La fonction WlanScan demande que le pilote LAN sans fil 802.11 natif recherche les réseaux sans fil disponibles. Le pilote peut ou non envoyer des requêtes de sonde (analyse active) en fonction de son implémentation et des valeurs transmises dans les paramètres pDot11Ssid et pIeData .

Si le paramètre pIeData n’est pas NULL, le pilote envoie des requêtes de sonde pendant l’analyse. Les requêtes de sonde incluent l’élément d’information (IE) pointé vers le paramètre pIeData . Par instance, le programme d’installation protégé Wi-Fi (WPS) IE peut être inclus dans les demandes de sonde pour découvrir les points d’accès compatibles WPS. La mémoire tampon pointée vers par le paramètre pIeData doit contenir l’IE complet à partir de l’ID d’élément.

Le paramètre pIeData passé à la fonction WlanScan peut contenir un pointeur vers une structure de WLAN_RAW_DATA facultative qui contient une entrée de données IE de découverte de service de proximité (PSD).

Lorsqu’elle est utilisée pour stocker un IE PSD, la constante DOT11_PSD_IE_MAX_DATA_SIZE définie dans le fichier d’en-tête Wlanapi.h est la valeur maximale du membre dwDataSize .

Constant	Valeur	Description
DOT11_PSD_IE_MAX_DATA_SIZE	240	Taille maximale des données, en octets, d’une entrée de données PSD IE.

Pour plus d’informations sur les E/S PSD, y compris une discussion sur le format d’un IE PSD, consultez la fonction WlanSetPsdIEDataList .

Lorsque la fonction WlanScan est appelée, le pilote LAN sans fil natif 802.11 peut vider la liste actuelle des réseaux sans fil disponibles avant le lancement de l’analyse. Les applications ne doivent pas supposer que l’appel de la fonction WlanScan s’ajoute à la liste existante des réseaux sans fil disponibles retournés par les fonctions WlanGetNetworkBssList ou WlanGetAvailableNetworkList à partir des analyses précédentes.

La fonction WlanScan retourne immédiatement. Pour être averti lorsque l’analyse réseau est terminée, un client sur Windows Vista et versions ultérieures doit s’inscrire aux notifications en appelant WlanRegisterNotification. Le paramètre dwNotifSource passé à la fonction WlanRegisterNotification doit avoir le WLAN_NOTIFICATION_SOURCE_ACM bit défini pour s’inscrire aux notifications générées par le module de configuration automatique. Les pilotes réseau sans fil qui répondent aux exigences de logo Windows sont nécessaires pour effectuer une demande de fonction WlanScan en 4 secondes.

Le service LAN sans fil n’envoie pas de notifications lorsque les réseaux sans fil disponibles changent. Le service LAN sans fil ne suit pas les modifications apportées à la liste des réseaux disponibles sur plusieurs analyses. Le comportement par défaut actuel est que le service LAN sans fil demande uniquement au pilote d’interface sans fil d’analyser les réseaux sans fil toutes les 60 secondes, et dans certains cas (lorsqu’il est déjà connecté au réseau sans fil), le service LAN sans fil ne demande pas d’analyses du tout. La fonction WlanScan peut être utilisée par une application pour suivre les modifications apportées au réseau sans fil. L’application doit d’abord s’inscrire aux notifications WLAN_NOTIFICATION_SOURCE_ACM. La fonction WlanScan peut ensuite être appelée pour lancer une analyse. L’application doit ensuite attendre de recevoir la notification wlan_notification_acm_scan_complete ou le délai d’expiration après 4 secondes. Ensuite, l’application peut appeler la fonction WlanGetNetworkBssList ou WlanGetAvailableNetworkList pour récupérer une liste des réseaux sans fil disponibles. Ce processus peut être répété régulièrement avec l’application qui suit les modifications apportées aux réseaux sans fil disponibles.

La fonction WlanScan retourne immédiatement et ne fournit pas de notification lorsque l’analyse est terminée sur Windows XP avec SP3 ou l’API LAN sans fil pour Windows XP avec SP2.

Étant donné qu’il devient plus difficile pour une interface sans fil d’envoyer et de recevoir des paquets de données pendant une analyse, la fonction WlanScan peut augmenter la latence jusqu’à ce que l’analyse réseau soit terminée.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista, Windows XP avec SP3 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wlanapi.h (inclure Wlanapi.h)
Bibliothèque	Wlanapi.lib
DLL	Wlanapi.dll
Composant redistribuable	API LAN sans fil pour Windows XP avec SP2