notifyRouteChange2 函式 (netioapi.h)

發行項
08/25/2023

NotifyRouteChange2函式會註冊，以通知本機電腦上的 IP 路由專案變更。

語法

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyRouteChange2(
  [in]      ADDRESS_FAMILY             AddressFamily,
  [in]      PIPFORWARD_CHANGE_CALLBACK Callback,
  [in]      PVOID                      CallerContext,
  [in]      BOOLEAN                    InitialNotification,
  [in, out] HANDLE                     *NotificationHandle
);

參數

[in] AddressFamily

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

位址系列的可能值會列在 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

收到 IP 路由通知時，傳遞至 Callback 參數中指定的回呼函式的使用者內容。

[in] InitialNotification

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

[in, out] NotificationHandle

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

傳回值

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

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

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

備註

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

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

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

參數	描述
IN PVOID CallerCoNtext	註冊通知時傳遞至NotifyRouteChange2函式的CallerCoNtext參數。
IN PMIB_IPFORWARD_ROW2 列選擇性	已變更之 IP 路由專案的 MIB_IPFORWARD_ROW2 專案指標。當將NotificationType參數中傳遞至回呼函式的MIB_NOTIFICATION_TYPE值設定為MibInitialNotification時，這個參數是Null指標。只有在註冊通知時，傳遞至NotifyRouteChange2的InitialNotification參數設定為TRUE時，才會發生此情況。
IN MIB_NOTIFICATION_TYPE NotificationType	通知類型。這個成員可以是Netioapi.h標頭檔中所定義MIB_NOTIFICATION_TYPE列舉類型的其中一個值。

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

當發生變更且Row參數不是Null時收到回呼函式時，在Row參數中傳遞之MIB_IPFORWARD_ROW2結構的指標會包含不完整的資料。 MIB_IPFORWARD_ROW2結構中傳回的資訊只是應用程式可以呼叫GetIpForwardEntry2函式的足夠資訊，以查詢已變更之 IP 路由的完整資訊。收到回呼函式時，應用程式應該配置MIB_IPFORWARD_ROW2結構，並使用所接收Row參數所指向之MIB_IPFORWARD_ROW2結構中的DestinationPrefix、NextHop、InterfaceLuid和InterfaceIndex成員加以初始化。這個新初始化 MIB_IPFORWARD_ROW2 結構的指標應該傳遞至 GetIpForwardEntry2 函式，以擷取已變更之 IP 路由的完整資訊。

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

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

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

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

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

需求


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