Fungsi WlanGetProfile (wlanapi.h)
Fungsi WlanGetProfile mengambil semua informasi tentang profil nirkabel tertentu.
Sintaks
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
Handel sesi klien, diperoleh dari panggilan sebelumnya ke fungsi WlanOpenHandle .
[in] pInterfaceGuid
GUID antarmuka nirkabel.
Daftar GUID untuk antarmuka nirkabel di komputer lokal dapat diambil menggunakan fungsi WlanEnumInterfaces .
[in] strProfileName
Nama profil. Nama profil peka huruf besar/kecil. String ini harus dihentikan NULL. Panjang maksimum nama profil adalah 255 karakter. Ini berarti bahwa panjang maksimum string ini, termasuk terminator NULL, adalah 256 karakter.
Windows XP dengan SP3 dan Wireless LAN API untuk Windows XP dengan SP2: Nama profil berasal secara otomatis dari SSID jaringan. Untuk profil jaringan infrastruktur, nama profil adalah SSID jaringan. Untuk profil jaringan ad hoc, nama profil adalah SSID jaringan ad hoc diikuti oleh -adhoc.
[in] pReserved
Disiapkan untuk penggunaan masa mendatang. Harus diatur ke NULL.
[out] pstrProfileXml
String yang merupakan representasi XML dari profil yang dikueri. Tidak ada panjang string maksimum yang telah ditentukan sebelumnya.
[in, out, optional] pdwFlags
Pada input, pointer ke lokasi alamat yang digunakan untuk memberikan informasi tambahan tentang permintaan tersebut. Jika parameter ini NULL pada input, maka tidak ada informasi tentang bendera profil yang akan dikembalikan. Pada output, pointer ke lokasi alamat yang digunakan untuk menerima bendera profil.
Windows XP dengan SP3 dan Wireless LAN API untuk Windows XP dengan SP2: Profil per pengguna tidak didukung. Atur parameter ini ke NULL.
Parameter pdwFlags dapat menunjuk ke lokasi alamat yang berisi nilai berikut:
| Nilai | Makna |
|---|---|
|
Pada input, bendera ini menunjukkan bahwa penelepon ingin mengambil kunci teks biasa dari profil nirkabel. Jika utas panggilan memiliki izin yang diperlukan, fungsi WlanGetProfile mengembalikan kunci teks biasa di elemen keyMaterial profil yang dikembalikan dalam buffer yang ditunjukkan oleh parameter pstrProfileXml .
Agar panggilan WlanGetProfile mengembalikan kunci teks biasa, izin wlan_secure_get_plaintext_key dari jenis enumerasi WLAN_SECURABLE_OBJECT harus diatur pada utas panggilan. DACL juga harus berisi ACE yang memberikan izin WLAN_READ_ACCESS ke token akses utas panggilan. Secara default, izin untuk mengambil kunci teks biasa hanya diizinkan untuk anggota grup Administrator pada komputer lokal. Jika utas panggilan tidak memiliki izin yang diperlukan, fungsi WlanGetProfile mengembalikan kunci terenkripsi dalam elemen keyMaterial profil yang dikembalikan dalam buffer yang ditunjukkan oleh parameter pstrProfileXml . Tidak ada kesalahan yang dikembalikan jika utas panggilan tidak memiliki izin yang diperlukan. Windows 7: Bendera yang diteruskan pada input ini adalah ekstensi untuk API nirkabel asli yang ditambahkan pada Windows 7 dan yang lebih baru. Parameter pdwFlags adalah parameter __inout_opt pada Windows 7 dan yang lebih baru. |
|
Pada output ketika panggilan WlanGetProfile berhasil, bendera ini menunjukkan bahwa profil ini dibuat oleh kebijakan grup. Profil kebijakan grup bersifat baca-saja. Konten maupun urutan preferensi profil tidak dapat diubah. |
|
Pada output ketika panggilan WlanGetProfile berhasil, bendera ini menunjukkan bahwa profil adalah profil pengguna untuk pengguna tertentu dalam konteks yang alur panggilannya berada. Jika tidak diatur, profil ini adalah profil semua pengguna. |
[out, optional] pdwGrantedAccess
Masker akses profil semua pengguna.
| Nilai | Makna |
|---|---|
|
Pengguna dapat melihat konten profil. |
|
Pengguna memiliki akses baca, dan pengguna juga dapat terhubung dan memutuskan sambungan dari jaringan menggunakan profil. Jika pengguna memiliki WLAN_EXECUTE_ACCESS, pengguna juga memiliki WLAN_READ_ACCESS. |
|
Pengguna telah menjalankan akses dan pengguna juga dapat memodifikasi konten profil atau menghapus profil. Jika pengguna memiliki WLAN_WRITE_ACCESS, pengguna juga memiliki WLAN_EXECUTE_ACCESS dan WLAN_READ_ACCESS. |
Nilai kembali
Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.
Jika fungsi gagal, nilai yang dikembalikan mungkin merupakan salah satu kode pengembalian berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
Pemanggil tidak memiliki izin yang memadai. Kesalahan ini dikembalikan jika parameter pstrProfileXml menentukan profil semua pengguna, tetapi pemanggil tidak memiliki akses baca di profil. |
|
Handel tidak valid. Kesalahan ini dikembalikan jika handel yang ditentukan dalam parameter hClientHandle tidak ditemukan dalam tabel handel. |
|
Parameter salah. Kesalahan ini dikembalikan jika salah satu kondisi berikut terjadi:
|
|
Penyimpanan tidak cukup tersedia untuk memproses perintah ini. Kesalahan ini dikembalikan jika sistem tidak dapat mengalokasikan memori untuk profil. |
|
Profil yang ditentukan oleh strProfileName tidak ditemukan. |
|
Berbagai RPC dan kode kesalahan lainnya. Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan. |
Keterangan
Jika fungsi WlanGetProfile berhasil, profil nirkabel dikembalikan dalam buffer yang diacu oleh parameter pstrProfileXml . Buffer berisi string yang merupakan representasi XML dari profil yang dikueri. Untuk deskripsi representasi XML profil nirkabel, lihat Skema WLAN_profile.
Pemanggil bertanggung jawab untuk memanggil fungsi WlanFreeMemory untuk membebaskan memori yang dialokasikan untuk penunjuk buffer oleh parameter pstrProfileXml ketika buffer tidak lagi diperlukan.
Jika pstrProfileXml menentukan profil semua pengguna, pemanggil WlanGetProfile harus memiliki akses baca di profil. Jika tidak, panggilan WlanGetProfile akan gagal dengan nilai pengembalian ERROR_ACCESS_DENIED. Izin pada profil semua pengguna dibuat saat profil dibuat atau disimpan menggunakan WlanSetProfile atau WlanSaveTemporaryProfile.
Windows 7:
Elemen keyMaterial yang dikembalikan dalam skema profil yang diarahkan oleh pstrProfileXml dapat diminta sebagai teks biasa jika fungsi WlanGetProfile dipanggil dengan bendera WLAN_PROFILE_GET_PLAINTEXT_KEY yang ditetapkan dalam nilai yang ditujukkan oleh parameter pdwFlags pada input.
Untuk kunci WEP, 5 karakter ASCII atau 10 karakter heksadesimal dapat digunakan untuk mengatur kunci teks biasa saat profil dibuat atau diperbarui. Namun, profil WEP akan disimpan dengan 10 karakter heksadesimal dalam kunci apa pun input asli yang digunakan untuk membuat profil. Jadi dalam profil yang dikembalikan oleh fungsi WlanGetProfile , kunci WEP teks biasa selalu dikembalikan sebagai 10 karakter heksadesimal.
Agar panggilan WlanGetProfile mengembalikan kunci teks biasa, izin wlan_secure_get_plaintext_key dari jenis enumerasi WLAN_SECURABLE_OBJECT harus diatur pada utas panggilan. DACL juga harus berisi ACE yang memberikan izin WLAN_READ_ACCESS ke token akses utas panggilan. Secara default, izin untuk mengambil kunci teks biasa hanya diizinkan untuk anggota grup Administrator pada komputer lokal.
Jika utas panggilan tidak memiliki izin yang diperlukan, fungsi WlanGetProfile mengembalikan kunci terenkripsi dalam elemen keyMaterial profil yang dikembalikan dalam buffer yang ditunjukkan oleh parameter pstrProfileXml . Tidak ada kesalahan yang dikembalikan jika utas panggilan tidak memiliki izin yang diperlukan.
Secara default, elemen keyMaterial yang dikembalikan di profil yang ditujukkan oleh pstrProfileXml dienkripsi. Jika proses Anda berjalan dalam konteks akun LocalSystem di komputer yang sama, maka Anda dapat membatalkan enkripsi materi kunci dengan memanggil fungsi CryptUnprotectData .
Windows Server 2008 dan Windows Vista: Elemen keyMaterial yang dikembalikan dalam skema profil yang ditujukan oleh pstrProfileXml selalu dienkripsi. Jika proses Anda berjalan dalam konteks akun LocalSystem, maka Anda dapat membuka kripto materi kunci dengan memanggil fungsi CryptUnprotectData .
Windows XP dengan SP3 dan Wireless LAN API untuk Windows XP dengan SP2: Materi kunci tidak pernah dienkripsi.
Contoh
Contoh berikut menghitung antarmuka LAN nirkabel di komputer lokal, mengambil informasi untuk profil nirkabel tertentu pada setiap antarmuka LAN nirkabel, dan mencetak nilai yang diambil. String yang merupakan representasi XML dari profil yang dikueri juga dicetak.
#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;
}
Persyaratan
| Klien minimum yang didukung | Windows Vista, Windows XP dengan SP3 [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | wlanapi.h (termasuk Wlanapi.h) |
| Pustaka | Wlanapi.lib |
| DLL | Wlanapi.dll |
| Redistribusi | API LAN Nirkabel untuk Windows XP dengan SP2 |