ホーム › NetworkManagement.WiFi › WlanHostedNetworkQuerySecondaryKey

WlanHostedNetworkQuerySecondaryKey

関数

ホストネットワークのセカンダリセキュリティキーを取得する。

DLLwlanapi.dll呼出規約winapi対応OSWindows 7 以降

シグネチャ

// wlanapi.dll
#include <windows.h>

DWORD WlanHostedNetworkQuerySecondaryKey(
    HANDLE hClientHandle,
    DWORD* pdwKeyLength,
    BYTE** ppucKeyData,
    BOOL* pbIsPassPhrase,
    BOOL* pbPersistent,
    WLAN_HOSTED_NETWORK_REASON* pFailReason,   // optional
    void* pvReserved   // optional
);

パラメーター

名前	型	方向	説明
hClientHandle	HANDLE	in	クライアントのセッションハンドル。以前の WlanOpenHandle 関数の呼び出しによって返されたものです。
pdwKeyLength	DWORD*	out	WlanHostedNetworkQuerySecondaryKey 関数の呼び出しが成功した場合に、ppucKeyData パラメーターが指すキーデータ配列内の有効なデータバイト数を示す値へのポインター。キーがパスフレーズの場合、このキー長には終端の ‘\0’ が含まれます。
ppucKeyData	BYTE**	out	WlanHostedNetworkQuerySecondaryKey 関数の呼び出しが成功した場合に、返されたセカンダリセキュリティキーデータを格納するバッファーへのポインターを受け取る値へのポインター。
pbIsPassPhrase	BOOL*	out	ppucKeyData パラメーターが指すキーデータ配列がパスフレーズ形式かどうかを示すブール値へのポインター。このパラメーターが TRUE の場合、キーデータ配列はパスフレーズ形式です。このパラメーターが FALSE の場合、キーデータ配列はパスフレーズ形式ではありません。
pbPersistent	BOOL*	out	ppucKeyData パラメーターが指すキーデータ配列を保存して後で再利用するのか、1 回限りの使用なのかを示すブール値へのポインター。このパラメーターが TRUE の場合、キーデータ配列は保存されて後で再利用されます。このパラメーターが FALSE の場合、キーデータ配列は 1 回限りの使用です。
pFailReason	WLAN_HOSTED_NETWORK_REASON*	outoptional	WlanHostedNetworkSetSecondaryKey 関数の呼び出しが失敗した場合に、失敗の理由を受け取る値への省略可能なポインター。失敗の理由として指定できる値は、Wlanapi.h ヘッダーファイルで定義されている WLAN_HOSTED_NETWORK_REASON 列挙型の値です。
pvReserved	void*	optional	将来の使用のために予約されています。このパラメーターは NULL である必要があります。

戻り値の型: DWORD

公式ドキュメント

ワイヤレス Hosted Network で使用するように構成されているセカンダリセキュリティキーを照会します。

戻り値

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

関数が失敗した場合、戻り値は次のいずれかのリターンコードになることがあります。

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

解説(Remarks)

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

クライアントアプリケーションは、WlanHostedNetworkQuerySecondaryKey 関数を呼び出して、ワイヤレス Hosted Network で使用されるセカンダリセキュリティキーを照会します。この関数は、キーデータ、キー長、パスフレーズかどうか、永続的か 1 回限りの使用かといったキー情報を返します。この関数は、ワイヤレス Hosted Network の状態やプロパティを変更しません。

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 が既に開始されていればただちに使用され、そうでなければ次に Hosted Network が開始されるときにのみ使用されます。Hosted Network が停止した後は、このセカンダリセキュリティキーが再び使用されることはなく、システムから削除されます。

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

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

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

