Fonction WlanGetProfile (wlanapi.h)
La fonction WlanGetProfile récupère toutes les informations sur un profil sans fil spécifié.
Syntaxe
DWORD WlanGetProfile(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[in] LPCWSTR strProfileName,
[in] PVOID pReserved,
[out] LPWSTR *pstrProfileXml,
[in, out, optional] DWORD *pdwFlags,
[out, optional] DWORD *pdwGrantedAccess
);
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 sans fil.
Une liste des GUID pour les interfaces sans fil sur l’ordinateur local peut être récupérée à l’aide de la fonction WlanEnumInterfaces .
[in] strProfileName
Nom du profil. Les noms de profil respectent la casse. Cette chaîne doit être terminée par null. La longueur maximale du nom du profil est de 255 caractères. Cela signifie que la longueur maximale de cette chaîne, y compris la terminaison NULL, est de 256 caractères.
Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Le nom du profil est dérivé automatiquement du SSID du réseau. Pour les profils réseau d’infrastructure, le nom du profil est le SSID du réseau. Pour les profils réseau ad hoc, le nom du profil est le SSID du réseau ad hoc suivi de -adhoc.
[in] pReserved
Réservé pour un usage futur. Doit être défini sur NULL.
[out] pstrProfileXml
Chaîne qui est la représentation XML du profil interrogé. Il n’existe aucune longueur de chaîne maximale prédéfinie.
[in, out, optional] pdwFlags
Lors de l’entrée, pointeur vers l’emplacement d’adresse utilisé pour fournir des informations supplémentaires sur la demande. Si ce paramètre a la valeur NULL lors de l’entrée, aucune information sur les indicateurs de profil n’est retournée. Lors de la sortie, un pointeur vers l’emplacement d’adresse utilisé pour recevoir les indicateurs de profil.
Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Les profils par utilisateur ne sont pas pris en charge. Définissez ce paramètre sur NULL.
Le paramètre pdwFlags peut pointer vers un emplacement d’adresse qui contient les valeurs suivantes :
| Valeur | Signification |
|---|---|
|
Lors de l’entrée, cet indicateur indique que l’appelant souhaite récupérer la clé de texte brut à partir d’un profil sans fil. Si le thread appelant dispose des autorisations requises, la fonction WlanGetProfile retourne la clé de texte brut dans l’élément keyMaterial du profil retourné dans la mémoire tampon vers laquelle pointe le paramètre pstrProfileXml .
Pour que l’appel WlanGetProfile retourne la clé de texte brut, les autorisations wlan_secure_get_plaintext_key du type énuméré WLAN_SECURABLE_OBJECT doivent être définies sur le thread appelant. Le DACL doit également contenir un ACE qui accorde WLAN_READ_ACCESS autorisation au jeton d’accès du thread appelant. Par défaut, les autorisations de récupération de la clé de texte brut sont autorisées uniquement aux membres du groupe Administrateurs sur un ordinateur local. Si le thread appelant ne dispose pas des autorisations requises, la fonction WlanGetProfile retourne la clé chiffrée dans l’élément keyMaterial du profil retourné dans la mémoire tampon vers laquelle pointe le paramètre pstrProfileXml . Aucune erreur n’est retournée si le thread appelant ne dispose pas des autorisations requises. Windows 7 : Cet indicateur transmis à l’entrée est une extension des API sans fil natives ajoutées sur Windows 7 et versions ultérieures. Le paramètre pdwFlags est un paramètre __inout_opt sur Windows 7 et versions ultérieures. |
|
Lors de la sortie lorsque l’appel WlanGetProfile réussit, cet indicateur indique que ce profil a été créé par la stratégie de groupe. Un profil de stratégie de groupe est en lecture seule. Ni le contenu ni l’ordre de préférence du profil ne peuvent être modifiés. |
|
Lors de la sortie lorsque l’appel WlanGetProfile réussit, cet indicateur indique que le profil est un profil utilisateur pour l’utilisateur spécifique dans lequel réside le thread appelant. S’il n’est pas défini, ce profil est un profil tout utilisateur. |
[out, optional] pdwGrantedAccess
Masque d’accès du profil tout utilisateur.
| Valeur | Signification |
|---|---|
|
L’utilisateur peut afficher le contenu du profil. |
|
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 a WLAN_EXECUTE_ACCESS, il a également WLAN_READ_ACCESS. |
|
L’utilisateur dispose d’un accès d’exécution et l’utilisateur peut également modifier le contenu du profil ou supprimer le profil. Si un utilisateur a WLAN_WRITE_ACCESS, il a également WLAN_EXECUTE_ACCESS et WLAN_READ_ACCESS. |
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 |
|---|---|
|
L’appelant n’a pas les autorisations suffisantes. Cette erreur est retournée si le paramètre pstrProfileXml spécifie un profil tout utilisateur, mais que l’appelant n’a pas d’accès en lecture sur le profil. |
|
Un handle n’est pas valide. Cette erreur est retournée si le handle spécifié dans le paramètre hClientHandle n’a pas été trouvé dans la table handle. |
|
Un paramètre est incorrect. Cette erreur est retournée si l’une des conditions suivantes se produit :
|
|
Le stockage disponible est insuffisant pour traiter cette commande. Cette erreur est retournée si le système n’a pas pu allouer de mémoire pour le profil. |
|
Le profil spécifié par strProfileName est introuvable. |
|
Divers codes d’erreur RPC et autres. Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée. |
Remarques
Si la fonction WlanGetProfile réussit, le profil sans fil est retourné dans la mémoire tampon vers laquelle pointe le paramètre pstrProfileXml . La mémoire tampon contient une chaîne qui est la représentation XML du profil interrogé. Pour obtenir une description de la représentation XML du profil sans fil, consultez schéma WLAN_profile.
L’appelant est chargé d’appeler la fonction WlanFreeMemory pour libérer la mémoire allouée pour le pointeur de mémoire tampon vers par le paramètre pstrProfileXml lorsque la mémoire tampon n’est plus nécessaire.
Si pstrProfileXml spécifie un profil pour tous les utilisateurs, l’appelant WlanGetProfile doit disposer d’un accès en lecture sur le profil. Sinon, l’appel WlanGetProfile échoue avec une valeur de retour de ERROR_ACCESS_DENIED. Les autorisations sur un profil tout utilisateur sont établies lorsque le profil est créé ou enregistré à l’aide de WlanSetProfile ou de WlanSaveTemporaryProfile.
Windows 7 :
L’élément keyMaterial retourné dans le schéma de profil pointé vers par le pstrProfileXml peut être demandé en texte clair si la fonction WlanGetProfile est appelée avec l’indicateur WLAN_PROFILE_GET_PLAINTEXT_KEY défini dans la valeur pointée par le paramètre pdwFlags lors de l’entrée .
Pour une clé WEP, 5 caractères ASCII ou 10 caractères hexadécimaux peuvent être utilisés pour définir la clé en texte clair lors de la création ou de la mise à jour du profil. Toutefois, un profil WEP est enregistré avec 10 caractères hexadécimaux dans la clé, quelle que soit l’entrée d’origine utilisée pour créer le profil. Par conséquent, dans le profil retourné par la fonction WlanGetProfile , la clé WEP en texte clair est toujours renvoyée sous forme de 10 caractères hexadécimaux.
Pour que l’appel WlanGetProfile retourne la clé de texte brut, les autorisations wlan_secure_get_plaintext_key du type énuméré WLAN_SECURABLE_OBJECT doivent être définies sur le thread appelant. Le DACL doit également contenir un ACE qui accorde WLAN_READ_ACCESS autorisation au jeton d’accès du thread appelant. Par défaut, les autorisations de récupération de la clé de texte brut sont autorisées uniquement aux membres du groupe Administrateurs sur un ordinateur local.
Si le thread appelant ne dispose pas des autorisations requises, la fonction WlanGetProfile retourne la clé chiffrée dans l’élément keyMaterial du profil retourné dans la mémoire tampon vers laquelle pointe le paramètre pstrProfileXml . Aucune erreur n’est retournée si le thread appelant n’a pas les autorisations requises.
Par défaut, l’élément keyMaterial retourné dans le profil pointé par pstrProfileXml est chiffré. Si votre processus s’exécute dans le contexte du compte LocalSystem sur le même ordinateur, vous pouvez annuler le chiffrement du matériel de clé en appelant la fonction CryptUnprotectData .
Windows Server 2008 et Windows Vista : L’élément keyMaterial retourné dans le schéma de profil pointé par pstrProfileXml est toujours chiffré. Si votre processus s’exécute dans le contexte du compte LocalSystem, vous pouvez déchiffrer le matériel de clé en appelant la fonction CryptUnprotectData .
Windows XP avec SP3 et API LAN sans fil pour Windows XP avec SP2 : Le matériel de clé n’est jamais chiffré.
Exemples
L’exemple suivant énumère les interfaces LAN sans fil sur l’ordinateur local, récupère les informations d’un profil sans fil spécifique sur chaque interface LAN sans fil et imprime les valeurs récupérées. La chaîne qui est la représentation XML du profil interrogé est également imprimée.
#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <wlanapi.h>
#include <objbase.h>
#include <wtypes.h>
#include <stdio.h>
#include <stdlib.h>
// Need to link with Wlanapi.lib and Ole32.lib
#pragma comment(lib, "wlanapi.lib")
#pragma comment(lib, "ole32.lib")
int _cdecl wmain(int argc, WCHAR **argv)
{
// Declare and initialize variables.
HANDLE hClient = NULL;
DWORD dwMaxClient = 2; //
DWORD dwCurVersion = 0;
DWORD dwResult = 0;
DWORD dwRetVal = 0;
int iRet = 0;
WCHAR GuidString[39] = {0};
unsigned int i;
/* variables used for WlanEnumInterfaces */
PWLAN_INTERFACE_INFO_LIST pIfList = NULL;
PWLAN_INTERFACE_INFO pIfInfo = NULL;
LPCWSTR pProfileName = NULL;
LPWSTR pProfileXml = NULL;
DWORD dwFlags = 0;
DWORD dwGrantedAccess = 0;
// Validate the parameters
if (argc < 2) {
wprintf(L"usage: %s <profile>\n", argv[0]);
wprintf(L" Gets a wireless profile\n");
wprintf(L" Example\n");
wprintf(L" %s \"Default Wireless\"\n", argv[0]);
exit(1);
}
pProfileName = argv[1];
wprintf(L"Information for profile: %ws\n\n", pProfileName);
dwResult = WlanOpenHandle(dwMaxClient, NULL, &dwCurVersion, &hClient);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanOpenHandle failed with error: %u\n", dwResult);
return 1;
// You can use FormatMessage here to find out why the function failed
}
dwResult = WlanEnumInterfaces(hClient, NULL, &pIfList);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanEnumInterfaces failed with error: %u\n", dwResult);
return 1;
// You can use FormatMessage here to find out why the function failed
} else {
wprintf(L"WLAN_INTERFACE_INFO_LIST for this system\n");
wprintf(L"Num Entries: %lu\n", pIfList->dwNumberOfItems);
wprintf(L"Current Index: %lu\n\n", pIfList->dwIndex);
for (i = 0; i < (int) pIfList->dwNumberOfItems; i++) {
pIfInfo = (WLAN_INTERFACE_INFO *) &pIfList->InterfaceInfo[i];
wprintf(L" Interface Index[%u]:\t %lu\n", i, i);
iRet = StringFromGUID2(pIfInfo->InterfaceGuid, (LPOLESTR) &GuidString,
sizeof(GuidString)/sizeof(*GuidString));
// For c rather than C++ source code, the above line needs to be
// iRet = StringFromGUID2(&pIfInfo->InterfaceGuid, (LPOLESTR) &GuidString,
// sizeof(GuidString)/sizeof(*GuidString));
if (iRet == 0)
wprintf(L"StringFromGUID2 failed\n");
else {
wprintf(L" InterfaceGUID[%d]: %ws\n",i, GuidString);
}
wprintf(L" Interface Description[%d]: %ws", i,
pIfInfo->strInterfaceDescription);
wprintf(L"\n");
wprintf(L" Interface State[%d]:\t ", i);
switch (pIfInfo->isState) {
case wlan_interface_state_not_ready:
wprintf(L"Not ready\n");
break;
case wlan_interface_state_connected:
wprintf(L"Connected\n");
break;
case wlan_interface_state_ad_hoc_network_formed:
wprintf(L"First node in a ad hoc network\n");
break;
case wlan_interface_state_disconnecting:
wprintf(L"Disconnecting\n");
break;
case wlan_interface_state_disconnected:
wprintf(L"Not connected\n");
break;
case wlan_interface_state_associating:
wprintf(L"Attempting to associate with a network\n");
break;
case wlan_interface_state_discovering:
wprintf(L"Auto configuration is discovering settings for the network\n");
break;
case wlan_interface_state_authenticating:
wprintf(L"In process of authenticating\n");
break;
default:
wprintf(L"Unknown state %ld\n", pIfInfo->isState);
break;
}
wprintf(L"\n\n");
dwResult = WlanGetProfile(hClient,
&pIfInfo->InterfaceGuid,
pProfileName,
NULL,
&pProfileXml,
&dwFlags,
&dwGrantedAccess);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanGetProfile failed with error: %u\n",
dwResult);
// You can use FormatMessage to find out why the function failed
} else {
wprintf(L" Profile Name: %ws\n", pProfileName);
wprintf(L" Profile XML string:\n");
wprintf(L"%ws\n\n", pProfileXml);
wprintf(L" dwFlags:\t 0x%x", dwFlags);
// if (dwFlags & WLAN_PROFILE_GET_PLAINTEXT_KEY)
// wprintf(L" Get Plain Text Key");
if (dwFlags & WLAN_PROFILE_GROUP_POLICY)
wprintf(L" Group Policy");
if (dwFlags & WLAN_PROFILE_USER)
wprintf(L" Per User Profile");
wprintf(L"\n");
wprintf(L" dwGrantedAccess: 0x%x", dwGrantedAccess);
if (dwGrantedAccess & WLAN_READ_ACCESS)
wprintf(L" Read access");
if (dwGrantedAccess & WLAN_EXECUTE_ACCESS)
wprintf(L" Execute access");
if (dwGrantedAccess & WLAN_WRITE_ACCESS)
wprintf(L" Write access");
wprintf(L"\n");
wprintf(L"\n");
}
}
}
if (pProfileXml != NULL) {
WlanFreeMemory(pProfileXml);
pProfileXml = NULL;
}
if (pIfList != NULL) {
WlanFreeMemory(pIfList);
pIfList = NULL;
}
return dwRetVal;
}
Configuration requise
| 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 |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour