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

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 DOT11_SSID qui spécifie le SSID du réseau à analyser. Ce paramètre peut être NULL. Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Ce paramètre doit être NULL.

[in, optional] pIeData

Pointeur vers un élément d’information à inclure dans les requêtes de sonde. Ce paramètre pointe vers une structure WLAN_RAW_DATA qui peut inclure des informations de disponibilité sur 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 être NULL.

pReserved

Réservé pour une utilisation ultérieure. 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 natif 802.11 recherche les réseaux sans fil disponibles. Le pilote peut ou non envoyer des requêtes de sonde (une analyse active) en fonction de son implémentation et des valeurs passées 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’informations (IE) pointé par le paramètre pIeData . Par exemple, l’IE Wi-Fi protected setup (WPS) peut être inclus dans les requêtes de sonde pour découvrir les points d’accès compatibles WPS. La mémoire tampon pointée par le paramètre pIeData doit contenir l’internet Explorer complet à partir de l’ID d’élément.

Le paramètre pIeData transmis à 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 services 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 EE PSD, notamment 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 l’initialisation de l’analyse. Les applications ne doivent pas supposer que l’appel de la fonction WlanScan ajoute à la liste existante des réseaux sans fil disponibles retournés par les fonctions WlanGetNetworkBssList ou WlanGetAvailableNetworkList 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 ultérieur doit s’inscrire aux notifications en appelant WlanRegisterNotification. Le paramètre dwNotifSource transmis à la fonction WlanRegisterNotification doit avoir le bit WLAN_NOTIFICATION_SOURCE_ACM défini pour s’inscrire aux notifications générées par le module de configuration automatique. Les pilotes de 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 de rechercher des 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 du 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 la réception de la notification ou du délai d’expiration wlan_notification_acm_scan_complete après 4 secondes. Ensuite, l’application peut appeler la fonction WlanGetNetworkBssList ou WlanGetAvailableNetworkList pour récupérer une liste de réseaux sans fil disponibles. Ce processus peut être répété régulièrement avec le suivi des modifications apportées aux réseaux sans fil disponibles par l’application.

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 qu’une analyse se produit, la fonction WlanScan peut augmenter la latence jusqu’à ce que l’analyse réseau soit terminée.

Spécifications

Voir aussi

DOT11_SSID

WLAN_RAW_DATA

WlanEnumInterfaces

WlanGetAvailableNetworkList

WlanGetNetworkBssList

WlanRegisterNotification

WlanSetPsdIEDataList