WlanGetProfile-Funktion (wlanapi.h)
Die WlanGetProfile-Funktion ruft alle Informationen zu einem angegebenen Drahtlosprofil ab.
Syntax
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
);
Parameter
[in] hClientHandle
Das Sitzungshandle des Clients, das durch einen vorherigen Aufruf der WlanOpenHandle-Funktion abgerufen wurde.
[in] pInterfaceGuid
Die GUID der drahtlosen Schnittstelle.
Eine Liste der GUIDs für drahtlose Schnittstellen auf dem lokalen Computer kann mit der Funktion WlanEnumInterfaces abgerufen werden.
[in] strProfileName
Der Name des Profils. Bei Profilnamen wird die Groß-/Kleinschreibung beachtet. Diese Zeichenfolge muss NULL-endend sein. Die maximale Länge des Profilnamens beträgt 255 Zeichen. Dies bedeutet, dass die maximale Länge dieser Zeichenfolge, einschließlich des NULL-Abschlusszeichens, 256 Zeichen beträgt.
Windows XP mit SP3 und Wlan-API für Windows XP mit SP2: Der Name des Profils wird automatisch von der SSID des Netzwerks abgeleitet. Bei Infrastrukturnetzwerkprofilen ist der Name des Profils die SSID des Netzwerks. Bei Ad-hoc-Netzwerkprofilen ist der Name des Profils die SSID des Ad-hoc-Netzwerks gefolgt von -adhoc.
[in] pReserved
Für die zukünftige Verwendung reserviert. Muss auf NULL festgelegt werden.
[out] pstrProfileXml
Eine Zeichenfolge, die die XML-Darstellung des abgefragten Profils darstellt. Es gibt keine vordefinierte maximale Zeichenfolgenlänge.
[in, out, optional] pdwFlags
Bei der Eingabe ein Zeiger auf den Adressspeicherort, der verwendet wird, um zusätzliche Informationen zur Anforderung bereitzustellen. Wenn dieser Parameter bei der Eingabe NULL ist, werden keine Informationen zu Profilflags zurückgegeben. In der Ausgabe ein Zeiger auf den Adressspeicherort, der zum Empfangen von Profilflags verwendet wird.
Windows XP mit SP3 und Wlan-API für Windows XP mit SP2: Benutzerspezifische Profile werden nicht unterstützt. Legen Sie diesen Parameter auf NULL fest.
Der parameter pdwFlags kann auf einen Adressspeicherort verweisen, der die folgenden Werte enthält:
| Wert | Bedeutung |
|---|---|
|
Bei der Eingabe gibt dieses Flag an, dass der Aufrufer den Nur-Text-Schlüssel aus einem Drahtlosprofil abrufen möchte. Wenn der aufrufende Thread über die erforderlichen Berechtigungen verfügt, gibt die WlanGetProfile-Funktion den Nur-Text-Schlüssel im keyMaterial-Element des Profils zurück, der im Puffer zurückgegeben wird, auf den der pstrProfileXml-Parameter verweist.
Damit der WlanGetProfile-Aufruf den Nur-Text-Schlüssel zurückgibt, müssen die wlan_secure_get_plaintext_key Berechtigungen des WLAN_SECURABLE_OBJECT enumerierten Typs für den aufrufenden Thread festgelegt werden. Die DACL muss außerdem einen ACE enthalten, der WLAN_READ_ACCESS Berechtigung für das Zugriffstoken des aufrufenden Threads erteilt. Standardmäßig sind die Berechtigungen zum Abrufen des Nur-Text-Schlüssels nur für die Mitglieder der Gruppe Administratoren auf einem lokalen Computer zulässig. Wenn dem aufrufenden Thread die erforderlichen Berechtigungen fehlen, gibt die WlanGetProfile-Funktion den verschlüsselten Schlüssel im keyMaterial-Element des Profils zurück, der im Puffer zurückgegeben wird, auf den der pstrProfileXml-Parameter verweist. Es wird kein Fehler zurückgegeben, wenn dem aufrufenden Thread die erforderlichen Berechtigungen fehlen. Windows 7: Dieses bei Eingaben übergebene Flag ist eine Erweiterung für native Drahtlos-APIs, die unter Windows 7 und höher hinzugefügt werden. Der pdwFlags-Parameter ist ein __inout_opt-Parameter unter Windows 7 und höher. |
|
Wenn der WlanGetProfile-Aufruf erfolgreich ist, gibt dieses Flag an, dass dieses Profil durch eine Gruppenrichtlinie erstellt wurde. Ein Gruppenrichtlinienprofil ist schreibgeschützt. Weder der Inhalt noch die Präferenzreihenfolge des Profils können geändert werden. |
|
Bei der Ausgabe, wenn der WlanGetProfile-Aufruf erfolgreich ist, gibt dieses Flag an, dass das Profil ein Benutzerprofil für den bestimmten Benutzer ist, in dessen Kontext sich der aufrufende Thread befindet. Wenn dieses Profil nicht festgelegt ist, handelt es sich um ein Benutzerprofil. |
[out, optional] pdwGrantedAccess
Die Zugriffsmaske des All-User-Profils.
| Wert | Bedeutung |
|---|---|
|
Der Benutzer kann den Inhalt des Profils anzeigen. |
|
Der Benutzer verfügt über Lesezugriff, und der Benutzer kann mithilfe des Profils auch eine Verbindung mit einem Netzwerk herstellen und die Verbindung mit diesem trennen. Wenn ein Benutzer über WLAN_EXECUTE_ACCESS verfügt, verfügt der Benutzer auch über WLAN_READ_ACCESS. |
|
Der Benutzer hat Ausführungszugriff, und der Benutzer kann auch den Inhalt des Profils ändern oder das Profil löschen. Wenn ein Benutzer über WLAN_WRITE_ACCESS verfügt, verfügt der Benutzer auch über WLAN_EXECUTE_ACCESS und WLAN_READ_ACCESS. |
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.
Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Rückgabecodes sein.
| Rückgabecode | Beschreibung |
|---|---|
|
Der Aufrufer verfügt nicht über ausreichende Berechtigungen. Dieser Fehler wird zurückgegeben, wenn der pstrProfileXml-Parameter ein Benutzerprofil angibt, der Aufrufer jedoch keinen Lesezugriff auf das Profil hat. |
|
Ein Handle ist ungültig. Dieser Fehler wird zurückgegeben, wenn das im hClientHandle-Parameter angegebene Handle in der Handletabelle nicht gefunden wurde. |
|
Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn eine der folgenden Bedingungen auftritt:
|
|
Für die Verarbeitung dieses Befehls ist nicht genügend Speicherplatz verfügbar. Dieser Fehler wird zurückgegeben, wenn das System nicht in der Lage war, Arbeitsspeicher für das Profil zuzuweisen. |
|
Das von strProfileName angegebene Profil wurde nicht gefunden. |
|
Verschiedene RPC- und andere Fehlercodes. Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Wenn die WlanGetProfile-Funktion erfolgreich ist, wird das Drahtlosprofil im Puffer zurückgegeben, auf den der pstrProfileXml-Parameter verweist. Der Puffer enthält eine Zeichenfolge, die die XML-Darstellung des abgefragten Profils darstellt. Eine Beschreibung der XML-Darstellung des Drahtlosprofils finden Sie unter WLAN_profile Schema.
Der Aufrufer ist für den Aufruf der WlanFreeMemory-Funktion verantwortlich, um den Speicher freizugeben, der dem Pufferzeiger durch den pstrProfileXml-Parameter zugewiesen ist, wenn der Puffer nicht mehr benötigt wird.
Wenn pstrProfileXml ein Benutzerprofil angibt, muss der WlanGetProfile-Aufrufer über Lesezugriff auf das Profil verfügen. Andernfalls schlägt der WlanGetProfile-Aufruf mit dem Rückgabewert ERROR_ACCESS_DENIED fehl. Die Berechtigungen für ein Benutzerprofil werden eingerichtet, wenn das Profil mithilfe von WlanSetProfile oder WlanSaveTemporaryProfile erstellt oder gespeichert wird.
Windows 7:
Das keyMaterial-Element , das im Profilschema zurückgegeben wird, auf das von pstrProfileXml verwiesen wird, kann als Klartext angefordert werden, wenn die WlanGetProfile-Funktion mit dem WLAN_PROFILE_GET_PLAINTEXT_KEY-Flag aufgerufen wird, das im Wert festgelegt ist, auf den der pdwFlags-Parameter bei der Eingabe verweist.
Bei einem WEP-Schlüssel können beide 5 ASCII-Zeichen oder 10 Hexadezimalzeichen verwendet werden, um den Klartextschlüssel festzulegen, wenn das Profil erstellt oder aktualisiert wird. Ein WEP-Profil wird jedoch mit 10 Hexadezimalzeichen im Schlüssel gespeichert, unabhängig davon, welche ursprüngliche Eingabe zum Erstellen des Profils verwendet wurde. Daher wird in dem profil, das von der WlanGetProfile-Funktion zurückgegeben wird, der Klartext-WEP-Schlüssel immer als 10 Hexadezimalzeichen zurückgegeben.
Damit der WlanGetProfile-Aufruf den Nur-Text-Schlüssel zurückgibt, müssen die wlan_secure_get_plaintext_key Berechtigungen des WLAN_SECURABLE_OBJECT enumerierten Typs für den aufrufenden Thread festgelegt werden. Die DACL muss außerdem einen ACE enthalten, der WLAN_READ_ACCESS Berechtigung für das Zugriffstoken des aufrufenden Threads erteilt. Standardmäßig sind die Berechtigungen zum Abrufen des Nur-Text-Schlüssels nur für die Mitglieder der Gruppe Administratoren auf einem lokalen Computer zulässig.
Wenn dem aufrufenden Thread die erforderlichen Berechtigungen fehlen, gibt die WlanGetProfile-Funktion den verschlüsselten Schlüssel im keyMaterial-Element des Profils zurück, der im Puffer zurückgegeben wird, auf den der pstrProfileXml-Parameter verweist. Es wird kein Fehler zurückgegeben, wenn dem aufrufenden Thread die erforderlichen Berechtigungen fehlen.
Standardmäßig wird das keyMaterial-Element , das im Profil zurückgegeben wird, auf das von pstrProfileXml verwiesen wird, verschlüsselt. Wenn Ihr Prozess im Kontext des LocalSystem-Kontos auf demselben Computer ausgeführt wird, können Sie die Verschlüsselung von Schlüsselmaterial aufheben, indem Sie die CryptUnprotectData-Funktion aufrufen.
Windows Server 2008 und Windows Vista: Das keyMaterial-Element , das im Profilschema zurückgegeben wird, auf das von pstrProfileXml verwiesen wird, wird immer verschlüsselt. Wenn Ihr Prozess im Kontext des LocalSystem-Kontos ausgeführt wird, können Sie die Verschlüsselung von Schlüsselmaterial aufheben, indem Sie die CryptUnprotectData-Funktion aufrufen.
Windows XP mit SP3 und Wlan-API für Windows XP mit SP2: Das Schlüsselmaterial wird nie verschlüsselt.
Beispiele
Das folgende Beispiel listet die WLAN-Schnittstellen auf dem lokalen Computer auf, ruft Informationen für ein bestimmtes Drahtlosprofil auf jeder WLAN-Schnittstelle ab und gibt die abgerufenen Werte aus. Die Zeichenfolge, die die XML-Darstellung des abgefragten Profils darstellt, wird ebenfalls gedruckt.
#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;
}
Anforderungen
| Unterstützte Mindestversion (Client) | Windows Vista, Windows XP mit SP3 [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | wlanapi.h (wlanapi.h einschließen) |
| Bibliothek | Wlanapi.lib |
| DLL | Wlanapi.dll |
| Verteilbare Komponente | Wlan-API für Windows XP mit SP2 |