Fungsi IcmpSendEcho2 (icmpapi.h)

Fungsi IcmpSendEcho2 mengirimkan permintaan echo ICMP IPv4, dan segera mengembalikan (jika Peristiwa atau ApcRoutine bukan NULL), atau kembali setelah waktu habis yang ditentukan. ReplyBuffer berisi respons gema ICMP, jika ada.

Sintaks

IPHLPAPI_DLL_LINKAGE DWORD IcmpSendEcho2(
  [in]           HANDLE                 IcmpHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [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, optional] Event

Peristiwa yang akan disinyalkan (paling banyak sekali) ketika respons ICMP tiba. Jika parameter ini ditentukan, maka parameter memerlukan handel ke objek peristiwa yang valid. Gunakan fungsi CreateEvent atau CreateEventEx untuk membuat objek kejadian ini.

Untuk informasi selengkapnya tentang menggunakan peristiwa, lihat Objek peristiwa.

[in, optional] ApcRoutine

Rutinitas yang dipanggil ketika utas panggilan berada dalam utas yang dapat diperingatkan, dan balasan ICMPv4 tiba. PIO_APC_ROUTINE_DEFINED harus didefinisikan untuk memaksa jenis data untuk parameter ini PIO_APC_ROUTINE daripada FARPROC.

[in, optional] ApcContext

Parameter opsional yang diteruskan ke rutinitas panggilan balik yang ditentukan dalam parameter ApcRoutine (paling banyak sekali) ketika respons ICMP tiba, atau terjadi kesalahan.

[in] DestinationAddress

Tujuan IPv4 dari permintaan echo, 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 .

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

[out] ReplyBuffer

Penunjuk ke buffer untuk menahan balasan apa pun terhadap permintaan. Setelah dikembalikan, buffer berisi array struktur ICMP_ECHO_REPLY diikuti dengan opsi dan data.

Buffer harus cukup besar untuk menyimpan setidaknya satu struktur ICMP_ECHO_REPLY , ditambah byte data RequestSize , ditambah 8 byte data tambahan (ukuran pesan kesalahan ICMP).

[in] ReplySize

Ukuran yang dialokasikan, dalam byte, dari buffer balasan.

Buffer harus cukup besar untuk menyimpan setidaknya satu struktur ICMP_ECHO_REPLY , ditambah byte data RequestSize , ditambah 8 byte data tambahan (ukuran pesan kesalahan ICMP).

[in] Timeout

Waktu dalam milidetik untuk menunggu balasan.

Nilai kembali

Ketika dipanggil secara sinkron, fungsi IcmpSendEcho2 mengembalikan jumlah balasan yang diterima dan disimpan di ReplyBuffer. Jika nilai yang dikembalikan adalah nol, maka untuk informasi kesalahan yang diperluas, panggil GetLastError.

Ketika dipanggil secara asinkron, fungsi IcmpSendEcho2 mengembalikan nol. Panggilan berikutnya ke GetLastError mengembalikan kode kesalahan yang diperluas ERROR_IO_PENDING untuk menunjukkan bahwa operasi sedang berlangsung. Hasilnya dapat diambil nanti ketika peristiwa yang ditentukan dalam sinyal parameter Peristiwa , atau fungsi panggilan balik dalam parameter ApcRoutine dipanggil.

Jika nilai yang dikembalikan adalah nol, maka untuk informasi kesalahan yang diperluas, panggil GetLastError.

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

Keterangan

Fungsi IcmpSendEcho2 dipanggil secara sinkron jika parameter ApcRoutine atau Event adalah NULL. Ketika dipanggil secara sinkron, nilai yang dikembalikan berisi jumlah balasan yang diterima dan disimpan di ReplyBuffer setelah menunggu waktu yang ditentukan dalam parameter Timeout . Jika nilai yang dikembalikan adalah nol, maka untuk informasi kesalahan yang diperluas, panggil GetLastError.

Fungsi IcmpSendEcho2 dipanggil secara asinkron ketika parameter ApcRoutine atau Event ditentukan. Ketika dipanggil secara asinkron, parameter ReplyBuffer dan ReplySize diperlukan untuk menerima respons. Data respons ICMP disalin ke ReplyBuffer yang disediakan, dan aplikasi diberi sinyal (ketika parameter Peristiwa ditentukan) atau fungsi panggilan balik dipanggil (ketika parameter ApcRoutine ditentukan). Aplikasi harus mengurai data yang diacu oleh parameter ReplyBuffer menggunakan fungsi IcmpParseReplies .

Jika parameter Peristiwa ditentukan, maka fungsi IcmpSendEcho2 dipanggil secara asinkron. Peristiwa yang ditentukan dalam parameter Peristiwa disinyalkan (paling banyak sekali) ketika respons ICMP tiba. Gunakan fungsi CreateEvent atau CreateEventEx untuk membuat objek kejadian ini.

Jika parameter ApcRoutine ditentukan, maka fungsi IcmpSendEcho2 dipanggil secara asinkron. Parameter ApcRoutine harus menunjuk ke fungsi panggilan balik yang ditentukan pengguna. Fungsi panggilan balik yang ditentukan dalam parameter ApcRoutine dipanggil (paling banyak sekali) ketika respons ICMP tiba. Pemanggilan fungsi panggilan balik yang ditentukan dalam parameter ApcRoutine diserialisasikan.

Jika parameter Peristiwa dan ApcRoutine ditentukan, maka peristiwa yang ditentukan dalam parameter Peristiwa disinyalkan (paling banyak sekali) ketika respons ICMP tiba, tetapi fungsi panggilan balik yang ditentukan dalam parameter ApcRoutine diabaikan.

Aplikasi apa pun yang memanggil fungsi IcmpSendEcho2 secara asinkron menggunakan parameter ApcRoutine harus menentukan PIO_APC_ROUTINE_DEFINED untuk memaksa jenis data parameter ApcRoutinePIO_APC_ROUTINE daripada FARPROC.

Fungsi panggilan balik yang ditunjukkan oleh ApcRoutine harus didefinisikan sebagai fungsi jenis VOID dengan sintaks berikut:

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

Parameter yang diteruskan ke fungsi panggilan balik meliputi yang berikut ini:

Fungsi panggilan balik yang ditentukan dalam parameter ApcRoutine harus diimplementasikan dalam proses yang sama dengan aplikasi yang memanggil fungsi IcmpSendEcho2 . Jika fungsi panggilan balik berada dalam DLL terpisah, maka DLL harus dimuat sebelum memanggil fungsi IcmpSendEcho2 .

Fungsi IcmpSendEcho2 diekspor dari Iphlpapi.dll.

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

Direktif sertakan Iphlpapi.h untuk file header harus ditempatkan sebelum Icmpapi.h file header.

Contoh

Contoh berikut memanggil fungsi IcmpSendEcho2 secara sinkron. Contoh mengirim 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;
    DWORD dwError = 0;
    char SendData[] = "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;
    }

    // Allocate space for a single reply.
    ReplySize = sizeof (ICMP_ECHO_REPLY) + sizeof (SendData) + 8;
    ReplyBuffer = (VOID *) malloc(ReplySize);
    if (ReplyBuffer == NULL) {
        printf("\tUnable to allocate memory for reply buffer\n");
        return 1;
    }

    dwRetVal = IcmpSendEcho2(hIcmpFile, NULL, NULL, NULL,
                             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  ", pEchoReply->Status);
        switch (pEchoReply->Status) {
        case IP_DEST_HOST_UNREACHABLE:
            printf("(Destination host was unreachable)\n");
            break;
        case IP_DEST_NET_UNREACHABLE:
            printf("(Destination Network was unreachable)\n");
            break;
        case IP_REQ_TIMED_OUT:
            printf("(Request timed out)\n");
            break;
        default:
            printf("\n");
            break;
        }

        printf("\t  Roundtrip time = %ld milliseconds\n",
               pEchoReply->RoundTripTime);
    } else {
        printf("Call to IcmpSendEcho2 failed.\n");
        dwError = GetLastError();
        switch (dwError) {
        case IP_BUF_TOO_SMALL:
            printf("\tReplyBufferSize too small\n");
            break;
        case IP_REQ_TIMED_OUT:
            printf("\tRequest timed out\n");
            break;
        default:
            printf("\tExtended error returned: %ld\n", dwError);
            break;
        }
        return 1;
    }
    return 0;
}

Persyaratan

Lihat juga

• CreateEvent
• CreateEventEx
• Objek peristiwa
• GetLastError
• ICMP_ECHO_REPLY
• IP_OPTION_INFORMATION
• IP_OPTION_INFORMATION32
• IPAddr
• Icmp6CreateFile
• Icmp6ParseReplies
• Icmp6SendEcho2
• IcmpCloseHandle
• IcmpCreateFile
• IcmpParseReplies
• IcmpSendEcho
• IcmpSendEcho2Ex