Fungsi Icmp6SendEcho2 (icmpapi.h)

Artikel
03/05/2024

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

Sintaks

IPHLPAPI_DLL_LINKAGE DWORD Icmp6SendEcho2(
  [in]           HANDLE                 IcmpHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [in]           sockaddr_in6           *SourceAddress,
  [in]           sockaddr_in6           *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 Icmp6CreateFile.

[in, optional] Event

Peristiwa yang akan disinyalkan setiap kali respons ICMPv6 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 ICMPv6 tiba. Pada Windows Vista dan yang lebih baru, PIO_APC_ROUTINE_DEFINED harus didefinisikan untuk memaksa jenis data agar parameter ini PIO_APC_ROUTINE daripada FARPROC.

Pada Windows Server 2003 dan Windows XP, PIO_APC_ROUTINE_DEFINED tidak boleh didefinisikan untuk memaksa jenis data untuk parameter ini ke FARPROC.

[in, optional] ApcContext

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

[in] SourceAddress

Alamat sumber IPv6 untuk mengeluarkan permintaan echo, dalam bentuk struktur sockaddr .

[in] DestinationAddress

Alamat tujuan IPv6 dari permintaan gema, dalam bentuk struktur sockaddr .

[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 IPv6 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.

Catatan Pada Windows Server 2003 dan Windows XP, parameter RequestOptions tidak opsional dan tidak boleh NULL dan hanya anggota Ttl dan Flags yang digunakan.

[out] ReplyBuffer

Penunjuk ke buffer untuk menahan balasan atas permintaan. Setelah dikembalikan, buffer berisi struktur ICMPV6_ECHO_REPLY diikuti oleh isi pesan dari data balasan respons gema ICMPv6. Buffer harus cukup besar untuk menyimpan setidaknya satu struktur ICMPV6_ECHO_REPLY ditambah jumlah byte data yang ditentukan dalam parameter RequestSize . 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, dalam byte, dari buffer balasan yang diacu oleh parameter ReplyBuffer . Buffer ini harus cukup besar untuk menyimpan setidaknya satu struktur ICMPV6_ECHO_REPLY ditambah byte data RequestSize . 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. Parameter ini hanya digunakan jika fungsi Icmp6SendEcho2 dipanggil secara sinkron. Jadi parameter ini tidak digunakan jika parameter ApcRoutine atau Event bukan NULL.

Nilai kembali

Ketika dipanggil secara sinkron, mengembalikan jumlah balasan yang diterima dan disimpan di ReplyBuffer.

Ketika dipanggil secara asinkron, menunjukkan bahwa operasi sedang berlangsung dengan mengembalikan ERROR_IO_PENDING. Anda dapat mengambil hasil jumlah balasan nanti, ketika peristiwa yang ditentukan dalam sinyal parameter Peristiwa , atau ketika fungsi panggilan balik dalam parameter ApcRoutine dipanggil.

Jika nilai jumlah balasan (sinkron atau asinkron) 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.

Menampilkan kode	Deskripsi
ERROR_CALL_NOT_IMPLEMENTED	Fungsi ini tidak didukung pada sistem ini.
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	Salah satu parameter tidak valid. Kesalahan ini dikembalikan jika parameter IcmpHandle berisi handel yang tidak valid.
ERROR_IO_PENDING	Operasi sedang berlangsung. Nilai ini dikembalikan oleh panggilan asinkron yang berhasil ke Icmp6SendEcho2 dan bukan indikasi kesalahan.
ERROR_NOT_ENOUGH_MEMORY	Tidak tersedia cukup memori untuk memproses perintah ini.
ERROR_NOT_SUPPORTED	Permintaan tidak didukung. Kesalahan ini dikembalikan jika tidak ada tumpukan IPv6 pada 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 Icmp6SendEcho2 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, panggil GetLastError untuk informasi kesalahan yang diperluas.

Fungsi Icmp6SendEcho2 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 disinyalkan (ketika parameter Peristiwa ditentukan) atau fungsi panggilan balik dipanggil (ketika parameter ApcRoutine ditentukan). Aplikasi harus mengurai data yang diacu oleh parameter ReplyBuffer menggunakan fungsi Icmp6ParseReplies .

Jika parameter Peristiwa ditentukan, fungsi Icmp6SendEcho2 dipanggil secara asinkron. Peristiwa yang ditentukan dalam parameter Peristiwa disinyalkan setiap kali respons ICMPv6 tiba. Gunakan fungsi CreateEvent untuk membuat objek kejadian ini.

Jika parameter ApcRoutine ditentukan, fungsi Icmp6SendEcho2 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 ICMPv6 tiba. Pemanggilan fungsi panggilan balik yang ditentukan dalam parameter ApcRoutine diserialisasikan.

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

Pada Windows Vista dan yang lebih baru, aplikasi apa pun yang memanggil fungsi Icmp6SendEcho2 secara asinkron menggunakan parameter ApcRoutine harus menentukan PIO_APC_ROUTINE_DEFINED untuk memaksa jenis data parameter ApcRoutine ke PIO_APC_ROUTINE daripada FARPROC.

CatatanPIO_APC_ROUTINE_DEFINED harus ditentukan sebelum file header Icmpapi.h disertakan.

Pada Windows Vista dan yang lebih baru, 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
    );

Pada Windows Vista dan yang lebih baru, parameter yang diteruskan ke fungsi panggilan balik meliputi yang berikut ini:

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

Pada Windows Server 2003 dan Windows XP, aplikasi apa pun yang memanggil fungsi Icmp6SendEcho2 secara asinkron menggunakan parameter ApcRoutine tidak boleh menentukan PIO_APC_ROUTINE_DEFINED untuk memaksa jenis data untuk parameter ApcRoutine ke FARPROC daripada PIO_APC_ROUTINE.

Pada Windows Server 2003 dan Windows XP, fungsi panggilan balik yang ditunjukkan oleh ApcRoutine harus didefinisikan sebagai fungsi jenis VOID dengan sintaks berikut:

typedef
VOID WINAPI
(*FARPROC) (
    IN PVOID ApcContext,
    );

Pada Windows Server 2003 dan Windows XP, parameter yang diteruskan ke fungsi panggilan balik meliputi yang berikut ini:

Parameter	Deskripsi
DALAM PVOID ApcContext	Parameter ApcContext diteruskan ke fungsi Icmp6SendEcho2 . Parameter ini dapat digunakan oleh aplikasi untuk mengidentifikasi permintaan Icmp6SendEcho2 yang ditanggapi oleh fungsi panggilan balik.

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

Untuk IPv4, gunakan fungsi IcmpCreateFile, IcmpSendEcho, IcmpSendEcho2, IcmpSendEcho2Ex, dan IcmpParseReplies .

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

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	icmpapi.h
Pustaka	Iphlpapi.lib
DLL	Iphlpapi.dll