Fonction WlanScan (wlanapi.h)

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.

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 .

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

Voir aussi

DOT11_SSID

WLAN_RAW_DATA

WlanEnumInterfaces

WlanGetAvailableNetworkList

WlanGetNetworkBssList

WlanRegisterNotification

WlanSetPsdIEDataList