ホーム › NetworkManagement.WiFi › WlanRegisterNotification

WlanRegisterNotification

関数

WLANイベントの通知を受け取るコールバックを登録する。

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

シグネチャ

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

DWORD WlanRegisterNotification(
    HANDLE hClientHandle,
    WLAN_NOTIFICATION_SOURCES dwNotifSource,
    BOOL bIgnoreDuplicate,
    WLAN_NOTIFICATION_CALLBACK funcCallback,   // optional
    void* pCallbackContext,   // optional
    void* pReserved,   // optional
    DWORD* pdwPrevNotifSource   // optional
);

パラメーター

名前

型

方向

説明

hClientHandle

HANDLE

クライアントのセッションハンドル。WlanOpenHandle 関数の以前の呼び出しによって取得します。

dwNotifSource

WLAN_NOTIFICATION_SOURCES

登録する通知ソース。これらのフラグは組み合わせて指定できます。このパラメーターに WLAN_NOTIFICATION_SOURCE_NONE を指定した場合、WlanRegisterNotification はすべてのワイヤレスインターフェイスの通知を登録解除します。

このパラメーターに指定できる値は、Wlanapi.h および L2cmn.h ヘッダーファイルで定義されています。

次の表に、指定できる値を示します。

値	意味
WLAN_NOTIFICATION_SOURCE_NONE	通知を登録解除します。
WLAN_NOTIFICATION_SOURCE_ALL	802.1X モジュールによって生成されるものを含め、そのオペレーティングシステムのバージョンで利用可能なすべての通知に登録します。 Windows XP with SP3 および Wireless LAN API for Windows XP with SP2 では、dwNotifSource に WLAN_NOTIFICATION_SOURCE_ALL を指定することは、dwNotifSource に WLAN_NOTIFICATION_SOURCE_ACM を指定することと機能的に同等です。
WLAN_NOTIFICATION_SOURCE_ACM	自動構成モジュールによって生成される通知に登録します。 Windows XP with SP3 および Wireless LAN API for Windows XP with SP2: wlan_notification_acm_connection_complete 通知と wlan_notification_acm_disconnected 通知のみが利用できます。
WLAN_NOTIFICATION_SOURCE_HNWK	ワイヤレスホステッドネットワークによって生成される通知に登録します。この通知ソースは、Windows 7 および Wireless LAN サービスがインストールされた Windows Server 2008 R2 で利用できます。
WLAN_NOTIFICATION_SOURCE_ONEX	802.1X によって生成される通知に登録します。
WLAN_NOTIFICATION_SOURCE_MSM	MSM によって生成される通知に登録します。 dwNotifSource に WLAN_NOTIFICATION_SOURCE_MSM フラグが設定されている場合、wiFiControl デバイス機能が必要です(アプリ機能の宣言を参照)。この機能が許可されていない場合、この関数は ERROR_ACCESS_DENIED を返します。wiFiControl デバイス機能を要求する際には、位置情報へのアクセスに関するユーザーの同意が必要になります。詳細については、Wi-Fi アクセスと位置情報に関する API の動作の変更を参照してください。 Windows XP with SP3 および Wireless LAN API for Windows XP with SP2: この値はサポートされていません。
WLAN_NOTIFICATION_SOURCE_SECURITY	セキュリティモジュールによって生成される通知に登録します。現在、WLAN_NOTIFICATION_SOURCE_SECURITY に対する通知は定義されていません。 Windows XP with SP3 および Wireless LAN API for Windows XP with SP2: この値はサポートされていません。
WLAN_NOTIFICATION_SOURCE_IHV	独立系ハードウェアベンダー (IHV) によって生成される通知に登録します。 Windows XP with SP3 および Wireless LAN API for Windows XP with SP2: この値はサポートされていません。
WLAN_NOTIFICATION_SOURCE_DEVICE_SERVICE	デバイスサービスによって生成される通知に登録します。

Windows XP with SP3 および Wireless LAN API for Windows XP with SP2: このパラメーターには、WLAN_NOTIFICATION_SOURCE_NONE、WLAN_NOTIFICATION_SOURCE_ALL、または WLAN_NOTIFICATION_SOURCE_ACM を指定する必要があります。

bIgnoreDuplicate

BOOL

