IcmpSendEcho2Ex 函式 (icmpapi.h)

發行項
08/24/2023

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 傳回的擴充錯誤碼可以是下列其中一個值。

傳回碼	描述
ERROR_INVALID_PARAMETER	不正確參數已傳遞至函式。如果 IcmpHandle 參數包含不正確控制碼，就會傳回此錯誤。如果 ReplySize 參數指定的值小於 ICMP_ECHO_REPLY 結構的大小，也可以傳回此錯誤。
ERROR_IO_PENDING	作業正在進行中。這個值是由 IcmpSendEcho2Ex 的成功非同步呼叫所傳回，而且不是錯誤的指示。
ERROR_NOT_ENOUGH_MEMORY	可用的記憶體不足，無法完成作業。
ERROR_NOT_SUPPORTED	不支援此要求。如果本機電腦上沒有 IPv4 堆疊，則會傳回此錯誤。
IP_BUF_TOO_SMALL	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。

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

ApcRoutine所指向的回呼函式必須定義為VOID類型的函式，其語法如下：

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

傳遞至回呼函式的參數包括下列各項：

參數	描述
IN PVOID ApcCoNtext	傳遞至IcmpSendEcho2Ex 函式的ApcCoNtext參數。應用程式可以使用此參數來識別回呼函式所回應的 IcmpSendEcho2Ex 要求。
IN PIO_STATUS_BLOCK IoStatusBlock	IO_STATUS_BLOCK的指標。此變數包含最終完成狀態和作業的相關資訊。在IO_STATUS_BLOCK結構的資訊成員中，會傳回回複中實際收到的位元組數目。 IO_STATUS_BLOCK結構定義于Wdm.h標頭檔中。
在 ULONG 中保留	此參數已保留備用。

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