Fungsi IcmpSendEcho2Ex (icmpapi.h)
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 |
---|---|
|
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 . |
|
Operasi sedang berlangsung. Nilai ini dikembalikan oleh panggilan asinkron yang berhasil ke IcmpSendEcho2Ex dan bukan indikasi kesalahan. |
|
Tidak cukup memori yang tersedia untuk menyelesaikan operasi. |
|
Permintaan tidak didukung. Kesalahan ini dikembalikan jika tidak ada tumpukan IPv4 di komputer lokal. |
|
Ukuran ReplyBuffer yang ditentukan dalam parameter ReplySize terlalu kecil. |
|
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.
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:
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 |