重複する通知を無視するかどうかを指定します。TRUE を指定した場合、直前の通知と同一の通知はクライアントに送信されません。

Windows XP with SP3 および Wireless LAN API for Windows XP with SP2: このパラメーターは無視されます。

funcCallback

WLAN_NOTIFICATION_CALLBACK

inoptional

通知コールバック関数の型を定義する WLAN_NOTIFICATION_CALLBACK 型です。

すべてのワイヤレスインターフェイスの通知を登録解除するために dwNotifSource パラメーターに WLAN_NOTIFICATION_SOURCE_NONE を指定する場合、このパラメーターは NULL にできます。

pCallbackContext

void*

inoptional

通知と共にコールバック関数へ渡されるクライアントコンテキストへのポインター。

pReserved

void*

optional

将来の使用のために予約されています。NULL を指定する必要があります。

pdwPrevNotifSource

DWORD*

outoptional

以前に登録されていた通知ソースへのポインター。

戻り値の型: DWORD

公式ドキュメント

すべてのワイヤレスインターフェイスに対する通知の登録および登録解除を行います。

戻り値

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

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

dwNotifSource に WLAN_NOTIFICATION_SOURCE_MSM フラグが設定されている場合、wiFiControl デバイス機能が必要です(アプリ機能の宣言を参照)。この機能が許可されていない場合、この関数は ERROR_ACCESS_DENIED を返します。wiFiControl デバイス機能を要求する際には、位置情報へのアクセスに関するユーザーの同意が必要になります。詳細については、Wi-Fi アクセスと位置情報に関する API の動作の変更を参照してください。

リターンコード	説明
ERROR_INVALID_PARAMETER	パラメーターが正しくありません。このエラーは、hClientHandle が NULL であるか無効な場合、または pReserved が NULL でない場合に返されます。
ERROR_INVALID_HANDLE	ハンドル hClientHandle がハンドルテーブル内に見つかりませんでした。
ERROR_NOT_ENOUGH_MEMORY	クエリ結果用のメモリの割り当てに失敗しました。
ERROR_ACCESS_DENIED	dwNotifSource に WLAN_NOTIFICATION_SOURCE_MSM フラグが設定されている場合、wiFiControl デバイス機能が必要です(アプリ機能の宣言を参照)。この機能が許可されていない場合、この関数は ERROR_ACCESS_DENIED を返します。wiFiControl デバイス機能を要求する際には、位置情報へのアクセスに関するユーザーの同意が必要になります。詳細については、Wi-Fi アクセスと位置情報に関する API の動作の変更を参照してください。
RPC_STATUS	さまざまなエラーコード。

解説(Remarks)

WlanRegisterNotification は、アプリケーションがすべてのワイヤレスインターフェイスに対する通知を登録および登録解除するために使用します。通知を登録する際、アプリケーションは funcCallback パラメーターが指すコールバック関数を提供する必要があります。このコールバック関数のプロトタイプは WLAN_NOTIFICATION_CALLBACK です。このコールバック関数は、WlanRegisterNotification 関数に渡した dwNotifSource パラメーターで登録した通知を受け取ります。コールバック関数は、第 1 パラメーターとして、通知に関する詳細情報を格納した WLAN_NOTIFICATION_DATA 構造体へのポインターを受け取ります。また、第 2 パラメーターとして、WlanRegisterNotification 関数の pCallbackContext パラメーターに渡したクライアントコンテキストへのポインターを受け取ります。

dwNotifSource が WLAN_NOTIFICATION_SOURCE_NONE 以外の値であるにもかかわらず、クライアントがコールバック関数を提供しなかった場合、WlanRegisterNotification 関数はエラーを返します。

登録後は、クライアントが登録解除するかハンドルを閉じるまで、通知が利用可能になるたびにコールバック関数が呼び出されます。

この関数によって行われた通知受信の登録は、呼び出し元アプリケーションが呼び出しに使用したハンドルを閉じた場合(hClientHandle パラメーターを指定して WlanCloseHandle を呼び出した場合)、またはプロセスが終了した場合に、自動的に解除されます。

