Fungsi IcmpSendEcho2Ex (icmpapi.h)

Artikel
08/24/2023

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

Sintaks

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

Parameter

[in] IcmpHandle

Handel terbuka yang dikembalikan oleh fungsi ICMPCreateFile .

[in, optional] Event

Peristiwa yang akan disinyalkan setiap kali respons ICMP tiba. Jika parameter ini ditentukan, 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 ICMP tiba. PIO_APC_ROUTINE_DEFINED harus didefinisikan untuk memaksa jenis data agar parameter ini PIO_APC_ROUTINE daripada FARPROC.

[in, optional] ApcContext

Parameter opsional yang diteruskan ke rutinitas panggilan balik yang ditentukan dalam parameter ApcRoutine setiap kali respons ICMP tiba atau terjadi kesalahan.

[in] SourceAddress

Alamat sumber IPv4 untuk mengeluarkan permintaan gema. Alamat ini dalam bentuk struktur IPAddr .

[in] DestinationAddress

Alamat tujuan IPv4 untuk permintaan echo. Alamat ini 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

Penunjuk ke buffer untuk menahan balasan apa pun terhadap permintaan. Setelah kembali, buffer berisi array struktur ICMP_ECHO_REPLY diikuti oleh opsi dan data. 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) ditambah ruang untuk struktur IO_STATUS_BLOCK .

[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) ditambah ruang untuk struktur IO_STATUS_BLOCK .

[in] Timeout

Waktu, dalam milidetik, untuk menunggu balasan.

Mengembalikan nilai

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

Ketika dipanggil secara asinkron, fungsi IcmpSendEcho2Ex mengembalikan ERROR_IO_PENDING untuk menunjukkan 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, panggil GetLastError untuk informasi kesalahan yang diperluas.

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

Menampilkan kode	Deskripsi
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_IO_PENDING	Operasi sedang berlangsung. Nilai ini dikembalikan oleh panggilan asinkron yang berhasil ke IcmpSendEcho2Ex dan bukan indikasi kesalahan.
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 IcmpSendEcho2Ex tersedia di Windows Server 2008 dan yang lebih baru.

Fungsi IcmpSendEcho2Ex adalah versi fungsi IcmpSendEcho2 yang disempurnakan yang memungkinkan pengguna menentukan alamat sumber IPv4 untuk mengeluarkan permintaan ICMP. Fungsi IcmpSendEcho2Ex berguna dalam kasus di mana komputer memiliki beberapa antarmuka jaringan.

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

Fungsi IcmpSendEcho2Ex 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, fungsi IcmpSendEcho2Ex disebut secara asinkron. Peristiwa yang ditentukan dalam parameter Peristiwa disinyalir setiap kali respons ICMP tiba. Gunakan fungsi CreateEvent untuk membuat objek kejadian ini.

Jika parameter ApcRoutine ditentukan, fungsi IcmpSendEcho2Ex dipanggil secara asinkron. Parameter ApcRoutine harus menunjuk ke fungsi panggilan balik yang ditentukan pengguna. Fungsi panggilan balik yang ditentukan dalam parameter ApcRoutine dipanggil setiap kali respons ICMP tiba. Pemanggilan fungsi panggilan balik yang ditentukan dalam parameter ApcRoutine diserialisasikan.

Jika parameter Peristiwa dan ApcRoutine ditentukan, peristiwa yang ditentukan dalam parameter Peristiwa disinyalir setiap kali respons ICMP tiba, tetapi fungsi panggilan balik yang ditentukan dalam parameter ApcRoutine diabaikan .

Aplikasi apa pun yang memanggil fungsi IcmpSendEcho2Ex secara asinkron menggunakan parameter ApcRoutine harus menentukan PIO_APC_ROUTINE_DEFINED untuk memaksa datatype untuk parameter ApcRoutineke PIO_APC_ROUTINE daripada FARPROC.

CatatanPIO_APC_ROUTINE_DEFINED harus ditentukan sebelum file header Icmpapi.h disertakan.

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:

Parameter	Deskripsi
IN PVOID ApcContext	Parameter ApcContext diteruskan ke fungsi IcmpSendEcho2Ex . Parameter ini dapat digunakan oleh aplikasi untuk mengidentifikasi permintaan IcmpSendEcho2Ex yang ditanggapi oleh fungsi panggilan balik.
IN PIO_STATUS_BLOCK IoStatusBlock	Pointer ke IO_STATUS_BLOCK. Variabel ini berisi status penyelesaian akhir dan informasi tentang operasi. Jumlah byte yang benar-benar diterima dalam balasan dikembalikan dalam anggota Informasi dari struktur IO_STATUS_BLOCK . Struktur IO_STATUS_BLOCK ditentukan dalam file header Wdm.h .
DI ULONG Dicadangkan	Parameter ini dicadangkan.

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

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

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

Persyaratan


Klien minimum yang didukung	Windows Vista dengan SP1 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	icmpapi.h
Pustaka	Iphlpapi.lib
DLL	Iphlpapi.dll