Fonction WlanHostedNetworkInitSettings (wlanapi.h)

Article
03/13/2024

La fonction WlanHostedNetworkInitSettings configure et conserve les paramètres de connexion réseau (SSID et nombre maximal d’homologues, par exemple) sur le réseau hébergé sans fil si ces paramètres ne sont pas déjà configurés.

Syntaxe

DWORD WlanHostedNetworkInitSettings(
  [in]            HANDLE                      hClientHandle,
  [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, optional] pFailReason

Pointeur facultatif vers une valeur qui reçoit la raison de l’échec si l’appel à la fonction WlanHostedNetworkInitSettings é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. pvReserved n’est pas NULL.
ERROR_INVALID_STATE	La ressource n’est pas dans l’état correct pour effectuer l’opération demandée.
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 WlanHostedNetworkInitSettings 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 WlanHostedNetworkInitSettings pour configurer et conserver les paramètres de connexion réseau (SSID et nombre maximal d’homologues, par exemple) sur le réseau hébergé sans fil, si les paramètres de connexion ne sont pas déjà configurés. Si les paramètres réseau sur les paramètres réseau hébergé sans fil sont déjà configurés (la fonction WlanHostedNetworkQueryProperty ne retourne pas ERROR_BAD_CONFIGURATION pour le profil de station ou les paramètres de connexion), cet appel de fonction retourne ERROR_SUCCESS sans modifier la configuration des paramètres de connexion réseau.

Une application cliente doit toujours appeler la fonction WlanHostedNetworkInitSettings avant d’utiliser d’autres fonctionnalités de réseau hébergé sur l’ordinateur local. Cette fonction initialise les paramètres requis lorsque le réseau hébergé sans fil est utilisé pour la première fois sur un ordinateur local. La fonction WlanHostedNetworkInitSettings ne modifie aucune configuration si la configuration a déjà été conservée. Il est donc sûr d’appeler la fonction WlanHostedNetworkInitSettings si la configuration a déjà été conservée. Il est recommandé que les applications qui utilisent un réseau hébergé appellent la fonction WlanHostedNetworkInitSettings avant d’utiliser d’autres fonctions de réseau hébergé.

La fonction WlanHostedNetworkInitSettings calcule un SSID aléatoire et lisible à partir du nom d’hôte et calcule une clé primaire aléatoire. Cette fonction utilise également définit une valeur pour le nombre maximal d’homologues autorisés dont la valeur par défaut est 100. Si une application souhaite utiliser un SSID différent ou un nombre maximal différent d’homologues, l’application doit appeler la fonction WlanHostedNetworkSetProperty pour définir spécifiquement ces propriétés utilisées par le réseau hébergé sans fil.

Tout changement d’état du réseau hébergé provoqué par cette fonction ne serait pas automatiquement annulé si l’application appelante ferme son handle d’appel (en appelant WlanCloseHandle avec le paramètre hClientHandle ) ou si le processus se termine.

Tout utilisateur peut appeler la fonction WlanHostedNetworkInitSettings pour configurer et conserver les paramètres de connexion réseau de stockage sur le réseau hébergé. Si le réseau hébergé sans fil a déjà été configuré, cette fonction ne fait rien et retourne ERROR_SUCCESS.

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 « Network Connections » en tant que « Connexion réseau sans fil 2 » avec le nom de l’appareil « Microsoft Virtual WiFi Miniport adapter » 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é.

Configuration requise

Condition requise	Valeur
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