Fonction WlanGetNetworkBssList (wlanapi.h)
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 |
|---|---|
|
Un réseau BSS d’infrastructure. |
|
Un réseau BSS (IBSS) indépendant (réseau ad hoc). |
|
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 |
|---|---|
|
Le handle hClientHandle est introuvable dans la table de handles. |
|
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. |
|
La radio associée à l’interface est désactivée. La liste BSS n’est pas disponible lorsque la radio est désactivée. |
|
La mémoire disponible est insuffisante pour traiter cette requête et allouer de la mémoire aux résultats de la requête. |
|
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. |
|
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é. |
|
Le service Wlan AutoConfig n’a pas été démarré. |
|
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 |