Icmp6SendEcho2 函式（icmpapi.h）

Icmp6SendEcho2 函式會發送 IPv6 ICMPv6 回波請求，並會立即回傳（若事件或 ApcRoutine 非 NULL）或在指定的逾時後返回。ReplyBuffer 包含 IPv6 ICMPv6 迴波回應（若有的話）。

語法

IPHLPAPI_DLL_LINKAGE DWORD Icmp6SendEcho2(
  [in]           HANDLE                 IcmpHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [in]           sockaddr_in6           *SourceAddress,
  [in]           sockaddr_in6           *DestinationAddress,
  [in]           LPVOID                 RequestData,
  [in]           WORD                   RequestSize,
  [in, optional] PIP_OPTION_INFORMATION RequestOptions,
  [out]          LPVOID                 ReplyBuffer,
  [in]           DWORD                  ReplySize,
  [in]           DWORD                  Timeout
);

參數

[in] IcmpHandle

Icmp6CreateFile 回傳的開放帳號。

[in, optional] Event

每當 ICMPv6 回應抵達時，該事件會被通知。若指定此參數，則需有效事件物件的句柄。使用 CreateEvent 或 CreateEventEx 函式來建立這個事件物件。

欲了解更多事件使用資訊，請參見事件物件。

[in, optional] ApcRoutine

當呼叫執行緒處於可警示執行緒且收到 ICMPv6 回應時所呼叫的例程。在 Windows Vista 及以後版本中，必須定義 PIO_APC_ROUTINE_DEFINED 來強制此參數的資料型態為 PIO_APC_ROUTINE ，而非 FARPROC。

在 Windows Server 2003 和 Windows XP 中，必須不定義 PIO_APC_ROUTINE_DEFINED 以強制此參數的資料型態為 FARPROC。

[in, optional] ApcContext

每當 ICMPv6 回應抵達或發生錯誤時，會由 ApcRoutine 參數指定，傳遞給回撥例程的一個可選參數。

[in] SourceAddress

這是 IPv6 來源位址，用來發出 echo 請求，形式為 sockaddr 結構。

[in] DestinationAddress

Echo 請求的 IPv6 目的位址，以 sockaddr 結構形式呈現。

[in] RequestData

一個指向緩衝區的指標，該緩衝區包含要傳送請求的資料。

[in] RequestSize

請求資料緩衝區的大小（以位元組為單位）由 RequestData 參數指向。

[in, optional] RequestOptions

一個指向請求 IPv6 標頭選項的指標，以 IP_OPTION_INFORMATION 結構的形式呈現。在 64 位元平台上，這個參數呈現為 IP_OPTION_INFORMATION32 結構的形式。

若不需要指定 IP 標頭選項，該參數可能是 NULL。

便條在 Windows Server 2003 和 Windows XP 中， RequestOptions 參數非可選且不得為 NULL，且僅使用 Ttl 與 Flags 成員。

[out] ReplyBuffer

一個指向緩衝區的指標，用來儲存對請求的回應。回傳時，緩衝區包含 ICMPV6_ECHO_REPLY 結構，接著是來自 ICMPv6 回聲回應資料的訊息主體。緩衝區必須足夠大，能容納至少一個 ICMPV6_ECHO_REPLY 結構，以及 RequestSize 參數中指定的資料位元組數。此緩衝區也應足夠大，可容納 8 個位元組的資料（相當於 ICMP 錯誤訊息大小）及 IO_STATUS_BLOCK 結構空間。

[in] ReplySize

回應緩衝區的大小（以位元組計）由 ReplyBuffer 參數所指向。此緩衝區應足夠大，至少能容納一個 ICMPV6_ECHO_REPLY 結構加上 RequestSize 位元組的資料。此緩衝區也應足夠大，可容納 8 個位元組的資料（相當於 ICMP 錯誤訊息大小）及 IO_STATUS_BLOCK 結構空間。

[in] Timeout

等待回覆的時間，以毫秒計。此參數僅在同步呼叫 Icmp6SendEcho2 函式時使用。因此，如果 APCRoutine 或 Event 參數不是 NULL，則不會使用此參數。

返回值

同步呼叫時，回傳收到並儲存在 ReplyBuffer 中的回覆數量。

非同步呼叫時，表示操作正在進行中，會回傳 ERROR_IO_PENDING。你可以在事件參數指定的事件發出訊號，或 ApcRoutine 參數中的回調函式被呼叫時，取得回覆次數的結果。

如果（同步或非同步）回覆次數為零，則擴充錯誤資訊請呼叫 GetLastError。

若函式失敗， GetLastError 回傳的擴展錯誤碼可為以下其中之一值。

