Fonction WlanSetProfile (wlanapi.h)

Article
12/22/2023

La fonction WlanSetProfile définit le contenu d’un profil spécifique.

Syntaxe

DWORD WlanSetProfile(
  [in]           HANDLE     hClientHandle,
  [in]           const GUID *pInterfaceGuid,
  [in]           DWORD      dwFlags,
  [in]           LPCWSTR    strProfileXml,
  [in, optional] LPCWSTR    strAllUserProfileSecurity,
  [in]           BOOL       bOverwrite,
  [in]           PVOID      pReserved,
  [out]          DWORD      *pdwReasonCode
);

Paramètres

[in] hClientHandle

Le handle de session du client, obtenu par un appel précédent à la fonction WlanOpenHandle .

[in] pInterfaceGuid

GUID de l’interface.

[in] dwFlags

Indicateurs à définir sur le profil.

Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : dwFlags doit être 0. Les profils par utilisateur ne sont pas pris en charge.

Valeur	Signification
0	Le profil est un profil tout utilisateur.
WLAN_PROFILE_GROUP_POLICY 0x00000001	Le profil est un profil de stratégie de groupe.
WLAN_PROFILE_USER 0x00000002	Le profil est un profil par utilisateur.

[in] strProfileXml

Contient la représentation XML du profil. L’élément WLANProfile est l’élément de profil racine. Pour afficher les exemples de profils, consultez Exemples de profils sans fil. Il n’existe aucune longueur de chaîne maximale prédéfinie.

Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Le profil fourni doit répondre aux critères de compatibilité décrits dans Compatibilité des profils sans fil.

[in, optional] strAllUserProfileSecurity

Définit la chaîne de descripteur de sécurité sur le profil tout utilisateur. Pour plus d’informations sur les autorisations de profil, consultez la section Remarques.

Si dwFlags a la valeur WLAN_PROFILE_USER, ce paramètre est ignoré.

Si ce paramètre a la valeur NULL pour un nouveau profil tout utilisateur, le descripteur de sécurité associé à l’objet wlan_secure_add_new_all_user_profiles est utilisé. Si le descripteur de sécurité n’a pas été modifié par un appel WlanSetSecuritySettings , tous les utilisateurs disposent d’autorisations par défaut sur un nouveau profil utilisateur. Appelez WlanGetSecuritySettings pour obtenir les autorisations par défaut associées à l’objet wlan_secure_add_new_all_user_profiles.

Si ce paramètre est défini sur NULL pour un profil tout utilisateur existant, les autorisations du profil ne sont pas modifiées.

Si ce paramètre n’a pas la valeur NULL pour un profil tout utilisateur, la chaîne de descripteur de sécurité associée au profil est créée ou modifiée après la création et l’analyse de l’objet de descripteur de sécurité en tant que chaîne.

Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Ce paramètre doit avoir la valeur NULL.

[in] bOverwrite

Spécifie si ce profil remplace un profil existant. Si ce paramètre a la valeur FALSE et que le profil existe déjà, le profil existant n’est pas remplacé et une erreur est retournée.

[in] pReserved

Réservé pour un usage futur. Doit être défini sur NULL.

[out] pdwReasonCode

Valeur WLAN_REASON_CODE qui indique pourquoi le profil n’est pas valide.

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 pour définir le profil. Lorsqu’il est appelé avec dwFlags défini sur 0 (autrement dit, lors de la définition d’un profil tout utilisateur), WlanSetProfile récupère la liste de contrôle d’accès discrétionnaire (DACL) stockée avec l’objet wlan_secure_add_new_all_user_profiles . Lorsqu’il est appelé avec dwFlags défini sur WLAN_PROFILE_USER ( autrement dit, lors de la définition d’un profil par utilisateur), WlanSetProfile récupère la liste de contrôle d’accès discrétionnaire (DACL) stockée avec l’objet wlan_secure_add_new_per_user_profiles . Dans les deux cas, si la liste DACL ne contient pas d’entrée de contrôle d’accès (ACE) qui accorde WLAN_WRITE_ACCESS autorisation au jeton d’accès du thread appelant, WlanSetProfile retourne ERROR_ACCESS_DENIED.
ERROR_ALREADY_EXISTS	strProfileXml spécifie un réseau qui existe déjà. En règle générale, cette valeur de retour est utilisée lorsque bOverwrite a la valeur FALSE ; toutefois, si bOverwrite a la valeur TRUE et que dwFlags spécifie un type de profil différent de celui utilisé par le profil existant, le profil existant ne sera pas remplacé et ERROR_ALREADY_EXISTS sera retourné.
ERROR_BAD_PROFILE	Le profil spécifié par strProfileXml n’est pas valide. Si cette valeur est retournée, pdwReasonCode spécifie la raison pour laquelle le profil n’est pas valide.
ERROR_INVALID_PARAMETER	L’une des conditions suivantes s’est produite : hClientHandle a la valeur NULL ou non valide. pInterfaceGuid a la valeur NULL. pReserved n’a pas la valeur NULL. strProfileXml a la valeur NULL. [ConfigBlob] (/windows/desktop/eaphost/eaphostconfigschema-configblob-eaphostconfig-element). Si le profil doit avoir un ConfigBlob vide, utilisez `<ConfigBlob>00</ConfigBlob>` dans le profil. pdwReasonCode a la valeur NULL. dwFlags n’est pas défini sur l’une des valeurs spécifiées. dwFlags a la valeur WLAN_PROFILE_GROUP_POLICY et bOverwrite a la valeur FALSE.
ERROR_NO_MATCH	L’interface ne prend pas en charge une ou plusieurs des fonctionnalités spécifiées dans le profil. Par exemple, si un profil spécifie l’utilisation de WPA2 lorsque la carte réseau prend uniquement en charge WPA, ce code d’erreur est retourné. En outre, si un profil spécifie l’utilisation du mode FIPS lorsque la carte réseau ne prend pas en charge le mode FIPS, ce code d’erreur est retourné.
RPC_STATUS	Différents codes d’erreur.

