NotifyAddrChange 函式 (iphlpapi.h)

發行項
08/24/2023

NotifyAddrChange函式會在將 IPv4 位址對應至介面的資料表中發生變更時，將通知傳送給呼叫端。

語法

IPHLPAPI_DLL_LINKAGE DWORD NotifyAddrChange(
  [out] PHANDLE      Handle,
  [in]  LPOVERLAPPED overlapped
);

參數

[out] Handle

HANDLE變數的指標，接收檔案控制代碼以供後續呼叫GetOverlappedResult 函式使用。

警告請勿關閉此控制碼，而且不要將它與完成埠產生關聯。

[in] overlapped

重迭結構的指標，會通知呼叫者資料表中將 IP 位址對應至介面的任何變更。

傳回值

如果函式成功，如果呼叫端指定Handle和重迭參數的Null，則傳回值會NO_ERROR。如果呼叫端指定非Null 參數，則成功傳回值會ERROR_IO_PENDING。

如果函式失敗，請使用 FormatMessage 取得傳回錯誤的訊息字串。

傳回碼	描述
ERROR_CANCELLED	正在取消註冊內容，因此會立即取消呼叫。
ERROR_INVALID_PARAMETER	傳遞了一個無效的參數。如果 Handle 和重迭參數都不是 Null，但呼叫進程無法寫入輸入參數指定的記憶體，就會傳回此錯誤。如果用戶端已經提出變更通知要求，也會傳回此錯誤，因此此重複的要求將會失敗。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足，無法完成作業。
ERROR_NOT_SUPPORTED	這個錯誤會在 Windows 版本傳回，其中不支援此函式，例如 Windows 98/95 和 Windows NT 4.0。

備註

此
NotifyAddrChange 函式可以透過兩種方式呼叫：

同步方法
非同步方法

如果呼叫端指定Handle和重迭參數的Null，則 NotifyAddrChange的呼叫是同步的，而且會封鎖直到發生 IP 位址變更為止。在此情況下，如果發生變更， NotifyAddrChange 函式會完成以指出已發生變更。

如果以同步方式呼叫 NotifyAddrChange 函式，則會在下一個 IPv4 位址變更時傳送通知，直到應用程式終止為止。

如果呼叫端指定控制碼變數和 OVERLAPPED 結構， 則 NotifyAddrChange 函數呼叫是非同步，而且呼叫端可以使用 RETURNED 結構的傳回控制碼，以使用 GetOverlappedResult 函式接收 IPv4 位址變更的非同步通知。如需使用控制碼和 OVERLAPPED 結構來接收通知的相關資訊，請參閱下列主題：

CancelIPChangeNotify函式會取消 IPv4 位址的通知，並路由傳送先前呼叫NotifyAddrChange或NotifyRouteChange函式的要求變更。

一旦應用程式收到變更的通知，應用程式就可以呼叫 GetIpAddrTable 或 GetAdaptersAddresses 函式來擷取 IPv4 位址的資料表，以判斷已變更的專案。如果應用程式收到通知，而且需要通知下一次變更，則必須再次呼叫 NotifyAddrChange 函式。

如果以非同步方式呼叫 NotifyAddrChange 函式，則會在下一個 IPv4 位址變更時傳送通知，直到應用程式呼叫 CancelIPChangeNotify 函式或應用程式終止為止。如果應用程式終止，系統會自動取消通知的註冊。仍然建議應用程式在終止之前明確取消任何通知。

任何通知的註冊都不會在系統關閉或重新開機之間保存。

在 Windows Vista 和更新版本上， NotifyIpInterfaceChange 函式可用來註冊，以通知本機電腦上的 IPv4 和 IPv6 介面變更。

範例

下列範例會等候將 IP 位址對應至介面的資料表中發生變更。

#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <windows.h>

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

void main()
{
  OVERLAPPED overlap;
  DWORD ret;
    
  HANDLE hand = NULL;
  overlap.hEvent = WSACreateEvent();

  ret = NotifyAddrChange(&hand, &overlap);

  if (ret != NO_ERROR)
  {
    if (WSAGetLastError() != WSA_IO_PENDING)
    {
      printf("NotifyAddrChange error...%d\n", WSAGetLastError());            
      return;
    }
  }

  if ( WaitForSingleObject(overlap.hEvent, INFINITE) == WAIT_OBJECT_0 )
    printf("IP Address table changed..\n");
}

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	iphlpapi.h
程式庫	Iphlpapi.lib
Dll	Iphlpapi.dll