IcmpSendEcho2Ex 函式 (icmpapi.h)
IcmpSendEcho2Ex 函式會傳送 IPv4 ICMP 回應要求，如果Event或ApcRoutine為非Null) ，或是在指定的逾時之後傳回，則會立即傳回 (。ReplyBuffer包含 ICMP 回應，如果有的話。
語法
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2Ex(
[in] HANDLE IcmpHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[in] IPAddr SourceAddress,
[in] IPAddr DestinationAddress,
[in] LPVOID RequestData,
[in] WORD RequestSize,
[in, optional] PIP_OPTION_INFORMATION RequestOptions,
[out] LPVOID ReplyBuffer,
[in] DWORD ReplySize,
[in] DWORD Timeout
);
參數
[in] IcmpHandle
ICMPCreateFile函式傳回的開啟控制碼。
[in, optional] Event
每當 ICMP 回應送達時，要發出訊號的事件。 如果指定此參數，則需要有效事件物件的控制碼。 使用 CreateEvent 或 CreateEventEx函 式來建立此事件物件。
如需使用事件的詳細資訊，請參閱 事件物件。
[in, optional] ApcRoutine
當呼叫執行緒位於可警示執行緒且 ICMP 回復送達時所呼叫的常式。 PIO_APC_ROUTINE_DEFINED 必須定義，才能強制此參數的資料類型 PIO_APC_ROUTINE ，而不是 FARPROC。
[in, optional] ApcContext
每當 ICMP 回應送達或發生錯誤時，傳遞至 ApcRoutine 參數中指定的回呼常式的選擇性參數。
[in] SourceAddress
要發出回應要求的 IPv4 來源位址。 此位址的格式為 IPAddr 結構。
[in] DestinationAddress
回應要求的 IPv4 目的地位址。 此位址的格式為 IPAddr 結構。
[in] RequestData
緩衝區的指標，其中包含要求中要傳送的資料。
[in] RequestSize
RequestData參數所指向之要求資料緩衝區的大小，以位元組為單位。
[in, optional] RequestOptions
要求 IP 標頭選項的指標，格式為 IP_OPTION_INFORMATION 結構。 在 64 位平臺上，此參數的格式為 IP_OPTION_INFORMATION32 結構。
如果不需要指定任何 IP 標頭選項，此參數可能是 Null 。
[out] ReplyBuffer
緩衝區的指標，用來保存對要求的任何回復。 傳回時，緩衝區包含 ICMP_ECHO_REPLY 結構的陣列，後面接著選項和資料。 緩衝區必須夠大，才能保存至少一 個ICMP_ECHO_REPLY 結構加上 RequestSize 位元組的資料。
此緩衝區也應該夠大，以容納 8 個以上的資料位元組， (ICMP 錯誤訊息的大小) 加上 IO_STATUS_BLOCK 結構的空間。
[in] ReplySize
回復緩衝區的配置大小，以位元組為單位。 緩衝區應該夠大，以容納至少一 個ICMP_ECHO_REPLY 結構加上 RequestSize 位元組的資料。
此緩衝區也應該夠大，以容納 8 個以上的資料位元組， (ICMP 錯誤訊息的大小) 加上 IO_STATUS_BLOCK 結構的空間。
[in] Timeout
等候回復的時間，以毫秒為單位。
傳回值
以同步方式呼叫時， IcmpSendEcho2Ex 函 式會傳回接收並儲存在 ReplyBuffer中的回復數目。 如果傳回值為零，請呼叫 GetLastError 以取得擴充的錯誤資訊。
以非同步方式呼叫時， IcmpSendEcho2Ex 函 式會傳回ERROR_IO_PENDING，表示作業正在進行中。 呼叫ApcRoutine參數中的事件訊號或回呼函式時，稍後可以擷取結果。
如果傳回值為零，請呼叫 GetLastError 以取得擴充的錯誤資訊。
如果函式失敗， GetLastError 傳回的擴充錯誤碼可以是下列其中一個值。
| 傳回碼 | 描述 |
|---|---|
|
不正確參數已傳遞至 函式。 如果 IcmpHandle 參數包含不正確控制碼，就會傳回此錯誤。 如果 ReplySize 參數指定的值小於 ICMP_ECHO_REPLY 結構的大小，也可以傳回此錯誤。 |
|
作業正在進行中。 這個值是由 IcmpSendEcho2Ex 的成功非同步呼叫所傳回，而且不是錯誤的指示。 |
|
可用的記憶體不足，無法完成作業。 |
|
不支援此要求。 如果本機電腦上沒有 IPv4 堆疊，則會傳回此錯誤。 |
|
ReplySize參數中指定的ReplyBuffer大小太小。 |
|
使用 FormatMessage 取得傳回錯誤的訊息字串。 |
備註
IcmpSendEcho2Ex 函式可在 Windows Server 2008 和更新版本上使用。
IcmpSendEcho2Ex 函式是IcmpSendEcho2函式的增強版本，可讓使用者指定要發出 ICMP 要求的 IPv4 來源位址。 當電腦有多個網路介面時， IcmpSendEcho2Ex 函 式很有用。
如果ApcRoutine或Event參數為Null，IcmpSendEcho2Ex 函式會以同步方式呼叫。 以同步方式呼叫時，傳回值會包含在等候Timeout參數中指定的時間之後，接收並儲存在ReplyBuffer中的回復數目。 如果傳回值為零，請呼叫 GetLastError 以取得擴充的錯誤資訊。
指定ApcRoutine或Event參數時，會以非同步方式呼叫IcmpSendEcho2Ex函式。 以非同步方式呼叫時，需要 ReplyBuffer 和 ReplySize 參數才能接受回應。 ICMP 回應資料會複製到提供的 ReplyBuffer ，並在指定 Event 參數) 或 (指定 ApcRoutine 參數時呼叫回呼函式 () 發出訊號。 應用程式必須使用IcmpParseReplies函式來剖析ReplyBuffer參數所指向的資料。
如果指定 Event 參數，則會以非同步方式呼叫 IcmpSendEcho2Ex 函 式。 每當 ICMP 回應送達時， 事件 參數中指定的事件就會發出訊號。 使用 CreateEvent 函式來建立此事件物件。
如果指定 了 ApcRoutine 參數，則會以非同步方式呼叫 IcmpSendEcho2Ex 函 式。 ApcRoutine參數應該指向使用者定義的回呼函式。 每當 ICMP 回應送達時，就會呼叫 ApcRoutine 參數中指定的回呼函式。 ApcRoutine參數中指定的回呼函式調用會序列化。
如果同時指定 Event 和 ApcRoutine 參數，每當 ICMP 回應送達時， 就會發出 Event 參數中指定的事件，但會忽略 ApcRoutine 參數中指定的回呼函式。
任何使用ApcRoutine參數非同步呼叫IcmpSendEcho2Ex 函式的應用程式都必須定義PIO_APC_ROUTINE_DEFINED，以強制ApcRoutine參數的資料類型PIO_APC_ROUTINE而非FARPROC。
ApcRoutine所指向的回呼函式必須定義為VOID類型的函式，其語法如下：
typedef
VOID WINAPI
(*PIO_APC_ROUTINE) (
IN PVOID ApcContext,
IN PIO_STATUS_BLOCK IoStatusBlock,
IN ULONG Reserved
);
傳遞至回呼函式的參數包括下列各項：
ApcRoutine參數中指定的回呼函式必須與呼叫IcmpSendEcho2Ex 函式的應用程式在相同的進程中實作。 如果回呼函式位於不同的 DLL 中，則應該先載入 DLL，再呼叫 IcmpSendEcho2Ex 函 式。
針對 IPv6，請使用 Icmp6CreateFile、 Icmp6SendEcho2和 Icmp6ParseReplies 函式。
請注意， Iphlpapi.h 標頭檔的 include 指示詞必須放在 Icmpapi.h 標頭檔之前。
需求
| 最低支援的用戶端 | Windows Vista SP1 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | icmpapi.h |
| 程式庫 | Iphlpapi.lib |
| Dll | Iphlpapi.dll |