Fungsi IcmpSendEcho (icmpapi.h)

Artikel
08/24/2023

Fungsi IcmpSendEcho mengirimkan permintaan gema ICMP IPv4 dan mengembalikan balasan respons gema apa pun. Panggilan kembali ketika waktu habis telah kedaluwarsa atau buffer balasan diisi.

Sintaks

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
);

Parameter

[in] IcmpHandle

Handel terbuka yang dikembalikan oleh fungsi IcmpCreateFile .

[in] DestinationAddress

Alamat tujuan IPv4 dari permintaan gema, dalam bentuk struktur IPAddr .

[in] RequestData

Penunjuk ke buffer yang berisi data untuk dikirim dalam permintaan.

[in] RequestSize

Ukuran, dalam byte, dari buffer data permintaan yang diacu oleh parameter RequestData .

[in, optional] RequestOptions

Penunjuk ke opsi header IP untuk permintaan, dalam bentuk struktur IP_OPTION_INFORMATION . Pada platform 64-bit, parameter ini dalam bentuk untuk struktur IP_OPTION_INFORMATION32 .

Parameter ini mungkin NULL jika tidak ada opsi header IP yang perlu ditentukan.

[out] ReplyBuffer

Buffer untuk menahan balasan apa pun pada permintaan echo. Setelah kembali, buffer berisi array struktur ICMP_ECHO_REPLY diikuti oleh opsi dan data untuk balasan. Buffer harus cukup besar untuk menyimpan setidaknya satu struktur ICMP_ECHO_REPLY ditambah requestSize byte data.

[in] ReplySize

Ukuran yang dialokasikan, dalam byte, dari buffer balasan. Buffer harus cukup besar untuk menyimpan setidaknya satu struktur ICMP_ECHO_REPLY ditambah requestSize byte data.

Buffer ini juga harus cukup besar untuk juga menyimpan 8 byte data lagi (ukuran pesan kesalahan ICMP).

[in] Timeout

Waktu, dalam milidetik, untuk menunggu balasan.

Menampilkan nilai

Fungsi IcmpSendEcho mengembalikan jumlah struktur ICMP_ECHO_REPLY yang disimpan dalam ReplyBuffer. Status setiap balasan terkandung dalam struktur. Jika nilai yang dikembalikan adalah nol, panggil GetLastError untuk informasi kesalahan tambahan.

Jika fungsi gagal, kode kesalahan yang diperluas yang dikembalikan oleh GetLastError bisa menjadi salah satu nilai berikut.

Menampilkan kode	Deskripsi
ERROR_INSUFFICIENT_BUFFER	Area data yang diteruskan ke panggilan sistem terlalu kecil. Kesalahan ini dikembalikan jika parameter ReplySize menunjukkan bahwa buffer yang ditunjukkan oleh parameter ReplyBuffer terlalu kecil.
ERROR_INVALID_PARAMETER	Parameter yang tidak valid diteruskan ke fungsi. Kesalahan ini dikembalikan jika parameter IcmpHandle berisi handel yang tidak valid. Kesalahan ini juga dapat dikembalikan jika parameter ReplySize menentukan nilai yang kurang dari ukuran struktur ICMP_ECHO_REPLY .
ERROR_NOT_ENOUGH_MEMORY	Tidak cukup memori yang tersedia untuk menyelesaikan operasi.
ERROR_NOT_SUPPORTED	Permintaan tidak didukung. Kesalahan ini dikembalikan jika tidak ada tumpukan IPv4 di komputer lokal.
IP_BUF_TOO_SMALL	Ukuran ReplyBuffer yang ditentukan dalam parameter ReplySize terlalu kecil.
Lainnya	Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi IcmpSendEcho mengirim permintaan gema ICMP ke alamat yang ditentukan dan mengembalikan jumlah balasan yang diterima dan disimpan di ReplyBuffer. Fungsi IcmpSendEcho adalah fungsi sinkron dan kembali setelah menunggu waktu yang ditentukan dalam parameter Batas Waktu untuk respons. Jika nilai yang dikembalikan adalah nol, panggil GetLastError untuk informasi kesalahan yang diperluas.

Fungsi IcmpSendEcho2 dan IcmpSendEcho2Ex adalah versi IcmpSendEcho yang ditingkatkan yang mendukung operasi asinkron. Fungsi IcmpSendEcho2Ex juga memungkinkan alamat IP sumber ditentukan. Fitur ini berguna pada komputer dengan beberapa antarmuka jaringan.

Untuk IPv6, gunakan fungsi Icmp6CreateFile, Icmp6SendEcho2, dan Icmp6ParseReplies .

Fungsi IcmpSendEcho diekspor dari Icmp.dll pada Windows 2000. Fungsi IcmpSendEcho diekspor dari Iphlpapi.dll pada Windows XP dan yang lebih baru. Pemeriksaan versi Windows tidak disarankan untuk menggunakan fungsi ini. Aplikasi yang membutuhkan portabilitas dengan fungsi ini di windows 2000, Windows XP, Windows Server 2003 dan versi Windows yang lebih baru tidak boleh secara statis ditautkan ke file Icmp.lib atau Iphlpapi.lib . Sebaliknya, aplikasi harus memeriksa keberadaan IcmpSendEcho di Iphlpapi.dll dengan panggilan ke LoadLibrary dan GetProcAddress. Gagal itu, aplikasi harus memeriksa keberadaan IcmpSendEcho di Icmp.dll dengan panggilan ke LoadLibrary dan GetProcAddress.

Perhatikan bahwa direktif sertakan untuk file header Iphlpapi.h harus ditempatkan sebelum file header Icmpapi.h .

Contoh

Contoh berikut mengirimkan permintaan gema ICMP ke alamat IP yang ditentukan pada baris perintah dan mencetak informasi yang diterima dari respons pertama.

#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;
}

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	icmpapi.h
Pustaka	Iphlpapi.lib
DLL	Iphlpapi.dll pada Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP; Icmp.dll di Windows 2000 Server dan Windows 2000 Professional