WlanHostedNetworkQuerySecondaryKey 関数 (wlanapi.h)

[アーティクル]
03/15/2023

WlanHostedNetworkQuerySecondaryKey 関数は、ワイヤレスホステッドネットワークで使用するように構成されているセカンダリセキュリティキーに対してクエリを実行します。

構文

DWORD WlanHostedNetworkQuerySecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [out]           PDWORD                      pdwKeyLength,
  [out]           PUCHAR                      *ppucKeyData,
  [out]           PBOOL                       pbIsPassPhrase,
  [out]           PBOOL                       pbPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

パラメーター

[in] hClientHandle

WlanOpenHandle 関数の以前の呼び出しによって返されるクライアントのセッションハンドル。

[out] pdwKeyLength

WlanHostedNetworkQuerySecondaryKey 関数の呼び出しが成功した場合に、ppucKeyData パラメーターが指すキーデータ配列内の有効なデータバイト数を指定する値へのポインター。

キーがパスフレーズの場合、このキー長には終端の '\0' が含まれます。

[out] ppucKeyData

WlanHostedNetworkQuerySecondaryKey 関数の呼び出しが成功した場合に、セカンダリセキュリティキーデータで返されるバッファーへのポインターを受け取る値へのポインター。

[out] pbIsPassPhrase

ppucKeyData パラメーターが指すキーデータ配列がパスフレーズ形式であるかどうかを示すブール値へのポインター。

このパラメーターが TRUE の場合、キーデータ配列はパスフレーズ形式になります。このパラメーターが FALSE の場合、キーデータ配列はパスフレーズ形式ではありません。

[out] pbPersistent

ppucKeyData パラメーターが指すキーデータ配列を後で格納して再利用するか、または 1 回限りの使用のみを目的とするかどうかを示すブール値へのポインター。

このパラメーターが TRUE の場合、キーデータ配列は後で格納および再利用されます。このパラメーターが FALSE の場合、キーデータ配列は 1 回限り使用されます。

[out, optional] pFailReason

WlanHostedNetworkSetSecondaryKey 関数の呼び出しが失敗した場合に、エラーの理由を受け取る値への省略可能なポインター。エラーの原因として考えられる値は、Wlanapi.h ヘッダーファイルで定義されているWLAN_HOSTED_NETWORK_REASON列挙型です。

pvReserved

将来利用するために予約されています。このパラメーターは NULL である必要があります。

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS です。

関数が失敗した場合、戻り値は次のいずれかの戻りコードになる可能性があります。

リターンコード	説明
ERROR_INVALID_HANDLE	ハンドルが無効です。このエラーは、 hClientHandle パラメーターで指定されたハンドルがハンドルテーブルで見つからなかった場合に返されます。
ERROR_INVALID_PARAMETER	パラメーターが正しくありません。このエラーは、次のいずれかの条件が発生した場合に返されます。 hClientHandle は NULL です。 pdwKeyLength は NULL です。 ppucKeyData が NULL または無効です。 pbIsPassPhrase が NULL または無効です。 pbPersistent が NULL です。 pvReserved が NULL ではありません。
ERROR_INVALID_STATE	リソースが、要求された操作を実行するための正しい状態ではありません。これは、ワイヤレスホストネットワークがシャットダウン中であった場合に発生する可能性があります。
ERROR_OUTOFMEMORY	この操作を実行するには、使用できる領域が十分ではありません。
ERROR_SERVICE_NOT_ACTIVE	サービスは開始されていません。このエラーは、WLAN AutoConfig サービスが実行されていない場合に返されます。
その他	さまざまな RPC とその他のエラーコード。 FormatMessage を使用して、返されたエラーのメッセージ文字列を取得します。

解説

WlanHostedNetworkQuerySecondaryKey 関数は、ワイヤレス LAN サービスがインストールされた Windows 7 および Windows Server 2008 R2 のワイヤレスホスト型ネットワークをサポートするために追加されたネイティブワイヤレス API の拡張機能です。

