Fonction WlanHostedNetworkSetSecondaryKey (wlanapi.h)

Article
08/28/2023

La fonction WlanHostedNetworkSetSecondaryKey configure la clé de sécurité secondaire qui sera utilisée par le réseau hébergé sans fil.

Syntaxe

DWORD WlanHostedNetworkSetSecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [in]            DWORD                       dwKeyLength,
  [in]            PUCHAR                      pucKeyData,
  [in]            BOOL                        bIsPassPhrase,
  [in]            BOOL                        bPersistent,
  [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 .

[in] dwKeyLength

Nombre d’octets de données valides dans le tableau de données clé pointé par le paramètre pucKeyData . Cette longueur de clé doit inclure la fin « \0 » si la clé est une phrase secrète.

[in] pucKeyData

Pointeur vers une mémoire tampon qui contient les données de clé. Le nombre d’octets de données valides dans la mémoire tampon doit être au moins la valeur spécifiée dans le paramètre dwKeyLength .

[in] bIsPassPhrase

Valeur booléenne qui indique si le tableau de données clés pointé par le paramètre pucKeyData 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.

[in] bPersistent

Valeur booléenne qui indique si le tableau de données clés vers lequel pointe le paramètre pucKeyData 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 doit être utilisé pour une session (la session active ou la session suivante si le réseau hébergé n’est pas démarré).

[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. pucKeyData a la valeur NULL. pucKeyData ne pointe pas vers une clé valide bien formée. 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_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 WlanHostedNetworkSetSecondaryKey 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 WlanHostedNetworkSetSecondaryKey pour configurer la clé de sécurité secondaire qui sera utilisée par le réseau hébergé sans fil. Toute modification du réseau hébergé provoquée par cette fonction ne serait pas automatiquement annulée si l’application appelante ferme son handle d’appel (en appelant WlanCloseHandle avec le paramètre hClientHandle ) ou si le processus se termine.

Une fois démarré, le réseau hébergé sans fil autorise les homologues sans fil à s’associer à cette clé de sécurité secondaire en plus de la clé de sécurité primaire. La clé de sécurité secondaire est toujours spécifiée par l’utilisateur en fonction des besoins, tandis que la clé de sécurité primaire est générée par le système d’exploitation avec une plus grande sécurité.

La clé de sécurité secondaire passée dans la mémoire tampon vers laquelle pointe le paramètre pucKeyData est utilisée avec l’authentification WPA2-Personal et doit être 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. Le paramètre dwKeyLength doit inclure la phrase secrète « \0 » de fin. La valeur du paramètre dwKeyLength doit être comprise entre 9 et 64.
Clé binaire qui se compose de 32 octets de données de clé binaire. Le paramètre dwKeyLength doit être 32 pour la clé binaire.

Pour configurer une clé de sécurité secondaire valide, le paramètre dwKeyLength doit être dans la plage correcte et le paramètre pucKeyData doit pointer vers une mémoire tampon valide contenant les octets de données spécifiés. Pour supprimer la clé de sécurité secondaire actuellement configurée du système, l’application doit appeler la fonction WlanHostedNetworkSetSecondaryKey avec zéro dans le paramètre dwKeyLength et NULL dans le paramètre pucKeyData .

La fonction WlanHostedNetworkSetSecondaryKey retourne ERROR_INVALID_PARAMETER si le paramètre pucKeyData a la valeur NULL, mais que le paramètre dwKeyLength n’est pas égal à zéro. La fonction WlanHostedNetworkSetSecondaryKey retourne également ERROR_INVALID_PARAMETER si le paramètre dwKeyLength est égal à zéro, mais que le paramètre pucKeyData n’a pas la valeur NULL.

La clé de sécurité secondaire est généralement définie avant le démarrage du réseau hébergé sans fil. Ensuite, il sera utilisé la prochaine fois que le réseau hébergé sera démarré.

Une clé de sécurité secondaire peut également être définie après le démarrage du réseau hébergé. Dans ce cas, la clé de sécurité secondaire est utilisée immédiatement. Tous les clients utilisant la clé de sécurité secondaire précédente resteront connectés, mais ils ne pourront pas se reconnecter s’ils sont déconnectés pour une raison quelconque ou si le réseau hébergé sans fil est redémarré.

La clé de sécurité secondaire peut être spécifiée comme persistante si le paramètre bPersistent a la valeur TRUE. Quand elle est spécifiée comme persistante, 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é est 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.

Tout utilisateur peut appeler cette fonction pour configurer la clé de sécurité secondaire à utiliser 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