icmpSendEcho 函式 (icmpapi.h)
IcmpSendEcho函式會傳送 IPv4 ICMP 回應要求，並傳回任何回應回應回復。 當逾時已過期或已填滿回復緩衝區時，呼叫會傳回。
語法
IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho(
[in] HANDLE IcmpHandle,
[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] 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 位元組的資料。
[in] ReplySize
回復緩衝區的配置大小，以位元組為單位。 緩衝區的大小應該足以保存至少一 個ICMP_ECHO_REPLY 結構加上 RequestSize 位元組的資料。
此緩衝區也應該夠大，以容納 8 個以上的資料位元組， (ICMP 錯誤訊息的大小) 。
[in] Timeout
等候回復的時間，以毫秒為單位。
傳回值
IcmpSendEcho函式會傳回儲存在ReplyBuffer中的ICMP_ECHO_REPLY結構數目。 每個回復的狀態都包含在 結構中。 如果傳回值為零，請呼叫 GetLastError 以取得其他錯誤資訊。
如果函式失敗， GetLastError 傳回的擴充錯誤碼可以是下列其中一個值。
| 傳回碼 | 描述 |
|---|---|
|
傳遞至系統呼叫的資料區域太小。 如果 ReplySize 參數指出 ReplyBuffer 參數所指向的緩衝區太小，就會傳回此錯誤。 |
|
不正確參數已傳遞至 函式。 如果 IcmpHandle 參數包含不正確控制碼，就會傳回此錯誤。 如果 ReplySize 參數指定的值小於 ICMP_ECHO_REPLY 結構的大小，也可以傳回此錯誤。 |
|
可用的記憶體不足，無法完成作業。 |
|
不支援此要求。 如果本機電腦上沒有 IPv4 堆疊，就會傳回此錯誤。 |
|
ReplySize參數中指定的ReplyBuffer大小太小。 |
|
使用 FormatMessage 取得傳回錯誤的訊息字串。 |
備註
IcmpSendEcho函式會將 ICMP 回應要求傳送至指定的位址，並傳回在ReplyBuffer中接收並儲存的回復數目。 IcmpSendEcho函式是同步函式，並在等候逾時參數中指定的時間之後傳迴響應。 如果傳回值為零，請呼叫 GetLastError 以取得擴充錯誤資訊。
IcmpSendEcho2和IcmpSendEcho2Ex函式是支援非同步作業的IcmpSendEcho增強版本。 IcmpSendEcho2Ex函式也允許指定來源 IP 位址。 此功能在具有多個網路介面的電腦上很有用。
針對 IPv6，請使用 Icmp6CreateFile、 Icmp6SendEcho2和 Icmp6ParseReplies 函式 。
IcmpSendEcho函式是從 Windows 2000 上的Icmp.dll匯出。 IcmpSendEcho函式是從 Windows XP 和更新版本的Iphlpapi.dll匯出。 不建議使用此函式進行 Windows 版本檢查。 需要跨 Windows 2000、Windows XP、Windows Server 2003 和更新 Windows 版本之此函式可攜性的應用程式不應該以靜態方式連結至 Icmp.lib 或 Iphlpapi.lib 檔案。 相反地，應用程式應該檢查Iphlpapi.dll中是否有IcmpSendEcho，並呼叫LoadLibrary和GetProcAddress。 失敗，應用程式應該檢查Icmp.dll中是否有IcmpSendEcho，並呼叫LoadLibrary和GetProcAddress。
請注意， Iphlpapi.h 標頭檔的 include 指示詞必須放在 Icmpapi.h 標頭檔之前。
範例
下列範例會將 ICMP 回應要求傳送至命令列上指定的 IP 位址，並列印從第一個回應接收的資訊。
#include <winsock2.h>
#include <iphlpapi.h>
#include <icmpapi.h>
#include <stdio.h>
#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")
int __cdecl main(int argc, char **argv) {
// Declare and initialize variables
HANDLE hIcmpFile;
unsigned long ipaddr = INADDR_NONE;
DWORD dwRetVal = 0;
char SendData[32] = "Data Buffer";
LPVOID ReplyBuffer = NULL;
DWORD ReplySize = 0;
// Validate the parameters
if (argc != 2) {
printf("usage: %s IP address\n", argv[0]);
return 1;
}
ipaddr = inet_addr(argv[1]);
if (ipaddr == INADDR_NONE) {
printf("usage: %s IP address\n", argv[0]);
return 1;
}
hIcmpFile = IcmpCreateFile();
if (hIcmpFile == INVALID_HANDLE_VALUE) {
printf("\tUnable to open handle.\n");
printf("IcmpCreatefile returned error: %ld\n", GetLastError() );
return 1;
}
ReplySize = sizeof(ICMP_ECHO_REPLY) + sizeof(SendData);
ReplyBuffer = (VOID*) malloc(ReplySize);
if (ReplyBuffer == NULL) {
printf("\tUnable to allocate memory\n");
return 1;
}
dwRetVal = IcmpSendEcho(hIcmpFile, ipaddr, SendData, sizeof(SendData),
NULL, ReplyBuffer, ReplySize, 1000);
if (dwRetVal != 0) {
PICMP_ECHO_REPLY pEchoReply = (PICMP_ECHO_REPLY)ReplyBuffer;
struct in_addr ReplyAddr;
ReplyAddr.S_un.S_addr = pEchoReply->Address;
printf("\tSent icmp message to %s\n", argv[1]);
if (dwRetVal > 1) {
printf("\tReceived %ld icmp message responses\n", dwRetVal);
printf("\tInformation from the first response:\n");
}
else {
printf("\tReceived %ld icmp message response\n", dwRetVal);
printf("\tInformation from this response:\n");
}
printf("\t Received from %s\n", inet_ntoa( ReplyAddr ) );
printf("\t Status = %ld\n",
pEchoReply->Status);
printf("\t Roundtrip time = %ld milliseconds\n",
pEchoReply->RoundTripTime);
}
else {
printf("\tCall to IcmpSendEcho failed.\n");
printf("\tIcmpSendEcho returned error: %ld\n", GetLastError() );
return 1;
}
return 0;
}
需求
| 最低支援的用戶端 | Windows 2000 專業版 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | icmpapi.h |
| 程式庫 | Iphlpapi.lib |
| Dll | windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP 上的 Iphlpapi.dll;Windows 2000 Server 和 Windows 2000 專業版上的 Icmp.dll |