icmpSendEcho 函式 (icmpapi.h)

發行項
08/24/2023

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

傳回碼	描述
ERROR_INSUFFICIENT_BUFFER	傳遞至系統呼叫的資料區域太小。如果 ReplySize 參數指出 ReplyBuffer 參數所指向的緩衝區太小，就會傳回此錯誤。
ERROR_INVALID_PARAMETER	不正確參數已傳遞至函式。如果 IcmpHandle 參數包含不正確控制碼，就會傳回此錯誤。如果 ReplySize 參數指定的值小於 ICMP_ECHO_REPLY 結構的大小，也可以傳回此錯誤。
ERROR_NOT_ENOUGH_MEMORY	可用的記憶體不足，無法完成作業。
ERROR_NOT_SUPPORTED	不支援此要求。如果本機電腦上沒有 IPv4 堆疊，就會傳回此錯誤。
IP_BUF_TOO_SMALL	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