クライアントアプリケーションは WlanHostedNetworkQuerySecondaryKey 関数を呼び出して、ワイヤレスホステッドネットワークで使用されるセカンダリセキュリティキーに対してクエリを実行します。この関数は、キーデータ、キーの長さ、パスフレーズであるかどうか、永続的であるか 1 回限りの使用であるかを含むキー情報を返します。この機能は、ワイヤレスホステッドネットワークの状態またはプロパティを変更しません。

pbIsPassPhrase パラメーターが指す値が TRUE の場合、セカンダリセキュリティキーはパスフレーズです。 pbIsPassPhrase パラメーターが指す値が FALSE の場合、セカンダリセキュリティキーはバイナリキーです。

ppucKeyData パラメーターによって指されるバッファーで返されるセカンダリセキュリティキーは、WPA2-Personal 認証で使用され、次のいずれかの形式になります。

8 ~ 63 文字の ASCII 文字の配列で構成されるキーパスフレーズ。 pdwKeyLength パラメーターが指す値には、パスフレーズに終端の '\0' が含まれています。 pdwKeyLength パラメーターが指す値は、9 から 64 の範囲にする必要があります。
32 バイトのバイナリキーデータで構成されるバイナリキー。 pdwKeyLength パラメーターによって指される値は、バイナリキーの場合は 32 である必要があります。

pbPersistent パラメーターが指す値が TRUE の場合、セカンダリセキュリティキーは永続的です。永続的な場合、Hosted Network が既に開始されている場合はセカンダリセキュリティキーがすぐに使用され、今後 Hosted Network が開始されるたびに再利用されます。

セカンダリセキュリティキーが永続的として指定されていない場合は、Hosted Network が既に開始されている場合、またはホストされたネットワークが次回開始されたときにのみ、セカンダリセキュリティキーがすぐに使用されます。ホストされたネットワークが停止すると、このセカンダリセキュリティキーは再び使用されなくなり、システムから削除されます。

現在構成されているセカンダリセキュリティキーがない場合、 pdwKeyLength パラメーターが指す戻り値は 0 になり、 ppucKeyData パラメーターで返される値は NULL になります。このような場合、 pbIsPassPhrase パラメーターと pbPersistent パラメーターで返される値は意味がありません。

WlanHostedNetworkQuerySecondaryKey 関数が成功した場合、返される ppucKeyData パラメーターのバッファーに使用されるメモリは、WlanFreeMemory 関数を呼び出して使用後に解放する必要があります。

どのユーザーも WlanHostedNetworkQuerySecondaryKey 関数を呼び出して、Hosted Network で使用されるセカンダリセキュリティキーに対してクエリを実行できます。ただし、ワイヤレスホステッドネットワークを有効にする機能は、ドメイン内のグループポリシーによって制限される場合があります。

Windows 7 以降では、ホスト型ネットワーク対応ワイヤレスアダプターがコンピューターに存在する場合、オペレーティングシステムによって仮想デバイスがインストールされます。この仮想デバイスは、通常、コンピューターに 1 つのワイヤレスネットワークアダプターがある場合、"ネットワーク接続フォルダー" に "ワイヤレスネットワーク接続 2" として表示され、デバイス名は "Microsoft Virtual WiFi ミニポートアダプター" になります。この仮想デバイスは、ソフトウェアアクセスポイント (SoftAP) 接続の実行専用に使用され、 WlanEnumInterfaces 関数によって返されるリストには存在しません。この仮想デバイスの有効期間は、物理ワイヤレスアダプターに関連付けられます。物理ワイヤレスアダプターが無効になっている場合、この仮想デバイスも削除されます。この機能は、ワイヤレス LAN サービスがインストールされている Windows Server 2008 R2 でも使用できます。

要件


サポートされている最小のクライアント	Windows 7 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 R2 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	wlanapi.h (Wlanapi.h を含む)
Library	Wlanapi.lib
[DLL]	Wlanapi.dll

次の方法で共有

WlanHostedNetworkQuerySecondaryKey 関数 (wlanapi.h)

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

その他のリソース