WlanRegisterNotification 函式 (wlanapi.h)
重要
有些資訊與發行前版本產品有關，在正式發行前可能會大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
WlanRegisterNotification 函式可用來在所有無線介面上註冊和取消註冊通知。
語法
DWORD WlanRegisterNotification(
[in] HANDLE hClientHandle,
[in] DWORD dwNotifSource,
[in] BOOL bIgnoreDuplicate,
[in, optional] WLAN_NOTIFICATION_CALLBACK funcCallback,
[in, optional] PVOID pCallbackContext,
[in] PVOID pReserved,
[out, optional] PDWORD pdwPrevNotifSource
);
參數
[in] hClientHandle
用戶端的會話句柄，由先前呼叫 WlanOpenHandle 函式取得。
[in] dwNotifSource
要註冊的通知來源。 這些旗標可以合併。 當此參數設定為 WLAN_NOTIFICATION_SOURCE_NONE 時， WlanRegisterNotification 會在所有無線介面上取消註冊通知。
此參數的可能值定義在 Wlanapi.h 和 L2cmn.h 頭檔中。
下表顯示可能的值。
| 值 | 意義 |
|---|---|
|
取消註冊通知。 |
|
註冊操作系統版本上所有可用的通知，包括802.1X模組所產生的通知。
對於 Windows XP SP3 和 Windows XP SP2 的無線 LAN API，將 dwNotifSource 設定為 WLAN_NOTIFICATION_SOURCE_ALL 的功能相當於將 dwNotifSource 設定為 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通知可用。 |
|
註冊無線託管網路所產生的通知。 此通知來源可在 Windows 7 和已安裝無線 LAN 服務的 Windows Server 2008 R2 上使用。 |
|
註冊 802.1X 所產生的通知。 |
|
註冊 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定義任何通知。 Windows XP with SP3 和 Wireless LAN API for Windows XP with SP2： 不支援這個值。 |
|
註冊獨立硬體廠商所產生的通知， (IHV) 。
Windows XP with SP3 和 Wireless LAN API for Windows XP with SP2： 不支援這個值。 |
|
註冊裝置服務所產生的通知。 |
Windows XP with SP3 和 Wireless LAN API for Windows XP with SP2： 此參數必須設定為 WLAN_NOTIFICATION_SOURCE_NONE、WLAN_NOTIFICATION_SOURCE_ALL 或 WLAN_NOTIFICATION_SOURCE_ACM。
[in] bIgnoreDuplicate
指定是否要忽略重複的通知。 如果設定為 TRUE，如果通知與前一個通知相同，則不會將通知傳送給用戶端。
Windows XP with SP3 和 Wireless LAN API for Windows XP with SP2： 忽略此參數。
[in, optional] funcCallback
定義通知回呼函式類型的 WLAN_NOTIFICATION_CALLBACK 型別。
如果 dwNotifSource 參數設定為WLAN_NOTIFICATION_SOURCE_NONE在所有無線介面上取消註冊通知，這個參數可以是 NULL。
[in, optional] pCallbackContext
將傳遞至回呼函式且具有通知之用戶端內容的指標。
[in] pReserved
保留供未來使用。 必須設定為 NULL。
[out, optional] pdwPrevNotifSource
先前註冊之通知來源的指標。
傳回值
如果函式成功，傳回值會ERROR_SUCCESS。
如果函式失敗，傳回值可能是下列其中一個傳回碼。
如果在 dwNotifSource 中設定WLAN_NOTIFICATION_SOURCE_MSM旗標，則需要wiFiControl裝置功能 (請參閱應用程式功能宣告) 。 如果未授與該功能，則函式會 傳回ERROR_ACCESS_DENIED。 要求 wiFiControl 裝置功能需要使用者同意，以取得位置的存取權。 如需詳細資訊，請參閱 Wi-Fi 存取和位置的 API 行為變更。
| 傳回碼 | Description |
|---|---|
|
參數不正確。 如果 hClientHandle 為 NULL 或無效，或 pReserved 不是 NULL，則會傳回此錯誤。 |
|
句柄數據表中找不到句柄 hClientHandle 。 |
|
無法為查詢結果配置記憶體。 |
|
如果在 dwNotifSource 中設定WLAN_NOTIFICATION_SOURCE_MSM旗標，則需要wiFiControl裝置功能 (請參閱應用程式功能宣告。 如果未授與該功能，則函式會 傳回ERROR_ACCESS_DENIED。 要求 wiFiControl 裝置功能需要使用者同意，以取得位置的存取權。 如需詳細資訊，請參閱 Wi-Fi 存取和位置的 API 行為變更。 |
|
各種錯誤碼。 |
備註
WlanRegisterNotification 是由應用程式用來在所有無線介面上註冊和取消註冊通知。 註冊通知時，應用程式必須提供 funcCallback 參數指向的回呼函式。 此回呼函式的原型是 WLAN_NOTIFICATION_CALLBACK。 此回呼函式會收到已在傳遞至 WlanRegisterNotification 函式的 dwNotifSource 參數中註冊的通知。 呼叫回呼函式時，會以 WLAN_NOTIFICATION_DATA 結構的指標作為包含通知詳細資訊的第一個參數。 回呼函式也會接收第二個參數，其中包含傳遞至 WlanRegisterNotification 函式之 pCallbackContext 參數中用戶端內容的指標。
如果 dwNotifSource 是WLAN_NOTIFICATION_SOURCE_NONE以外的值，而且客戶端無法提供回呼函式，WlanRegisterNotification 函式會傳回錯誤。
註冊之後，每當有通知可用時，就會呼叫回呼函式，直到用戶端取消註冊或關閉句柄為止。
如果呼叫應用程式使用 hClientHandle 參數呼叫 WlanCloseHandle，) 或行程結束，呼叫 WlanCloseHandle 來關閉其呼叫句柄 (，則會自動復原此函式所造成的任何通知。
請勿從回調函式呼叫 WlanRegisterNotification 。 如果在 呼叫 WlanRegisterNotification 且 dwNotifSource 設為 WLAN_NOTIFICATION_SOURCE_NONE ( 時，用戶端在通知回呼中間) ， 則 WlanRegisterNotification 會在傳回值之前等候回呼完成。 在回呼函式內呼叫此函式會導致呼叫永遠不會完成。 如果回呼函式和從通知取消註冊的線程嘗試取得相同的鎖定，可能會發生死結。 此外，請勿從應用程式 DLL 中的 DllMain 函式呼叫 WlanRegisterNotification。 這也可能導致死結。
應用程式可能會逾時並查詢目前的介面狀態，而不是等候通知。
Windows XP with SP3 和 Wireless LAN API for Windows XP with SP2： Netman 服務會處理通知。 如果 Netman 服務已停用或無法使用，將不會收到通知。 如果未在合理的時間內收到通知，應用程式應該逾時並查詢目前的介面狀態。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Vista、Windows XP 與 SP3 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | wlanapi.h (包含 Wlanapi.h) |
| 程式庫 | Wlanapi.lib |
| Dll | Wlanapi.dll |
| 可轉散發套件 | 適用於 Windows XP 與 SP2 的無線 LAN API |