WlanSetProfile 関数 (wlanapi.h)
WlanSetProfile 関数は、特定のプロファイルの内容を設定します。
構文
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
);
パラメーター
[in] hClientHandle
WlanOpenHandle 関数の以前の呼び出しによって取得されたクライアントのセッション ハンドル。
[in] pInterfaceGuid
インターフェイスの GUID。
[in] dwFlags
プロファイルに設定するフラグ。
SP3 の Windows XP と、SP2 を使用した Windows XP 用のワイヤレス LAN API: dwFlags は 0 である必要があります。 ユーザーごとのプロファイルはサポートされていません。
| 値 | 意味 |
|---|---|
|
プロファイルは、すべてのユーザー プロファイルです。 |
|
プロファイルはグループ ポリシー プロファイルです。 |
|
プロファイルはユーザーごとのプロファイルです。 |
[in] strProfileXml
プロファイルの XML 表現を格納します。 WLANProfile 要素はルート プロファイル要素です。 サンプル プロファイルを表示するには、「 ワイヤレス プロファイルのサンプル」を参照してください。 定義済みの最大文字列長はありません。
SP3 を使用した Windows XP と、SP2 を使用した Windows XP 用のワイヤレス LAN API: 指定されたプロファイルは、「 ワイヤレス プロファイルの互換性」で説明されている互換性基準を満たしている必要があります。
[in, optional] strAllUserProfileSecurity
すべてのユーザー プロファイルのセキュリティ記述子文字列を設定します。 プロファイルのアクセス許可の詳細については、「解説」セクションを参照してください。
dwFlags が WLAN_PROFILE_USER に設定されている場合、このパラメーターは無視されます。
新しい全ユーザー プロファイルに対してこのパラメーターが NULL に設定されている場合は、wlan_secure_add_new_all_user_profiles オブジェクトに関連付けられているセキュリティ記述子が使用されます。 セキュリティ記述子が WlanSetSecuritySettings 呼び出しによって変更されていない場合、すべてのユーザーは新しいすべてのユーザー プロファイルに対する既定のアクセス許可を持ちます。 WlanGetSecuritySettings を呼び出して、wlan_secure_add_new_all_user_profiles オブジェクトに関連付けられている既定のアクセス許可を取得します。
このパラメーターが既存の全ユーザー プロファイルに 対して NULL に設定されている場合、プロファイルのアクセス許可は変更されません。
このパラメーターがすべてのユーザー プロファイルに 対して NULL でない場合は、セキュリティ記述子オブジェクトが作成され、文字列として解析された後に、プロファイルに関連付けられているセキュリティ記述子文字列が作成または変更されます。
SP3 を使用した Windows XP と、SP2 を使用した Windows XP 用のワイヤレス LAN API: このパラメーターは NULL である必要があります。
[in] bOverwrite
このプロファイルが既存のプロファイルを上書きするかどうかを指定します。 このパラメーターが FALSE で、プロファイルが既に存在する場合、既存のプロファイルは上書きされず、エラーが返されます。
[in] pReserved
将来利用するために予約されています。 NULL に設定する必要があります。
[out] pdwReasonCode
プロファイルが無効な理由を示す WLAN_REASON_CODE 値。
戻り値
関数が成功した場合、戻り値は ERROR_SUCCESS です。
関数が失敗した場合、戻り値は次のいずれかのリターン コードになります。
| リターン コード | 説明 |
|---|---|
|
呼び出し元には、プロファイルを設定するための十分なアクセス許可がありません。
dwFlags を 0 に設定して呼び出した場合 、つまり、すべてのユーザー プロファイルを設定する場合、 WlanSetProfile は、wlan_secure_add_new_all_user_profiles オブジェクトと共に格納されている随意アクセス制御リスト (DACL) を取得します。 dwFlags を WLAN_PROFILE_USER に設定して呼び出した場合 、つまりユーザーごとのプロファイルを設定する場合、 WlanSetProfile は、wlan_secure_add_new_per_user_profiles オブジェクトと共に格納されている随意アクセス制御リスト (DACL) を取得します。 どちらの場合も、DACL に、呼び出し元スレッドのアクセス トークンに対するアクセス許可WLAN_WRITE_ACCESS付与するアクセス制御エントリ (ACE) が含まれていない場合、 WlanSetProfile は ERROR_ACCESS_DENIEDを返します。 |
|
strProfileXml は、既に存在するネットワークを指定します。 通常、この戻り値は、bOverwrite が FALSE の場合に使用されます。ただし、bOverwrite が TRUE で、dwFlags で既存のプロファイルで使用されているプロファイルの種類とは異なるプロファイルの種類が指定されている場合、既存のプロファイルは上書きされず、ERROR_ALREADY_EXISTSが返されます。 |
|
strProfileXml で指定されたプロファイルが無効です。 この値が返された場合、 pdwReasonCode はプロファイルが無効な理由を指定します。 |
|
次のいずれかの条件が発生しました。
<ConfigBlob>00</ConfigBlob> します。
|
|
インターフェイスは、プロファイルで指定された 1 つ以上の機能をサポートしていません。 たとえば、NIC が WPA のみをサポートする場合にプロファイルで WPA2 の使用が指定されている場合、このエラー コードが返されます。 また、NIC が FIPS モードをサポートしていないときにプロファイルで FIPS モードの使用が指定されている場合は、このエラー コードが返されます。 |
|
さまざまなエラー コード。 |
注釈
WlanSetProfile 関数を使用すると、新しいワイヤレス LAN プロファイルを追加したり、既存のワイヤレス LAN プロファイルを置き換えたりできます。
新しいプロファイルは、グループ ポリシー プロファイルの後の一覧の上部に追加されます。 既存のプロファイルが上書きされた場合、リスト内のプロファイルの位置は変更されません。SP3 を使用した Windows XP と、SP2 を使用した Windows XP 用のワイヤレス LAN API:
アドホック プロファイルは、プロファイル一覧のインフラストラクチャ プロファイルの後に表示されます。 新しいアドホック プロファイルを作成すると、グループ ポリシーとインフラストラクチャ プロファイルの後のアドホック リストの先頭に配置されます。
802.1X ゲスト プロファイル、ワイヤレス プロビジョニング サービス (WPS) プロファイル、および Wi-Fi Protected Access-None (WPA-None) 認証を使用したプロファイルはサポートされていません。 つまり、このようなプロファイルは、Native Wifi 関数を使用して作成、削除、列挙、またはアクセスすることはできません。 優先プロファイル リストに既に存在するプロファイルはすべてリストに残り、他のプロファイルの位置が変更されない限り、リスト内の他のプロファイルに対する相対的な位置は固定されます。
プレーンテキスト キーを含むプロファイル (つまり、保護された要素が存在し、FALSE に設定されたプロファイル) で WlanSetProfile を呼び出すことができます。 プロファイルがプロファイル ストアに保存される前に、キー マテリアルは自動的に暗号化されます。 その後、 WlanGetProfile を呼び出してプロファイル ストアからプロファイルを取得すると、暗号化されたキー マテリアルが返されます。SP3 を使用した Windows XP と、SP2 を使用した Windows XP 用のワイヤレス LAN API: キー マテリアルは暗号化されません。
すべてのユーザー プロファイルには、読み取り、書き込み、実行の 3 つのアクセス許可が関連付けられています。 ユーザーが読み取りアクセス権を持っている場合、ユーザーはプロファイルのアクセス許可を表示できます。 ユーザーが実行アクセス権を持っている場合、ユーザーは読み取りアクセス権を持ち、ユーザーはプロファイルを使用してネットワークに接続して切断することもできます。 ユーザーが書き込みアクセス権を持っている場合、ユーザーは実行アクセス権を持ち、ユーザーはプロファイルに関連付けられているアクセス許可を変更および削除することもできます。
次に、セキュリティ記述子オブジェクトを作成し、それを文字列として解析する手順について説明します。
- InitializeSecurityDescriptor を呼び出して、メモリ内にセキュリティ記述子を作成します。
- SetSecurityDescriptorOwner を呼び出します。
- InitializeAcl を呼び出して、メモリ内に随意アクセス制御リスト (DACL) を作成します。
- AddAccessAllowedAce または AddAccessDeniedAce を呼び出して、DACL にアクセス制御エントリ (ACE) を追加します。 必要に応じて、 AccessMask パラメーターを次のいずれかに設定します。
- WLAN_READ_ACCESS
- WLAN_EXECUTE_ACCESS
- WLAN_WRITE_ACCESS
- SetSecurityDescriptorDacl を呼び出して、DACL をセキュリティ記述子に追加します。
- 記述子を文字列に変換するには、 ConvertSecurityDescriptorToStringSecurityDescriptor を呼び出します。
Native Wifi AutoConfig サービスで使用されるすべてのワイヤレス LAN プロファイルについて、Windows ではカスタム ユーザー データの概念が維持されます。 このカスタム ユーザー データは、最初は存在しないが、 WlanSetProfileCustomUserData 関数を呼び出すことによって設定できます。 カスタム ユーザー データは 、WlanSetProfile 関数を呼び出すことによってプロファイルが変更されるたびに空にリセットされます。 カスタム ユーザー データが設定されたら、 WlanGetProfileCustomUserData 関数を使用してこのデータにアクセスできます。
すべてのワイヤレス LAN 機能では、プロファイル操作を実行するときに、ワイヤレス インターフェイスのインターフェイス GUID が必要です。 ワイヤレス インターフェイスが削除されると、その状態はワイヤレス LAN サービス (WLANSVC) からクリアされ、プロファイル操作は実行できません。
wlanSetProfile 関数は、pInterfaceGuid パラメーターで指定されたワイヤレス インターフェイス (削除された USB ワイヤレス アダプターなど) がシステムから削除された場合、ERROR_INVALID_PARAMETERで失敗する可能性があります。
netsh wlan add profile コマンドは、コマンド ラインでも同様の機能を提供します。 詳細については、「 ワイヤレス ローカル エリア ネットワーク (wlan) の Netsh コマンド」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista、WINDOWS XP と SP3 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | wlanapi.h (Wlanapi.h を含む) |
| Library | Wlanapi.lib |
| [DLL] | Wlanapi.dll |
| 再頒布可能パッケージ | Sp2 を使用した Windows XP 用ワイヤレス LAN API |