Remarques

La fonction WlanSetProfile peut être utilisée pour ajouter un nouveau profil LAN sans fil ou remplacer un profil LAN sans fil existant.

Un nouveau profil est ajouté en haut de la liste après les profils de stratégie de groupe. La position d’un profil dans la liste n’est pas modifiée si un profil existant est remplacé. Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 :

Les profils ad hoc apparaissent après les profils d’infrastructure dans la liste des profils. Si vous créez un profil ad hoc, il est placé en haut de la liste ad hoc, après les profils de stratégie de groupe et d’infrastructure.

Les profils invités 802.1X, les profils WPS (Wireless Provisioning Service) et les profils avec l’authentification Wi-Fi protégée Access-None (WPA-None) ne sont pas pris en charge. Cela signifie qu’un tel profil ne peut pas être créé, supprimé, énuméré ou accessible à l’aide des fonctions Native Wifi. Tout profil de ce type déjà dans la liste des profils préférés reste dans la liste, et sa position dans la liste par rapport aux autres profils est corrigée, sauf si la position des autres profils change.

Vous pouvez appeler WlanSetProfile sur un profil qui contient une clé en texte clair (c’est-à-dire un profil avec l’élément protégé présent et défini sur FALSE). Avant que le profil ne soit enregistré dans le magasin de profils, le matériel clé est automatiquement chiffré. Lorsque le profil est ensuite récupéré à partir du magasin de profils en appelant WlanGetProfile, le matériel de clé chiffré est retourné. Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Le matériel clé n’est jamais chiffré.

Les profils tous les utilisateurs ont trois autorisations associées : lire, écrire et exécuter. Si un utilisateur dispose d’un accès en lecture, il peut afficher les autorisations de profil. Si un utilisateur a un accès d’exécution, l’utilisateur dispose d’un accès en lecture et l’utilisateur peut également se connecter à un réseau et se déconnecter d’un réseau à l’aide du profil. Si un utilisateur dispose d’un accès en écriture, l’utilisateur dispose d’un accès d’exécution et l’utilisateur peut également modifier et supprimer des autorisations associées à un profil.

L’article suivant décrit la procédure permettant de créer un objet de descripteur de sécurité et de l’analyser en tant que chaîne.

Appelez InitializeSecurityDescriptor pour créer un descripteur de sécurité en mémoire.
Appelez SetSecurityDescriptorOwner.
Appelez InitializeAcl pour créer une liste de contrôle d’accès discrétionnaire (DACL) en mémoire.
Appelez AddAccessAllowedAce ou AddAccessDeniedAce pour ajouter des entrées de contrôle d’accès (AAC) au DACL. Définissez le paramètre AccessMask sur l’un des éléments suivants, le cas échéant :
- WLAN_READ_ACCESS
- WLAN_EXECUTE_ACCESS
- WLAN_WRITE_ACCESS
Appelez SetSecurityDescriptorDacl pour ajouter la liste DACL au descripteur de sécurité.
Appelez ConvertSecurityDescriptorToStringSecurityDescriptor pour convertir le descripteur en chaîne.

La chaîne retournée par ConvertSecurityDescriptorToStringSecurityDescriptor peut ensuite être utilisée comme valeur de paramètre strAllUserProfileSecurity lors de l’appel de WlanSetProfile.

Pour chaque profil LAN sans fil utilisé par le service Native Wifi AutoConfig, Windows conserve le concept de données utilisateur personnalisées. Ces données utilisateur personnalisées sont initialement inexistantes, mais peuvent être définies en appelant la fonction WlanSetProfileCustomUserData . Les données utilisateur personnalisées sont réinitialisées à chaque fois que le profil est modifié en appelant la fonction WlanSetProfile . Une fois les données utilisateur personnalisées définies, ces données sont accessibles à l’aide de la fonction WlanGetProfileCustomUserData .

Toutes les fonctions LAN sans fil nécessitent un GUID d’interface pour l’interface sans fil lors de l’exécution d’opérations de profil. Lorsqu’une interface sans fil est supprimée, son état est effacé du service LAN sans fil (WLANSVC) et aucune opération de profil n’est possible.

La fonction WlanSetProfile peut échouer avec ERROR_INVALID_PARAMETER si l’interface sans fil spécifiée dans le paramètre pInterfaceGuid a été supprimée du système (un adaptateur sans fil USB qui a été supprimé, par exemple).

La commande netsh wlan add profile fournit des fonctionnalités similaires sur la ligne de commande. Pour plus d’informations, consultez Commandes Netsh pour le réseau local sans fil (wlan).

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista, Windows XP avec SP3 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wlanapi.h (incluez Wlanapi.h)
Bibliothèque	Wlanapi.lib
DLL	Wlanapi.dll
Composant redistribuable	API LAN sans fil pour Windows XP avec SP2