Windows 7 以降では、Hosted Network に対応したワイヤレスアダプターがコンピューターに存在する場合、オペレーティングシステムは仮想デバイスをインストールします。コンピューターにワイヤレスネットワークアダプターが 1 つしかない場合、この仮想デバイスは通常、「ネットワーク接続フォルダー」に、デバイス名が 'Microsoft Virtual WiFi Miniport adapter' の 'ワイヤレスネットワーク接続 2' として表示されます。この仮想デバイスは、ソフトウェアアクセスポイント (SoftAP) 接続を実行するためだけに使用され、WlanEnumInterfaces 関数が返す一覧には含まれません。この仮想デバイスの有効期間は、物理的なワイヤレスアダプターに結び付けられています。物理的なワイヤレスアダプターが無効にされると、この仮想デバイスも削除されます。この機能は、Wireless LAN Service がインストールされた Windows Server 2008 R2 でも利用できます。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// wlanapi.dll
#include <windows.h>

DWORD WlanHostedNetworkQuerySecondaryKey(
    HANDLE hClientHandle,
    DWORD* pdwKeyLength,
    BYTE** ppucKeyData,
    BOOL* pbIsPassPhrase,
    BOOL* pbPersistent,
    WLAN_HOSTED_NETWORK_REASON* pFailReason,   // optional
    void* pvReserved   // optional
);

[DllImport("wlanapi.dll", ExactSpelling = true)]
static extern uint WlanHostedNetworkQuerySecondaryKey(
    IntPtr hClientHandle,   // HANDLE
    out uint pdwKeyLength,   // DWORD* out
    IntPtr ppucKeyData,   // BYTE** out
    out bool pbIsPassPhrase,   // BOOL* out
    out bool pbPersistent,   // BOOL* out
    IntPtr pFailReason,   // WLAN_HOSTED_NETWORK_REASON* optional, out
    IntPtr pvReserved   // void* optional
);

<DllImport("wlanapi.dll", ExactSpelling:=True)>
Public Shared Function WlanHostedNetworkQuerySecondaryKey(
    hClientHandle As IntPtr,   ' HANDLE
    <Out> ByRef pdwKeyLength As UInteger,   ' DWORD* out
    ppucKeyData As IntPtr,   ' BYTE** out
    <Out> ByRef pbIsPassPhrase As Boolean,   ' BOOL* out
    <Out> ByRef pbPersistent As Boolean,   ' BOOL* out
    pFailReason As IntPtr,   ' WLAN_HOSTED_NETWORK_REASON* optional, out
    pvReserved As IntPtr   ' void* optional
) As UInteger
End Function

