Fonction WlanHostedNetworkQuerySecondaryKey (wlanapi.h)

Article
08/28/2023

La fonction WlanHostedNetworkQuerySecondaryKey interroge la clé de sécurité secondaire configurée pour être utilisée par le réseau hébergé sans fil.

Syntaxe

DWORD WlanHostedNetworkQuerySecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [out]           PDWORD                      pdwKeyLength,
  [out]           PUCHAR                      *ppucKeyData,
  [out]           PBOOL                       pbIsPassPhrase,
  [out]           PBOOL                       pbPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

Paramètres

[in] hClientHandle

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

[out] pdwKeyLength

Pointeur vers une valeur qui spécifie le nombre d’octets de données valides dans le tableau de données clé vers lequel pointe le paramètre ppucKeyData , si l’appel à la fonction WlanHostedNetworkQuerySecondaryKey réussit.

Cette longueur de clé inclut la fin « \0 » si la clé est une phrase secrète.

[out] ppucKeyData

Pointeur vers une valeur qui reçoit un pointeur vers la mémoire tampon retournée avec les données de clé de sécurité secondaires, si l’appel à la fonction WlanHostedNetworkQuerySecondaryKey réussit.

[out] pbIsPassPhrase

Pointeur vers une valeur booléenne qui indique si le tableau de données clés pointé par le paramètre ppucKeyData est au format de phrase secrète.

Si ce paramètre a la valeur TRUE, le tableau de données clés est au format de phrase secrète. Si ce paramètre a la valeur FALSE, le tableau de données clés n’est pas au format de phrase secrète.

[out] pbPersistent

Pointeur vers une valeur booléenne qui indique si le tableau de données clés pointé par le paramètre ppucKeyData doit être stocké et réutilisé ultérieurement ou pour une utilisation unique.

Si ce paramètre a la valeur TRUE, le tableau de données clés doit être stocké et réutilisé ultérieurement. Si ce paramètre a la valeur FALSE, le tableau de données clés est destiné à une utilisation unique.

[out, optional] pFailReason

Pointeur facultatif vers une valeur qui reçoit la raison de l’échec, si l’appel à la fonction WlanHostedNetworkSetSecondaryKey échoue. Les valeurs possibles pour la raison de l’échec proviennent du type d’énumération WLAN_HOSTED_NETWORK_REASON défini dans le fichier d’en-tête Wlanapi.h .

pvReserved

Réservé pour un usage futur. Ce paramètre doit être 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_HANDLE	Un handle n’est pas valide. Cette erreur est retournée si le handle spécifié dans le paramètre hClientHandle est introuvable dans la table de handle.
ERROR_INVALID_PARAMETER	Un paramètre est incorrect. Cette erreur est retournée si l’une des conditions suivantes se produit : hClientHandle a la valeur NULL. pdwKeyLength a la valeur NULL. ppucKeyData est NULL ou non valide. pbIsPassPhrase est NULL ou non valide. pbPersistent a la valeur NULL. pvReserved n’est pas NULL.
ERROR_INVALID_STATE	La ressource n’est pas dans l’état correct pour effectuer l’opération demandée. Cela peut se produire si le réseau hébergé sans fil était en cours d’arrêt.
ERROR_OUTOFMEMORY	Espace de stockage insuffisant pour terminer cette opération.
ERROR_SERVICE_NOT_ACTIVE	Le service n'a pas été démarré. Cette erreur est retournée si le service de configuration automatique WLAN n’est pas en cours d’exécution.
Autres	Divers codes d’erreur RPC et autres. Utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée.

Remarques

La fonction WlanHostedNetworkQuerySecondaryKey est une extension des API sans fil natives ajoutées pour prendre en charge le réseau hébergé sans fil sur Windows 7 et Windows Server 2008 R2 avec le service LAN sans fil installé.

Une application cliente appelle la fonction WlanHostedNetworkQuerySecondaryKey pour interroger la clé de sécurité secondaire qui sera utilisée par le réseau hébergé sans fil. Cette fonction retourne les informations de clé, y compris les données de clé, la longueur de la clé, s’il s’agit d’une phrase secrète et si elle est persistante ou pour une utilisation unique. Cette fonction ne modifie pas l’état ou les propriétés du réseau hébergé sans fil.

La clé de sécurité secondaire est une phrase secrète si la valeur pointée par le paramètre pbIsPassPhrase est TRUE. La clé de sécurité secondaire est une clé binaire si la valeur pointée par le paramètre pbIsPassPhrase est FALSE.

La clé de sécurité secondaire retournée dans la mémoire tampon vers laquelle pointe le paramètre ppucKeyData est utilisée avec l’authentification WPA2-Personal et est dans l’un des formats suivants :

Phrase secrète de clé qui se compose d’un tableau de caractères ASCII compris entre 8 et 63 caractères. La valeur pointée par le paramètre pdwKeyLength inclut la fin « \0 » dans la phrase secrète. La valeur pointée par le paramètre pdwKeyLength doit être comprise entre 9 et 64.
Clé binaire qui se compose de 32 octets de données de clé binaire. La valeur pointée par le paramètre pdwKeyLength doit être 32 pour la clé binaire.

La clé de sécurité secondaire est persistante si la valeur pointée par le paramètre pbPersistent est TRUE. En cas de persistance, la clé de sécurité secondaire est utilisée immédiatement si le réseau hébergé est déjà démarré, et également réutilisée chaque fois que le réseau hébergé est démarré à l’avenir.

Si la clé de sécurité secondaire n’est pas spécifiée comme persistante, elle est utilisée immédiatement si le réseau hébergé est déjà démarré, ou uniquement pour la prochaine fois que le réseau hébergé sera démarré. Une fois le réseau hébergé arrêté, cette clé de sécurité secondaire ne sera plus jamais utilisée et supprimée du système.

Si aucune clé de sécurité secondaire n’est actuellement configurée, la valeur renvoyée pointée vers le paramètre pdwKeyLength est égale à zéro et la valeur retournée dans le paramètre ppucKeyData est NULL. Dans ce cas, la valeur retournée dans les paramètres pbIsPassPhrase et pbPersistent n’aura aucun sens.

Si la fonction WlanHostedNetworkQuerySecondaryKey réussit, la mémoire utilisée pour la mémoire tampon dans le paramètre ppucKeyData retourné doit être libérée après utilisation en appelant la fonction WlanFreeMemory .

Tout utilisateur peut appeler la fonction WlanHostedNetworkQuerySecondaryKey pour interroger la clé de sécurité secondaire utilisée dans le réseau hébergé. Toutefois, la possibilité d’activer le réseau hébergé sans fil peut être limitée par la stratégie de groupe dans un domaine.

Sur Windows 7 et versions ultérieures, le système d’exploitation installe un appareil virtuel si une carte sans fil compatible réseau hébergé est présente sur l’ordinateur. Cet appareil virtuel s’affiche normalement dans le dossier Connexions réseau sous la forme « Connexion réseau sans fil 2 » avec le nom de l’appareil « Carte miniport Microsoft Virtual WiFi » si l’ordinateur dispose d’une seule carte réseau sans fil. Cet appareil virtuel est utilisé exclusivement pour effectuer des connexions de point d’accès logiciel (SoftAP) et n’est pas présent dans la liste retournée par la fonction WlanEnumInterfaces . La durée de vie de cet appareil virtuel est liée à l’adaptateur sans fil physique. Si l’adaptateur sans fil physique est désactivé, cet appareil virtuel est également supprimé. Cette fonctionnalité est également disponible sur Windows Server 2008 R2 avec le service LAN sans fil installé.

Spécifications


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