Fonction WlanHostedNetworkSetProperty (wlanapi.h)

Article
03/13/2024

La fonction WlanHostedNetworkSetProperty définit les propriétés statiques du réseau hébergé sans fil.

Syntaxe

DWORD WlanHostedNetworkSetProperty(
  [in]            HANDLE                      hClientHandle,
  [in]            WLAN_HOSTED_NETWORK_OPCODE  OpCode,
  [in]            DWORD                       dwDataSize,
  [in]            PVOID                       pvData,
  [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] OpCode

Identificateur de la propriété à définir. Cet identificateur ne peut être que les valeurs suivantes dans l’énumération WLAN_HOSTED_NETWORK_OPCODE définie dans le fichier d’en-tête Wlanapi.h :

wlan_hosted_network_opcode_connection_settings

Paramètres de connexion au réseau hébergé.

wlan_hosted_network_opcode_enable

Indicateur Réseau hébergé activé.

[in] dwDataSize

Valeur qui spécifie la taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre pvData .

[in] pvData

Pointeur vers une mémoire tampon avec la propriété statique à définir. Le type de données associé à cette mémoire tampon dépend de la valeur du paramètre OpCode .

[out, optional] pFailReason

Pointeur facultatif vers une valeur qui reçoit la raison de l’échec, si l’appel à la fonction WlanHostedNetworkSetProperty é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. Cette erreur est également retournée si le paramètre OpCode a été wlan_hosted_network_opcode_enable et que le réseau hébergé sans fil est désactivé par la stratégie de groupe sur un domaine.
ERROR_BAD_PROFILE	Le profil de connexion réseau utilisé par le réseau hébergé sans fil est endommagé.
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. OpCode ne fait pas partie des valeurs énumérées définies dans le WLAN_HOSTED_NETWORK_OPCODE. dwDataSize est égal à zéro. pvData a la valeur NULL. pvData ne pointe pas vers une propriété statique 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_NOT_SUPPORTED	La demande n'est pas prise en charge. Cette erreur est retournée si l’application appelle la fonction WlanHostedNetworkSetProperty avec le paramètre OpCode défini sur wlan_hosted_network_opcode_station_profile ou wlan_hosted_network_opcode_security_settings.
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 WlanHostedNetworkSetProperty 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 WlanHostedNetworkSetProperty pour définir les propriétés statiques actuelles du réseau hébergé sans fil. Toute modification de propriété de 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.

Le type de données associé à la mémoire tampon pointée par le paramètre pvData dépend de la valeur du paramètre OpCode comme suit :

OpCode	Description
wlan_hosted_network_opcode_connection_settings	Un pointeur vers une structure WLAN_HOSTED_NETWORK_CONNECTION_SETTINGS est passé dans le paramètre pvData .
wlan_hosted_network_opcode_enable	Un pointeur vers BOOL est passé dans le paramètre pvData .

Si la fonction WlanHostedNetworkSetProperty est appelée avec le paramètre OpCode défini sur wlan_hosted_network_opcode_enable, l’utilisateur doit disposer 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 la fonction WlanHostedNetworkSetProperty avec le paramètre OpCode de wlan_hosted_network_opcode_enable, le jeton d’accès client de l’appelant doit disposer de privilèges élevés exposés par l’énumération suivante dans WLAN_SECURABLE_OBJECT :

wlan_secure_hosted_network_elevated_access

Si l’une des valeurs suivantes est transmise à la fonction WlanHostedNetworkSetProperty dans le paramètre OpCode , la fonction échoue avec ERROR_NOT_SUPPORTED :

wlan_hosted_network_opcode_station_profile
wlan_hosted_network_opcode_connection_settings

Pour réussir, la fonction WlanHostedNetworkSetProperty doit conserver les nouveaux paramètres, ce qui nécessite la transition de l’état du réseau hébergé vers wlan_hosted_network_idle s’il était en cours d’exécution (wlan_hosted_network_active).

Tout utilisateur peut appeler cette fonction pour définir les propriétés du réseau hébergé. Toutefois, pour définir l’indicateur wlan_hosted_network_opcode_enable nécessite des privilèges élevés. 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 « 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