' hClientHandle : HANDLE
' pdwKeyLength : DWORD* out
' ppucKeyData : BYTE** out
' pbIsPassPhrase : BOOL* out
' pbPersistent : BOOL* out
' pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out
' pvReserved : void* optional
Declare PtrSafe Function WlanHostedNetworkQuerySecondaryKey Lib "wlanapi" ( _
    ByVal hClientHandle As LongPtr, _
    ByRef pdwKeyLength As Long, _
    ByVal ppucKeyData As LongPtr, _
    ByRef pbIsPassPhrase As Long, _
    ByRef pbPersistent As Long, _
    ByVal pFailReason As LongPtr, _
    ByVal pvReserved As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WlanHostedNetworkQuerySecondaryKey = ctypes.windll.wlanapi.WlanHostedNetworkQuerySecondaryKey
WlanHostedNetworkQuerySecondaryKey.restype = wintypes.DWORD
WlanHostedNetworkQuerySecondaryKey.argtypes = [
    wintypes.HANDLE,  # hClientHandle : HANDLE
    ctypes.POINTER(wintypes.DWORD),  # pdwKeyLength : DWORD* out
    ctypes.c_void_p,  # ppucKeyData : BYTE** out
    ctypes.c_void_p,  # pbIsPassPhrase : BOOL* out
    ctypes.c_void_p,  # pbPersistent : BOOL* out
    ctypes.c_void_p,  # pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out
    ctypes.POINTER(None),  # pvReserved : void* optional
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('wlanapi.dll')
WlanHostedNetworkQuerySecondaryKey = Fiddle::Function.new(
  lib['WlanHostedNetworkQuerySecondaryKey'],
  [
    Fiddle::TYPE_VOIDP,  # hClientHandle : HANDLE
    Fiddle::TYPE_VOIDP,  # pdwKeyLength : DWORD* out
    Fiddle::TYPE_VOIDP,  # ppucKeyData : BYTE** out
    Fiddle::TYPE_VOIDP,  # pbIsPassPhrase : BOOL* out
    Fiddle::TYPE_VOIDP,  # pbPersistent : BOOL* out
    Fiddle::TYPE_VOIDP,  # pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out
    Fiddle::TYPE_VOIDP,  # pvReserved : void* optional
  ],
  -Fiddle::TYPE_INT)

#[link(name = "wlanapi")]
extern "system" {
    fn WlanHostedNetworkQuerySecondaryKey(
        hClientHandle: *mut core::ffi::c_void,  // HANDLE
        pdwKeyLength: *mut u32,  // DWORD* out
        ppucKeyData: *mut *mut u8,  // BYTE** out
        pbIsPassPhrase: *mut i32,  // BOOL* out
        pbPersistent: *mut i32,  // BOOL* out
        pFailReason: *mut i32,  // WLAN_HOSTED_NETWORK_REASON* optional, out
        pvReserved: *mut ()  // void* optional
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("wlanapi.dll")]
public static extern uint WlanHostedNetworkQuerySecondaryKey(IntPtr hClientHandle, out uint pdwKeyLength, IntPtr ppucKeyData, out bool pbIsPassPhrase, out bool pbPersistent, IntPtr pFailReason, IntPtr pvReserved);
"@
$api = Add-Type -MemberDefinition $sig -Name 'wlanapi_WlanHostedNetworkQuerySecondaryKey' -Namespace Win32 -PassThru
# $api::WlanHostedNetworkQuerySecondaryKey(hClientHandle, pdwKeyLength, ppucKeyData, pbIsPassPhrase, pbPersistent, pFailReason, pvReserved)

#uselib "wlanapi.dll"
#func global WlanHostedNetworkQuerySecondaryKey "WlanHostedNetworkQuerySecondaryKey" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; WlanHostedNetworkQuerySecondaryKey hClientHandle, varptr(pdwKeyLength), varptr(ppucKeyData), varptr(pbIsPassPhrase), varptr(pbPersistent), varptr(pFailReason), pvReserved   ; 戻り値は stat
; hClientHandle : HANDLE -> "sptr"
; pdwKeyLength : DWORD* out -> "sptr"
; ppucKeyData : BYTE** out -> "sptr"
; pbIsPassPhrase : BOOL* out -> "sptr"
; pbPersistent : BOOL* out -> "sptr"
; pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out -> "sptr"
; pvReserved : void* optional -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "wlanapi.dll"
#cfunc global WlanHostedNetworkQuerySecondaryKey "WlanHostedNetworkQuerySecondaryKey" sptr, var, var, var, var, var, sptr
; res = WlanHostedNetworkQuerySecondaryKey(hClientHandle, pdwKeyLength, ppucKeyData, pbIsPassPhrase, pbPersistent, pFailReason, pvReserved)
; hClientHandle : HANDLE -> "sptr"
; pdwKeyLength : DWORD* out -> "var"
; ppucKeyData : BYTE** out -> "var"
; pbIsPassPhrase : BOOL* out -> "var"
; pbPersistent : BOOL* out -> "var"
; pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out -> "var"
; pvReserved : void* optional -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "wlanapi.dll"
#cfunc global WlanHostedNetworkQuerySecondaryKey "WlanHostedNetworkQuerySecondaryKey" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; res = WlanHostedNetworkQuerySecondaryKey(hClientHandle, varptr(pdwKeyLength), varptr(ppucKeyData), varptr(pbIsPassPhrase), varptr(pbPersistent), varptr(pFailReason), pvReserved)
; hClientHandle : HANDLE -> "sptr"
; pdwKeyLength : DWORD* out -> "sptr"
; ppucKeyData : BYTE** out -> "sptr"
; pbIsPassPhrase : BOOL* out -> "sptr"
; pbPersistent : BOOL* out -> "sptr"
; pFailReason : WLAN_HOSTED_NETWORK_REASON* optional, out -> "sptr"
; pvReserved : void* optional -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。