回傳碼	Description
ERROR_CALL_NOT_IMPLEMENTED	此功能在本系統中不支援。
ERROR_INSUFFICIENT_BUFFER	傳送給系統呼叫的資料區域太小。若 ReplySize 參數顯示 ReplyBuffer 參數指向的緩衝區過小，則會回傳此錯誤。
ERROR_INVALID_PARAMETER	其中一個參數無效。若 IcmpHandle 參數包含無效的 handle ，則會回傳此錯誤。
ERROR_IO_PENDING	作業正在進行中。此值由成功非同步呼叫 Icmp6SendEcho2 回傳，並非錯誤的指標。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足以處理此指令。
ERROR_NOT_SUPPORTED	不支援此要求。若本地電腦上沒有 IPv6 堆疊，則會回傳此錯誤。
IP_BUF_TOO_SMALL	ReplySize 參數中指定的 ReplyBuffer 大小過小。
其他	使用 FormatMessage 來取得傳回錯誤的訊息字串。

備註

若 APCRoutine 與 Event 參數為 NULL，則同步呼叫 Icmp6SendEcho2 函式。同步呼叫時，回傳值包含在等待逾時參數指定時間後，回覆緩衝區中收到並儲存的回覆數量。如果回傳值為零，請呼叫 GetLastError 以獲取擴充的錯誤資訊。

當指定 ApcRoutine 或 Event 參數時，Icmp6SendEcho2 函式會以非同步方式呼叫。非同步呼叫時，必須啟用 ReplyBuffer 和 ReplySize 參數才能接受回應。 ICMP 回應資料會被複製到提供的 ReplyBuffer ，應用程式會被通知（指定事件參數時）或呼叫回調函式（指定 ApcRoutine 參數時）。應用程式必須使用 Icmp6ParseReplylies 函式解析 ReplyBuffer 參數所指向的資料。

若指定事件參數，則非同步呼叫 Icmp6SendEcho2 函式。事件參數中指定的事件會在 ICMPv6 回應時被標示。使用 CreateEvent 函式來建立這個事件物件。

若指定 ApcRoutine 參數，則非同步呼叫 Icmp6SendEcho2 函式。 ApcRoutine 參數應指向使用者自訂的回調函式。每當收到 ICMPv6 回應時，就會呼叫 ApcRoutine 參數中指定的回調函式。 ApcRoutine 參數中指定的回調函式呼叫會被序列化。

若同時指定事件與 ApcRoutine 參數，則每當 ICMPv6 回應抵達時，事件參數中指定的事件會被警告，但忽略 ApcRoutine 參數中指定的回調函式。

在 Windows Vista 及之後版本中，任何使用 ApcRoutine 參數非同步呼叫 Icmp6SendEcho2 函式的應用程式，必須定義PIO_APC_ROUTINE_DEFINED強制 ApcRoutine 參數的資料型態為 PIO_APC_ROUTINE，而非 FARPROC。

注意，PIO_APC_ROUTINE_DEFINED 必須先定義，才能包含 Icmpapi.h 標頭檔。

在 Windows Vista 及之後版本中， ApcRoutine 指向的回調函式必須定義為 VOID 型別的函式，語法如下：

typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
    IN PVOID ApcContext,
    IN PIO_STATUS_BLOCK IoStatusBlock,
    IN ULONG Reserved
    );

在 Windows Vista 及之後版本中，傳給回撥函式的參數包括以下幾項：

參數	Description
在 PVOID ApcContext 中	ApcContext 參數傳遞給 Icmp6SendEcho2 函式。應用程式可利用此參數識別回調函式所回應的 Icmp6SendEcho2 請求。
在 PIO_STATUS_BLOCK IoStatusBlock 中	指向 IO_STATUS_BLOCK。此變數包含最終完成狀態及操作資訊。回覆中實際收到的位元組數會回傳在IO_STATUS_BLOCK結構的資訊成員中。 IO_STATUS_BLOCK結構定義於 Wdm.h 標頭檔案中。
烏龍保留	此參數是保留的。

在 Windows Server 2003 與 Windows XP 中，任何使用 ApcRoutine 參數非同步呼叫 Icmp6SendEcho2 函式的應用程式，都不得定義PIO_APC_ROUTINE_DEFINED強制 ApcRoutine 參數的資料型別為 FARPROC，而非 PIO_APC_ROUTINE。

在 Windows Server 2003 與 Windows XP 中， ApcRoutine 所指向的回調函式必須定義為 VOID 型別的函式，語法如下：

typedef
VOID WINAPI
(*FARPROC) (
    IN PVOID ApcContext,
    );

在 Windows Server 2003 和 Windows XP 中，傳給回呼函式的參數包括以下內容：

參數	Description
在 PVOID ApcContext 中	ApcContext 參數傳遞給 Icmp6SendEcho2 函式。應用程式可利用此參數識別回調函式所回應的 Icmp6SendEcho2 請求。

ApcRoutine 參數中指定的回調函式必須與呼叫 Icmp6SendEcho2 函式的應用程式在同一程序中實作。如果回調函式在獨立的 DLL 中，那麼 DLL 應該先載入，再呼叫 Icmp6SendEcho2 函式。

IPv4 則使用 IcmpCreateFile、 IcmpSendEcho、 IcmpSendEcho2、 IcmpSendEcho2 及 IcmpParseResponse 函式。

請注意， Iphlpapi.h 標頭檔案的 include 指令必須放在 Icmpapi.h 標頭檔案之前。

需求

Requirement	價值觀
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
Header	icmpapi.h
Library	伊菲爾帕皮.lib
DLL	Iphlpapi.dll