notifyUnicastIpAddressChange 函式 (netioapi.h)

發行項
03/05/2024

NotifyUnicastIpAddressChange 函式會註冊，以通知本機計算機上所有單播 IP 介面、單播 IPv4 位址或單播 IPv6 位址的變更。

語法

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyUnicastIpAddressChange(
  [in]      ADDRESS_FAMILY                     Family,
  [in]      PUNICAST_IPADDRESS_CHANGE_CALLBACK Callback,
  [in]      PVOID                              CallerContext,
  [in]      BOOLEAN                            InitialNotification,
  [in, out] HANDLE                             *NotificationHandle
);

參數

[in] Family

要註冊變更通知的位址系列。

位址系列的可能值會列在 Winsock2.h 頭檔中。請注意，AF_位址系列和PF_通訊協定系列常數的值 (相同，例如， AF_INET 和 PF_INET) ，因此可以使用任一個常數。

在針對 Windows Vista 和更新版本發行的 Windows SDK 上，頭檔的組織已變更，而且此成員的可能值定義在 Ws2def.h 頭檔中。請注意， Ws2def.h 頭文件會自動包含在 Winsock2.h 中，不應該直接使用。

目前支援的值是 AF_INET、 AF_INET6和 AF_UNSPEC。

值	意義
AF_INET	只註冊單播 IPv4 位址變更通知。
AF_INET6	只註冊單播 IPv6 位址變更通知。
AF_UNSPEC	註冊單播 IPv4 和 IPv6 位址變更通知。

[in] Callback

發生變更時要呼叫之函式的指標。收到單播IP位址通知時，將會叫用此函式。

[in] CallerContext

收到介面通知時，傳遞至 Callback 參數中指定的回呼函式的用戶內容。

[in] InitialNotification

值，指出在註冊變更通知完成之後，是否應該立即叫用回呼。這個初始通知並不表示單播IP位址發生變更。此參數的目的是要提供回呼已註冊的確認。

[in, out] NotificationHandle

用來傳回句柄的指標，稍後可用來取消註冊變更通知。成功時，此參數會傳回通知句柄。如果發生錯誤，則會傳回 NULL 。

傳回值

如果函式成功，傳回值會NO_ERROR。

如果函式失敗，傳回值就是下列其中一個錯誤碼。

傳回碼	Description
ERROR_INVALID_HANDLE	發生內部錯誤，其中遇到無效的句柄。
ERROR_INVALID_PARAMETER	無效的參數已傳遞至函式。如果 Family 參數不是 AF_INET、 AF_INET6或 AF_UNSPEC，則會傳回此錯誤。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足。
其他	使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

NotifyUnicastIpAddressChange 函式是在 Windows Vista 和更新版本上定義。

Family 參數必須設定為 AF_INET、AF_INET6 或 AF_UNSPEC。

回呼參數中指定的回呼函式調用會串行化。回呼函式應該定義為 VOID 類型的函式。傳遞至回調函式的參數包括下列各項：

參數	Description
IN PVOID CallerContext	註冊通知時傳遞至 NotifyUnicastIpAddressChange 函式的 CallerContext 參數。
IN PMIB_UNICASTIPADDRESS_ROW列選擇性	已變更之單播IP位址之MIB_UNICASTIPADDRESS_ROW 專案的指標。當將 NotificationType 參數中傳遞至回調函式的MIB_NOTIFICATION_TYPE值設定為 MibInitialNotification 時，這個參數是 NULL 指標。只有在註冊通知時，傳遞至 NotifyUnicastIpAddressChange 的 InitialNotification 參數設定為 TRUE 時，才會發生此情況。
IN MIB_NOTIFICATION_TYPE NotificationType	通知類型。這個成員可以是 Netioapi.h 頭檔中所定義MIB_NOTIFICATION_TYPE列舉類型的其中一個值。

Callback 參數中指定的回呼函式必須與呼叫 NotifyUnicastIpAddressChange 函式的應用程式相同進程中實作。如果回呼函式位於個別的 DLL 中，則應該先載入 DLL，再呼叫 NotifyUnicastIpAddressChange 函式來註冊變更通知。

當發生變更且 Row 參數不是 NULL 時收到回呼函式時，在 Row 參數中傳遞之MIB_UNICASTIPADDRESS_ROW結構的指標會包含不完整的數據。 MIB_UNICASTIPADDRESS_ROW結構中傳回的資訊，只是應用程式可以呼叫 GetUnicastIpAddressEntry 函式來查詢所變更 IP 位址的完整資訊。收到回呼函式時，應用程式應該配置MIB_UNICASTIPADDRESS_ROW結構，並使用所接收 Row 參數所指向之MIB_UNICASTIPADDRESS_ROW結構中的 Address、InterfaceLuid 和 InterfaceIndex 成員加以初始化。這個新初始化 MIB_UNICASTIPADDRESS_ROW 結構的指標應該傳遞至 GetUnicastIpAddressEntry 函式，以擷取已變更之單播 IP 位址的完整資訊。

回呼指示中使用的 Row 參數所指向的記憶體是由作業系統所管理。接收通知的應用程式不應該嘗試釋放 Row 參數所指向的記憶體。

呼叫 NotifyUnicastIpAddressChange 函式以註冊變更通知之後，這些通知會繼續傳送，直到應用程式取消註冊變更通知或應用程式終止為止。如果應用程式終止，系統會自動取消註冊變更通知的任何註冊。仍然建議應用程式在終止之前明確取消註冊變更通知。

如果系統關機或重新啟動，變更通知的任何註冊都不會保存。

若要取消註冊變更通知，請呼叫 CancelMibChangeNotify2 函式，並傳遞 NotifyUnicastIpAddressChange 所傳回的 NotificationHandle 參數。

應用程式無法從線程的內容呼叫 CancelMibChangeNotify2 函式，該線程目前正在執行相同 NotificationHandle 參數的通知回呼函式。否則，執行該回呼的線程會導致死結。因此 ，CancelMibChangeNotify2 函式不得直接呼叫為通知回呼例程的一部分。在較普遍的情況下，執行 CancelMibChangeNotify2 函式的線程無法擁有執行通知回呼作業的線程會等候的資源，因為它會導致類似的死結。 CancelMibChangeNotify2 函式應該從接收通知回呼的線程沒有相依性的不同線程呼叫。

規格需求

需求	值
最低支援的用戶端	Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	netioapi.h (包含 Iphlpapi.h)
程式庫	Iphlpapi.lib
Dll	Iphlpapi.dll