Fonction WlanHostedNetworkSetSecondaryKey (wlanapi.h)
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 |
|---|---|
|
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. |
|
Un paramètre est incorrect. Cette erreur est retournée si l’une des conditions suivantes se produit :
|
|
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. |
|
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. |
|
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 |
Voir aussi
À propos du réseau hébergé sans fil
Utilisation du réseau hébergé sans fil et du partage de connexion Internet
WlanHostedNetworkQueryProperty
WlanHostedNetworkQuerySecondaryKey