コールバック関数から WlanRegisterNotification を呼び出さないでください。クライアントが通知コールバックの処理中に、dwNotifSource に WLAN_NOTIFICATION_SOURCE_NONE を指定して WlanRegisterNotification が呼び出された場合(つまり、クライアントが通知の登録を解除する場合)、WlanRegisterNotification は値を返す前にコールバックの完了を待機します。コールバック関数の内部でこの関数を呼び出すと、その呼び出しは完了しません。また、コールバック関数と、通知の登録を解除するスレッドの両方が同じロックを取得しようとすると、デッドロックが発生する可能性があります。さらに、アプリケーション DLL の DllMain 関数から WlanRegisterNotification を呼び出さないでください。これもデッドロックの原因になる可能性があります。

アプリケーションは、通知を待機する代わりに、タイムアウトして現在のインターフェイスの状態を照会することもできます。

Windows XP with SP3 および Wireless LAN API for Windows XP with SP2: 通知は Netman サービスによって処理されます。Netman サービスが無効になっているか利用できない場合、通知は受信されません。妥当な時間内に通知が受信されない場合、アプリケーションはタイムアウトして現在のインターフェイスの状態を照会する必要があります。

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

各言語での呼び出し定義

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

DWORD WlanRegisterNotification(
    HANDLE hClientHandle,
    WLAN_NOTIFICATION_SOURCES dwNotifSource,
    BOOL bIgnoreDuplicate,
    WLAN_NOTIFICATION_CALLBACK funcCallback,   // optional
    void* pCallbackContext,   // optional
    void* pReserved,   // optional
    DWORD* pdwPrevNotifSource   // optional
);

[DllImport("wlanapi.dll", ExactSpelling = true)]
static extern uint WlanRegisterNotification(
    IntPtr hClientHandle,   // HANDLE
    uint dwNotifSource,   // WLAN_NOTIFICATION_SOURCES
    bool bIgnoreDuplicate,   // BOOL
    IntPtr funcCallback,   // WLAN_NOTIFICATION_CALLBACK optional
    IntPtr pCallbackContext,   // void* optional
    IntPtr pReserved,   // void* optional
    IntPtr pdwPrevNotifSource   // DWORD* optional, out
);

<DllImport("wlanapi.dll", ExactSpelling:=True)>
Public Shared Function WlanRegisterNotification(
    hClientHandle As IntPtr,   ' HANDLE
    dwNotifSource As UInteger,   ' WLAN_NOTIFICATION_SOURCES
    bIgnoreDuplicate As Boolean,   ' BOOL
    funcCallback As IntPtr,   ' WLAN_NOTIFICATION_CALLBACK optional
    pCallbackContext As IntPtr,   ' void* optional
    pReserved As IntPtr,   ' void* optional
    pdwPrevNotifSource As IntPtr   ' DWORD* optional, out
) As UInteger
End Function

