WlanHostedNetworkQuerySecondaryKey 関数 (wlanapi.h)

  • [アーティクル]

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

関連項目

ワイヤレス ホステッド ネットワークについて

ワイヤレス ホスト型ネットワークとインターネット接続共有の使用

WLAN_HOSTED_NETWORK_REASON

WlanCloseHandle

WlanEnumInterfaces

WlanFreeMemory

WlanHostedNetworkInitSettings

WlanHostedNetworkQueryProperty

WlanHostedNetworkQueryStatus

WlanHostedNetworkRefreshSecuritySettings

WlanHostedNetworkSetProperty

WlanHostedNetworkSetSecondaryKey

WlanOpenHandle