Fonction WlanHostedNetworkForceStart (wlanapi.h)

Article
08/28/2023

La fonction WlanHostedNetworkForceStart transfère le réseau hébergé sans fil vers l’état wlan_hosted_network_active sans associer la requête au handle d’appel de l’application.

Syntaxe

DWORD WlanHostedNetworkForceStart(
  [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 WlanHostedNetworkForceStart é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_ACCESS_DENIED	L’appelant ne dispose pas des autorisations suffisantes.
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. Cette erreur est retournée si le réseau hébergé sans fil est désactivé par la stratégie de groupe sur un domaine.
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 WlanHostedNetworkForceStart 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 WlanHostedNetworkForceStart pour forcer le démarrage du réseau hébergé sans fil en faisant passer le réseau hébergé sans fil à l’état wlan_hosted_network_active sans associer la demande au handle d’appel de l’application. Un appel réussi à la fonction WlanHostedNetworkForceStart doit finalement être mis en correspondance par un appel à la fonction WlanHostedNetworkForceStop . 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.

Le coût d’appel de la fonction WlanHostedNetworkForceStart par rapport à l’appel de WlanHostedNetworkStartUsing est le privilège associé requis. Une application peut appeler la fonction WlanHostedNetworkForceStart après s’être assuré qu’un utilisateur système avec élévation de privilèges accepte les exigences d’alimentation accrues impliquées dans l’exécution du réseau hébergé sans fil pendant de longues durées.

La fonction WlanHostedNetworkForceStart peut échouer si l’état du réseau hébergé est wlan_hosted_network_unavailable ou si l’appelant ne dispose pas de privilèges suffisants.

Cette fonction pour forcer le démarrage du réseau hébergé ne peut être appelée que si l’utilisateur dispose du privilège associé approprié. Les autorisations sont stockées dans une liste de contrôle d’accès discrétionnaire (DACL) associée à un WLAN_SECURABLE_OBJECT. Pour appeler le WlanHostedNetworkForceStart, le jeton d’accès client de l’appelant doit avoir des privilèges élevés exposés par l’énumération suivante dans WLAN_SECURABLE_OBJECT :

wlan_secure_hosted_network_elevated_access

La possibilité d’activer le réseau hébergé sans fil peut également être limitée par une 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