' hClientHandle : HANDLE
' dwNotifSource : WLAN_NOTIFICATION_SOURCES
' bIgnoreDuplicate : BOOL
' funcCallback : WLAN_NOTIFICATION_CALLBACK optional
' pCallbackContext : void* optional
' pReserved : void* optional
' pdwPrevNotifSource : DWORD* optional, out
Declare PtrSafe Function WlanRegisterNotification Lib "wlanapi" ( _
    ByVal hClientHandle As LongPtr, _
    ByVal dwNotifSource As Long, _
    ByVal bIgnoreDuplicate As Long, _
    ByVal funcCallback As LongPtr, _
    ByVal pCallbackContext As LongPtr, _
    ByVal pReserved As LongPtr, _
    ByVal pdwPrevNotifSource As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WlanRegisterNotification = ctypes.windll.wlanapi.WlanRegisterNotification
WlanRegisterNotification.restype = wintypes.DWORD
WlanRegisterNotification.argtypes = [
    wintypes.HANDLE,  # hClientHandle : HANDLE
    wintypes.DWORD,  # dwNotifSource : WLAN_NOTIFICATION_SOURCES
    wintypes.BOOL,  # bIgnoreDuplicate : BOOL
    ctypes.c_void_p,  # funcCallback : WLAN_NOTIFICATION_CALLBACK optional
    ctypes.POINTER(None),  # pCallbackContext : void* optional
    ctypes.POINTER(None),  # pReserved : void* optional
    ctypes.POINTER(wintypes.DWORD),  # pdwPrevNotifSource : DWORD* optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('wlanapi.dll')
WlanRegisterNotification = Fiddle::Function.new(
  lib['WlanRegisterNotification'],
  [
    Fiddle::TYPE_VOIDP,  # hClientHandle : HANDLE
    -Fiddle::TYPE_INT,  # dwNotifSource : WLAN_NOTIFICATION_SOURCES
    Fiddle::TYPE_INT,  # bIgnoreDuplicate : BOOL
    Fiddle::TYPE_VOIDP,  # funcCallback : WLAN_NOTIFICATION_CALLBACK optional
    Fiddle::TYPE_VOIDP,  # pCallbackContext : void* optional
    Fiddle::TYPE_VOIDP,  # pReserved : void* optional
    Fiddle::TYPE_VOIDP,  # pdwPrevNotifSource : DWORD* optional, out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "wlanapi")]
extern "system" {
    fn WlanRegisterNotification(
        hClientHandle: *mut core::ffi::c_void,  // HANDLE
        dwNotifSource: u32,  // WLAN_NOTIFICATION_SOURCES
        bIgnoreDuplicate: i32,  // BOOL
        funcCallback: *const core::ffi::c_void,  // WLAN_NOTIFICATION_CALLBACK optional
        pCallbackContext: *mut (),  // void* optional
        pReserved: *mut (),  // void* optional
        pdwPrevNotifSource: *mut u32  // DWORD* optional, out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("wlanapi.dll")]
public static extern uint WlanRegisterNotification(IntPtr hClientHandle, uint dwNotifSource, bool bIgnoreDuplicate, IntPtr funcCallback, IntPtr pCallbackContext, IntPtr pReserved, IntPtr pdwPrevNotifSource);
"@
$api = Add-Type -MemberDefinition $sig -Name 'wlanapi_WlanRegisterNotification' -Namespace Win32 -PassThru
# $api::WlanRegisterNotification(hClientHandle, dwNotifSource, bIgnoreDuplicate, funcCallback, pCallbackContext, pReserved, pdwPrevNotifSource)

#uselib "wlanapi.dll"
#func global WlanRegisterNotification "WlanRegisterNotification" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; WlanRegisterNotification hClientHandle, dwNotifSource, bIgnoreDuplicate, funcCallback, pCallbackContext, pReserved, varptr(pdwPrevNotifSource)   ; 戻り値は stat
; hClientHandle : HANDLE -> "sptr"
; dwNotifSource : WLAN_NOTIFICATION_SOURCES -> "sptr"
; bIgnoreDuplicate : BOOL -> "sptr"
; funcCallback : WLAN_NOTIFICATION_CALLBACK optional -> "sptr"
; pCallbackContext : void* optional -> "sptr"
; pReserved : void* optional -> "sptr"
; pdwPrevNotifSource : DWORD* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "wlanapi.dll"
#cfunc global WlanRegisterNotification "WlanRegisterNotification" sptr, int, int, sptr, sptr, sptr, var
; res = WlanRegisterNotification(hClientHandle, dwNotifSource, bIgnoreDuplicate, funcCallback, pCallbackContext, pReserved, pdwPrevNotifSource)
; hClientHandle : HANDLE -> "sptr"
; dwNotifSource : WLAN_NOTIFICATION_SOURCES -> "int"
; bIgnoreDuplicate : BOOL -> "int"
; funcCallback : WLAN_NOTIFICATION_CALLBACK optional -> "sptr"
; pCallbackContext : void* optional -> "sptr"
; pReserved : void* optional -> "sptr"
; pdwPrevNotifSource : DWORD* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "wlanapi.dll"
#cfunc global WlanRegisterNotification "WlanRegisterNotification" sptr, int, int, sptr, sptr, sptr, sptr
; res = WlanRegisterNotification(hClientHandle, dwNotifSource, bIgnoreDuplicate, funcCallback, pCallbackContext, pReserved, varptr(pdwPrevNotifSource))
; hClientHandle : HANDLE -> "sptr"
; dwNotifSource : WLAN_NOTIFICATION_SOURCES -> "int"
; bIgnoreDuplicate : BOOL -> "int"
; funcCallback : WLAN_NOTIFICATION_CALLBACK optional -> "sptr"
; pCallbackContext : void* optional -> "sptr"
; pReserved : void* optional -> "sptr"
; pdwPrevNotifSource : DWORD* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。