WlanGetProfile 関数 (wlanapi.h)
WlanGetProfile 関数は、指定されたワイヤレス プロファイルに関するすべての情報を取得します。
構文
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
);
パラメーター
[in] hClientHandle
WlanOpenHandle 関数の以前の呼び出しによって取得されたクライアントのセッション ハンドル。
[in] pInterfaceGuid
ワイヤレス インターフェイスの GUID。
ローカル コンピューター上のワイヤレス インターフェイスの GUID の一覧は、 WlanEnumInterfaces 関数を使用して取得できます。
[in] strProfileName
プロファイルの名前。 プロファイル名では大文字と小文字が区別されます。 この文字列は NULL で終わる必要があります。 プロファイル名の最大長は 255 文字です。 つまり、NULL 終端記号を含め、この文字列の最大長は 256 文字です。
WINDOWS XP SP3 とワイヤレス LAN API for Windows XP SP2: プロファイルの名前は、ネットワークの SSID から自動的に派生します。 インフラストラクチャ ネットワーク プロファイルの場合、プロファイルの名前はネットワークの SSID です。 アドホック ネットワーク プロファイルの場合、プロファイルの名前はアドホック ネットワークの SSID の後に が -adhoc続きます。
[in] pReserved
将来利用するために予約されています。 NULL に設定する必要があります。
[out] pstrProfileXml
クエリ対象プロファイルの XML 表現である文字列。 定義済みの最大文字列長はありません。
[in, out, optional] pdwFlags
入力時に、要求に関する追加情報を提供するために使用されるアドレスの場所へのポインター。 入力時にこのパラメーターが NULL の場合、プロファイル フラグに関する情報は返されません。 出力時に、プロファイル フラグの受信に使用されるアドレスの場所へのポインター。
WINDOWS XP SP3 とワイヤレス LAN API for Windows XP SP2: ユーザーごとのプロファイルはサポートされていません。 このパラメーターを NULL に設定 します。
pdwFlags パラメーターは、次の値を含むアドレスの場所を指すことができます。
| 値 | 意味 |
|---|---|
|
入力時に、このフラグは、呼び出し元がワイヤレス プロファイルからプレーン テキスト キーを取得することを示します。 呼び出し元のスレッドに必要なアクセス許可がある場合、WlanGetProfile 関数は、pstrProfileXml パラメーターによって指されるバッファーで返されるプロファイルの keyMaterial 要素のプレーン テキスト キーを返します。
WlanGetProfile 呼び出しでプレーン テキスト キーを返すには、WLAN_SECURABLE_OBJECT列挙型からのwlan_secure_get_plaintext_keyアクセス許可を呼び出し元のスレッドに設定する必要があります。 DACL には、呼び出し元スレッド の アクセス トークンWLAN_READ_ACCESSアクセス許可を付与する ACE も含まれている必要があります。 既定では、プレーン テキスト キーを取得するためのアクセス許可は、ローカル コンピューター上の Administrators グループのメンバーにのみ許可されます。 呼び出し元のスレッドに必要なアクセス許可がない場合、WlanGetProfile 関数は、pstrProfileXml パラメーターによって指されるバッファーで返されるプロファイルの keyMaterial 要素で暗号化されたキーを返します。 呼び出し元のスレッドに必要なアクセス許可がない場合、エラーは返されません。 Windows 7: 入力で渡されるこのフラグは、Windows 7 以降で追加されたネイティブ ワイヤレス API の拡張機能です。 pdwFlags パラメーターは、Windows 7 以降の__inout_opt パラメーターです。 |
|
WlanGetProfile 呼び出しが成功した場合の出力では、このフラグは、このプロファイルがグループ ポリシーによって作成されたことを示します。 グループ ポリシー プロファイルは読み取り専用です。 プロファイルのコンテンツとユーザー設定の順序はどちらも変更できません。 |
|
WlanGetProfile 呼び出しが成功した場合の出力では、このフラグは、プロファイルが呼び出し元スレッドが存在するコンテキストの特定のユーザーのユーザー プロファイルであることを示します。 設定されていない場合、このプロファイルは全ユーザー プロファイルです。 |
[out, optional] pdwGrantedAccess
すべてのユーザー プロファイルのアクセス マスク。
| 値 | 意味 |
|---|---|
|
ユーザーはプロファイルの内容を表示できます。 |
|
ユーザーは読み取りアクセス権を持ち、ユーザーはプロファイルを使用してネットワークに接続したり、ネットワークから切断したりすることもできます。 ユーザーにWLAN_EXECUTE_ACCESSがある場合は、ユーザーにもWLAN_READ_ACCESSがあります。 |
|
ユーザーは実行アクセス権を持ち、ユーザーはプロファイルの内容を変更したり、プロファイルを削除したりすることもできます。 ユーザーにWLAN_WRITE_ACCESSがある場合、ユーザーにはWLAN_EXECUTE_ACCESSとWLAN_READ_ACCESSもあります。 |
戻り値
関数が成功した場合、戻り値は ERROR_SUCCESS です。
関数が失敗した場合、戻り値は次のいずれかの戻りコードになる可能性があります。
| リターン コード | 説明 |
|---|---|
|
呼び出し元に十分なアクセス許可がありません。 pstrProfileXml パラメーターがすべてのユーザー プロファイルを指定しているが、呼び出し元がプロファイルに対する読み取りアクセス権を持っていない場合、このエラーが返されます。 |
|
ハンドルが無効です。 このエラーは、 hClientHandle パラメーターで指定されたハンドルがハンドル テーブルで見つからなかった場合に返されます。 |
|
パラメーターが正しくありません。 このエラーは、次のいずれかの条件が発生した場合に返されます。
|
|
このコマンドを処理するのに十分なストレージがありません。 このエラーは、システムがプロファイルのメモリを割り当てられなかった場合に返されます。 |
|
strProfileName で指定されたプロファイルが見つかりませんでした。 |
|
さまざまな RPC とその他のエラー コード。 FormatMessage を使用して、返されたエラーのメッセージ文字列を取得します。 |
注釈
WlanGetProfile 関数が成功した場合、ワイヤレス プロファイルは pstrProfileXml パラメーターが指すバッファーで返されます。 バッファーには、クエリされたプロファイルの XML 表現である文字列が含まれています。 ワイヤレス プロファイルの XML 表現の説明については、「 WLAN_profile スキーマ」を参照してください。
呼び出し元は WlanFreeMemory 関数を呼び出して、バッファーが不要になったときに pstrProfileXml パラメーターによってバッファー ポインターに割り当てられたメモリを解放します。
pstrProfileXml ですべてのユーザー プロファイルが指定されている場合、WlanGetProfile 呼び出し元はプロファイルに対する読み取りアクセス権を持っている必要があります。 それ以外の場合、 WlanGetProfile 呼び出しは ERROR_ACCESS_DENIEDの戻り値で失敗します。 すべてのユーザー プロファイルに対するアクセス許可は、 WlanSetProfile または WlanSaveTemporaryProfile を使用してプロファイルが作成または保存されるときに確立されます。
Windows 7:
入力時に pdwFlags パラメーターが指す値に WLAN_PROFILE_GET_PLAINTEXT_KEY フラグを設定して WlanGetProfile 関数が呼び出された場合、pstrProfileXml が指すプロファイル スキーマで返される keyMaterial 要素はプレーンテキストとして要求される場合があります。
WEP キーの場合は、5 文字の ASCII 文字または 10 個の 16 進文字の両方を使用して、プロファイルの作成時または更新時にプレーンテキスト キーを設定できます。 ただし、WEP プロファイルは、プロファイルの作成に使用された元の入力に関係なく、キーに 10 個の 16 進文字で保存されます。 そのため、 WlanGetProfile 関数によって返されるプロファイルでは、プレーンテキスト WEP キーは常に 10 個の 16 進文字として返されます。
WlanGetProfile 呼び出しでプレーン テキスト キーを返すには、WLAN_SECURABLE_OBJECT列挙型からのwlan_secure_get_plaintext_keyアクセス許可を呼び出し元のスレッドに設定する必要があります。 DACL には、呼び出し元スレッド の アクセス トークンWLAN_READ_ACCESSアクセス許可を付与する ACE も含まれている必要があります。 既定では、プレーン テキスト キーを取得するためのアクセス許可は、ローカル コンピューター上の Administrators グループのメンバーにのみ許可されます。
呼び出し元のスレッドに必要なアクセス許可がない場合、WlanGetProfile 関数は、pstrProfileXml パラメーターによって指されるバッファーで返されるプロファイルの keyMaterial 要素で暗号化されたキーを返します。 呼び出し元のスレッドに必要なアクセス許可がない場合、エラーは返されません。
既定では、pstrProfileXml が指すプロファイルで返される keyMaterial 要素は暗号化されます。 プロセスが同じコンピューター上の LocalSystem アカウントのコンテキストで実行されている場合は、 CryptUnprotectData 関数を呼び出すことでキーマテリアルを暗号化解除できます。
Windows Server 2008 と Windows Vista: pstrProfileXml が指すプロファイル スキーマで返される keyMaterial 要素は、常に暗号化されます。 プロセスが LocalSystem アカウントのコンテキストで実行されている場合は、 CryptUnprotectData 関数を呼び出すことでキーマテリアルを暗号化解除できます。
WINDOWS XP SP3 とワイヤレス LAN API for Windows XP SP2: キーマテリアルは暗号化されません。
例
次の例では、ローカル コンピューター上のワイヤレス LAN インターフェイスを列挙し、各ワイヤレス LAN インターフェイス上の特定のワイヤレス プロファイルの情報を取得し、取得した値を出力します。 クエリされたプロファイルの XML 表現である文字列も出力されます。
#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;
}
要件
| サポートされている最小のクライアント | Windows Vista、SP3 を使用した Windows XP [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | wlanapi.h (Wlanapi.h を含む) |
| Library | Wlanapi.lib |
| [DLL] | Wlanapi.dll |
| 再頒布可能パッケージ | Sp2 を使用した Windows XP 用ワイヤレス LAN API |