WlanHostedNetworkSetSecondaryKey 関数 (wlanapi.h)

  • [アーティクル]

WlanHostedNetworkSetSecondaryKey 関数は、ワイヤレスホステッド ネットワークで使用されるセカンダリ セキュリティ キーを構成します。

構文

DWORD WlanHostedNetworkSetSecondaryKey(
  [in]            HANDLE                      hClientHandle,
  [in]            DWORD                       dwKeyLength,
  [in]            PUCHAR                      pucKeyData,
  [in]            BOOL                        bIsPassPhrase,
  [in]            BOOL                        bPersistent,
  [out, optional] PWLAN_HOSTED_NETWORK_REASON pFailReason,
                  PVOID                       pvReserved
);

パラメーター

[in] hClientHandle

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

[in] dwKeyLength

pucKeyData パラメーターが指すキー データ配列内の有効なデータ バイト数。 キーがパスフレーズの場合、このキーの長さは終端の '\0' を含める必要があります。

[in] pucKeyData

キー データを含むバッファーへのポインター。 バッファー内の有効なデータ バイト数は、 dwKeyLength パラメーターで指定された値以上である必要があります。

[in] bIsPassPhrase

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

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

[in] bPersistent

pucKeyData パラメーターが指すキー データ配列を後で格納して再利用するか、1 回限り使用するかどうかを示すブール値。

このパラメーターが TRUE の場合、キー データ配列は後で格納および再利用されます。 このパラメーターが FALSE の場合、キー データ配列は 1 つのセッション (現在のセッション、または Hosted Network が開始されていない場合は次のセッション) に使用されます。

[out, optional] pFailReason

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

pvReserved

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

戻り値

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

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

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

解説

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

クライアント アプリケーションは WlanHostedNetworkSetSecondaryKey 関数を呼び出して、ワイヤレス ホステッド ネットワークで使用されるセカンダリ セキュリティ キーを構成します。 呼び出し元のアプリケーションが呼び出し元のハンドルを閉じる (hClientHandle パラメーターを指定して WlanCloseHandle を呼び出す) 場合、またはプロセスが終了した場合、この関数によって発生した Hosted Network の変更は自動的に元に戻されません。

開始すると、ワイヤレス ホステッド ネットワークを使用すると、ワイヤレス ピアはプライマリ セキュリティ キーに加えて、このセカンダリ セキュリティ キーに関連付けることができます。 セカンダリ セキュリティ キーは、必要に応じて常にユーザーによって指定されますが、プライマリ セキュリティ キーは、セキュリティ強度が高いオペレーティング システムによって生成されます。

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

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

有効なセカンダリ セキュリティ キーを構成するには、 dwKeyLength パラメーターが正しい範囲にあり、 pucKeyData パラメーターが、指定されたデータバイトを含む有効なメモリ バッファーを指している必要があります。 現在構成されているセカンダリ セキュリティ キーをシステムから削除するには、アプリケーションで wlanHostedNetworkSetSecondaryKey 関数を呼び出し、dwKeyLength パラメーターに 0 を、pucKeyData パラメーターに NULL を指定する必要があります。

pucKeyData パラメーターが NULL の場合、wlanHostedNetworkSetSecondaryKey 関数はERROR_INVALID_PARAMETERを返しますが、dwKeyLength パラメーターは 0 ではありません。 dwKeyLength パラメーターが 0 の場合でも、wlanHostedNetworkSetSecondaryKey 関数は ERROR_INVALID_PARAMETER を返しますが、pucKeyData パラメーターは NULL ではありません。

通常、セカンダリ セキュリティ キーは、ワイヤレスホスト型ネットワークが開始される前に設定されます。 次に、ホストされたネットワークが開始されたときに使用されます。

セカンダリ セキュリティ キーは、Hosted Network の開始後に設定することもできます。 この場合、セカンダリ セキュリティ キーはすぐに使用されます。 以前のセカンダリ セキュリティ キーを使用しているクライアントは接続されたままになりますが、何らかの理由で切断された場合、またはワイヤレスホスト型ネットワークが再起動された場合は再接続できません。

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

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

任意のユーザーがこの関数を呼び出して、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

WlanHostedNetworkInitSettings

WlanHostedNetworkQueryProperty

WlanHostedNetworkQuerySecondaryKey

WlanHostedNetworkRefreshSecuritySettings

WlanHostedNetworkSetProperty

WlanOpenHandle