Fungsi WSANSPIoctl (winsock2.h)
Fungsi Windows Sockets WSANSPIoctl memungkinkan pengembang untuk melakukan panggilan kontrol I/O ke namespace terdaftar.
Sintaks
INT WSAAPI WSANSPIoctl(
[in] HANDLE hLookup,
[in] DWORD dwControlCode,
[in] LPVOID lpvInBuffer,
[in, out] DWORD cbInBuffer,
[out] LPVOID lpvOutBuffer,
[in] DWORD cbOutBuffer,
[out] LPDWORD lpcbBytesReturned,
[in] LPWSACOMPLETION lpCompletion
);
Parameter
[in] hLookup
Handel pencarian dikembalikan dari panggilan sebelumnya ke fungsi WSALookupServiceBegin .
[in] dwControlCode
Kode kontrol operasi yang akan dilakukan.
Nilai yang dapat digunakan untuk parameter dwControlCode ditentukan oleh penyedia namespace layanan.
Nilai berikut didukung oleh beberapa penyedia namespace Microsoft termasuk penyedia namespace Network Location Awareness (NS_NLA). IOCTL ini didefinisikan dalam file header Winsock2.h.
| Nilai | Makna |
|---|---|
|
Operasi ini memeriksa apakah hasil yang dikembalikan dengan panggilan sebelumnya menggunakan parameter hLookup masih valid. Panggilan sebelumnya ini mencakup panggilan awal ke fungsi WSALookupServiceBegin untuk mengambil parameter hLookup . Panggilan sebelumnya ini juga dapat mencakup panggilan ke fungsi WSALookupServiceNext menggunakan parameter hLookup . |
[in] lpvInBuffer
Penunjuk ke buffer input.
[in, out] cbInBuffer
Ukuran, dalam byte, dari buffer input.
[out] lpvOutBuffer
Penunjuk ke buffer output.
[in] cbOutBuffer
Ukuran, dalam byte, dari buffer output.
[out] lpcbBytesReturned
Penunjuk ke jumlah byte yang dikembalikan.
[in] lpCompletion
Penunjuk ke struktur WSACOMPLETION , digunakan untuk pemrosesan asinkron. Atur lpCompletion ke NULL untuk memaksa pemblokiran (sinkron) eksekusi.
Nilai kembali
Keberhasilan mengembalikan NO_ERROR. Kegagalan mengembalikan SOCKET_ERROR, dan kode kesalahan tertentu dapat diambil dengan memanggil fungsi WSAGetLastError . Tabel berikut ini menjelaskan kode kesalahan.
| Kode kesalahan | Deskripsi |
|---|---|
| Parameter hLookup bukan handel kueri yang valid yang dikembalikan oleh WSALookupServiceBegin. | |
| Operasi yang tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu. | |
| Argumen lpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer, atau lpCompletion tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid. Atau, argumen cbInBuffer atau cbOutBuffer terlalu kecil, dan argumen dimodifikasi untuk mencerminkan ukuran alokasi yang diperlukan. | |
| Parameter yang disediakan tidak dapat diterima, atau operasi secara tidak pantas mengembalikan hasil dari beberapa namespace ketika tidak masuk akal untuk operasi yang ditentukan. | |
| Subsistem jaringan gagal. | |
| Operasi ini tidak didukung. Kesalahan ini dikembalikan jika penyedia namespace tidak mengimplementasikan fungsi ini. Kesalahan ini juga dapat dikembalikan jika dwControlCode yang ditentukan adalah perintah yang tidak dikenali. | |
|
Soket tidak menggunakan I/O yang tumpang tindih (pemrosesan asinkron), namun parameter lpCompletion bukan NULL.
Kesalahan ini digunakan sebagai pemberitahuan khusus untuk SIO_NSP_NOTIFY_CHANGE IOCTL ketika parameter lpCompletion adalah NULL (polling) untuk menunjukkan bahwa kumpulan kueri tetap valid. |
Keterangan
Fungsi WSANSPIoctl digunakan untuk mengatur atau mengambil parameter operasi yang terkait dengan handel kueri ke penyedia namespace. Parameter hLookup adalah handel ke kueri penyedia namespace yang sebelumnya dikembalikan oleh fungsi WSALookupServiceBegin (bukan handel soket).
Setiap IOCTL yang dikirim ke penyedia namespace dapat memblokir tanpa batas waktu, tergantung pada implementasi namespace layanan. Jika aplikasi tidak dapat mentolerir pemblokiran dalam panggilan fungsi WSANSPIoctl , I/O yang tumpang tindih harus digunakan dan parameter lpCompletion harus menunjuk ke struktur WSACOMPLETION . Untuk membuat fungsi WSANSPIoctl memanggil nonblocking dan segera kembali, atur anggota Jenis struktur WSACOMPLETION ke NSP_NOTIFY_IMMEDIATELY.
Jika lpCompletionADALAH NULL, fungsi WSANSPIoctl dijalankan sebagai panggilan pemblokiran. Penyedia namespace harus segera kembali dan tidak boleh memblokir. Tetapi setiap namespace bertanggung jawab untuk menegakkan perilaku ini.
Kode IOCTL berikut didukung oleh beberapa penyedia ruang nama Microsoft:
- SIO_NSP_NOTIFY_CHANGE
-
Operasi ini memeriksa apakah hasil yang dikembalikan dengan panggilan sebelumnya menggunakan parameter hLookup masih valid. Panggilan sebelumnya ini mencakup panggilan awal ke fungsi WSALookupServiceBegin untuk mengambil parameter hLookup . Panggilan sebelumnya ini juga dapat mencakup panggilan ke fungsi WSALookupServiceNext menggunakan parameter hLookup .
Penyedia namespace Microsoft yang mendukung IOCTL ini menyertakan yang berikut ini
- NS_NLA - Penyedia namespace Network Location Awareness (NLA).
- NS_PNRPNAME - Penyedia namespace Protokol Resolusi Nama Serekan (PNRP).
- NS_PNRPCLOUD - Penyedia namespace layanan cloud Peer Name Resolution Protocol (PNRP).
Penyedia namespace layanan non-Microsoft lainnya dapat diinstal yang juga mendukung IOCTL ini.
Ketika parameter lpCompletionadalah NULL, IOCTL ini menerapkan perilaku khusus. Jika parameter lpCompletion adalah NULL untuk IOCTL ini, operasi ini adalah polling dan segera kembali. Jika kumpulan kueri tetap valid, WSAEWOULDBLOCK dikembalikan sebagai pemberitahuan bahwa kumpulan kueri tetap valid. Jika kumpulan kueri telah berubah dan tidak valid, NO_ERROR dikembalikan yang menunjukkan keberhasilan dalam polling untuk pembatalan kumpulan kueri.
Jika parameter lpCompletion bukan NULL dan menunjuk ke struktur WSACOMPLETION , maka fungsi WSANSPIoctl mengembalikan WSA_IO_PENDING jika operasi yang tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu. Metode yang ditentukan dalam struktur WSACOMPLETION digunakan untuk memberi tahu aplikasi jika kumpulan kueri masih valid.
Tidak semua protokol resolusi nama dapat mendukung fitur ini, dan oleh karena itu, panggilan fungsi ini mungkin gagal dengan WSAEOPNOTSUPP. Kueri yang berisi data dari beberapa penyedia tidak dapat memanggil IOCTL ini, dan akan mengembalikan WSAEINVAL.
Parameter lpvInBuffer, cbInBuffer, lpvOutBuffer, dan cbOutBuffer saat ini diabaikan oleh penyedia namespace Microsoft.
Untuk aplikasi utas tunggal, metode umum untuk menggunakan fungsi WSANSPIoctl adalah sebagai berikut. Panggil fungsi WSANSPIoctl dengan parameter dwControlCode yang diatur ke SIO_NSP_NOTIFY_CHANGE tanpa rutinitas penyelesaian (parameter lpCompletion diatur ke NULL) setelah setiap panggilan fungsi WSALookupServiceNext untuk memastikan data kueri masih valid. Jika data menjadi tidak valid, panggil fungsi WSALookupServiceEnd untuk menutup handel kueri. Panggil fungsi WSALookupServiceBegin untuk mengambil handel kueri baru dan mulai kueri lagi.
Untuk aplikasi multi-utas, metode umum untuk menggunakan fungsi WSANSPIoctl adalah sebagai berikut. Panggil fungsi WSANSPIoctl dengan parameter dwControlCode yang diatur ke SIO_NSP_NOTIFY_CHANGE dengan rutinitas penyelesaian setelah panggilan awal ke fungsi WSALookupServiceBegin . Aplikasi akan menggunakan mekanisme untuk pemberitahuan yang ditentukan dalam rutinitas penyelesaian untuk diberi tahu ketika data tidak lagi valid. Salah satu mekanisme umum adalah menggunakan peristiwa yang ditentukan dalam rutinitas penyelesaian. Jika data menjadi tidak valid, panggil fungsi WSALookupServiceEnd untuk menutup handel kueri. Panggil fungsi WSALookupServiceBegin dan WSANSPIoctl untuk mengambil handel kueri baru dan memulai kueri lagi.
Beberapa protokol mungkin hanya menyimpan informasi secara lokal dan membatalkannya setelah beberapa waktu, dalam hal ini pemberitahuan dapat dikeluarkan untuk menunjukkan cache lokal telah dibatalkan.
Untuk protokol resolusi nama di mana perubahan jarang terjadi, dimungkinkan bagi penyedia namespace untuk menunjukkan peristiwa perubahan global yang mungkin tidak berlaku untuk kueri tempat pemberitahuan perubahan diminta dan dikeluarkan.
Operasi polling langsung biasanya jauh lebih murah karena tidak memerlukan objek pemberitahuan. Dalam kebanyakan kasus, ini diimplementasikan sebagai pemeriksaan variabel Boolean sederhana. Namun, pemberitahuan asinkron dapat mengharuskan pembuatan utas pekerja khusus dan/atau saluran komunikasi antar-proses, tergantung pada implementasi layanan penyedia namespace layanan, dan akan menimbulkan overhead pemrosesan yang terkait dengan objek pemberitahuan yang terlibat dengan sinyal peristiwa perubahan.
Untuk membatalkan permintaan pemberitahuan asinkron, akhiri kueri asli dengan panggilan fungsi WSALookupServiceEnd pada handel kueri yang terpengaruh. Membatalkan pemberitahuan asinkron untuk LUP_NOTIFY_HWND tidak akan memposting pesan apa pun, namun, operasi yang tumpang tindih akan selesai dan pemberitahuan akan dikirimkan dengan kesalahan WSA_OPERATION_ABORTED.
Windows 8.1 dan Windows Server 2012 R2: Fungsi ini didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 8.1, Windows Vista [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | winsock2.h |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk