notifyStableUnicastIpAddressTable 函式 (netioapi.h)
NotifyStableUnicastIpAddressTable 函式會擷取本機電腦上的穩定單播 IP 位址表。
語法
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyStableUnicastIpAddressTable(
[in] ADDRESS_FAMILY Family,
[in, out] PMIB_UNICASTIPADDRESS_TABLE *Table,
[in] PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
[in] PVOID CallerContext,
[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。
[in, out] Table
MIB_UNICASTIPADDRESS_TABLE 結構的指標。 當 NotifyStableUnicastIpAddressTable 成功時，此參數會傳回本機電腦上的穩定單播 IP 位址數據表。
當 NotifyStableUnicastIpAddressTable 傳回 ERROR_IO_PENDING 指出 I/O 要求擱置中時，穩定單播 IP 位址表會傳回 CallerCallback 參數中的函式。
[in] CallerCallback
使用穩定單播IP位址表呼叫之函式的指標。 如果 NotifyStableUnicastIpAddressTable 傳回 ERROR_IO_PENDING，則會叫用此函式，指出 I/O 要求擱置中。
[in] CallerContext
當穩定單播IP位址表si可用時，傳遞給 CallerCallback 參數中指定的回呼函式的用戶內容。
[in, out] NotificationHandle
用來傳回句柄的指標，可用來取消要求以擷取穩定的單播IP位址表。 如果 NotifyStableUnicastIpAddressTable 的傳回值 ERROR_IO_PENDING 表示 I/O 要求擱置中，則會傳回這個參數。
傳回值
如果函式立即成功，傳回值會NO_ERROR，而穩定單播IP數據表則會在 Table 參數中傳回。
如果 I/O 要求擱置中，當 I/O 要求使用穩定單播 IP 位址表完成時，呼叫 CallerCallback 參數所指向的函式會傳回ERROR_IO_PENDING。
如果函式失敗，傳回值就是下列其中一個錯誤碼。
| 傳回碼 | Description |
|---|---|
|
發生內部錯誤，其中遇到無效的句柄。 |
|
無效的參數已傳遞至 函式。 如果 Table 參數是 NULL 指標、 NotificationHandle 參數是 NULL 指標，或是 Family 參數不是 AF_INET、 AF_INET6或 AF_UNSPEC，就會傳回此錯誤。 |
|
記憶體不足。 |
|
使用 FormatMessage 取得傳回錯誤的訊息字串。 |
備註
NotifyStableUnicastIpAddressTable 函式是在 Windows Vista 和更新版本上定義。
如果 NotifyStableUnicastIpAddressTable 函式立即成功，則會NO_ERROR傳回值，而穩定單播 IP 數據表則會在 Table 參數中傳回。 當不再需要MIB_UNICASTIPADDRESS_TABLE資訊時，呼叫的應用程式應該使用FreeMibTable函數釋放 Table 參數所指向的記憶體。
除了隨選撥號位址以外的所有單播IP位址，只有在它們處於慣用狀態時，才會被視為穩定。 如果是一般單播IP位址專案，這會對應至ip位址設定為IpDadStatePreferred之ip位址MIB_UNICASTIPADDRESS_ROW的 DadState 成員。 每個隨選撥號位址都會定義自己的穩定性計量。 此函式目前唯一考慮的隨選撥號位址是本機電腦上的 Teredo 用戶端所使用的單播 IP 位址。
Family 參數必須設定為 AF_INET、AF_INET6 或 AF_UNSPEC。
當 NotifyStableUnicastIpAddressTable 成功並傳回NO_ERROR時， Table 參數會傳回本機電腦上的穩定單播 IP 位址數據表。
當 NotifyStableUnicastIpAddressTable 傳回 ERROR_IO_PENDING 指出 I/O 要求擱置中時，穩定單播 IP 位址表會傳回 CallerCallback 參數中的函式。
NotifyStableUnicastIpAddressTable 函式主要是由使用 Teredo 用戶端的應用程式使用。
如果 Teredo 所使用的單播 IP 位址可在本機電腦上使用，但無法處於穩定 (限定) 狀態， NotifyStableUnicastIpAddressTable 會傳回 ERROR_IO_PENDING，而穩定單播 IP 位址表最終會藉由呼叫 CallerCallback 參數中的 函式傳回。 如果 Teredo 位址無法使用或處於穩定狀態，而其他單播 IP 位址處於穩定狀態，則永遠不會叫用 CallerCallback 參數中的函式。
CallerCallback 參數中指定的回調函式應該定義為 VOID 類型的函式。 傳遞至回調函式的參數包括下列各項：
| 參數 | Description |
|---|---|
| IN PVOID CallerContext | 註冊通知時傳遞至 NotifyStableUnicastIpAddressTable 函式的 CallerContext 參數。 |
| IN PMIB_UNICASTIPADDRESS_TABLE AddressTable | MIB_UNICASTIPADDRESS_TABLE指標，其中包含本機計算機上的穩定單播IP位址表。 |
CallerCallback 參數中指定的回調函式必須與呼叫 NotifyStableUnicastIpAddressTable 函式的應用程式相同進程中實作。 如果回呼函式位於個別的 DLL 中，則應該先載入 DLL，再呼叫 NotifyStableUnicastIpAddressTable 函式來註冊變更通知。
呼叫指示中使用的 AddressTable 參數所指向的記憶體是由作業系統所配置。 當不再需要MIB_UNICASTIPADDRESS_TABLE資訊時，接收通知的應用程式應該使用FreeMibTable函式釋放AddressTable 參數所指向的記憶體。
呼叫 NotifyStableUnicastIpAddressTable 函式以註冊變更通知之後，這些通知會繼續傳送，直到應用程式取消註冊變更通知或應用程式終止為止。 如果應用程式終止，系統會自動取消註冊變更通知的任何註冊。 仍然建議應用程式在終止之前明確取消註冊任何變更通知。
如果系統關機或重新啟動，變更通知的任何註冊都不會保存。
若要取消註冊變更通知，請呼叫 CancelMibChangeNotify2 函式，並傳遞 NotifyStableUnicastIpAddressTable 所傳回的 NotificationHandle 參數。
應用程式無法從線程的內容呼叫 CancelMibChangeNotify2 函式，該線程目前正在執行相同 NotificationHandle 參數的通知回呼函式。 否則，執行該回呼的線程會導致死結。 因此 ，CancelMibChangeNotify2 函式不得直接呼叫為通知回呼例程的一部分。 在較普遍的情況下，執行 CancelMibChangeNotify2 函式的線程無法擁有執行通知回呼作業的線程會等候的資源，因為它會導致類似的死結。 CancelMibChangeNotify2 函式應該從接收通知回呼的線程沒有相依性的不同線程呼叫。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | netioapi.h (包含 Iphlpapi.h) |
| 程式庫 | Iphlpapi.lib |
| Dll | Iphlpapi.dll |