Fungsi panggilan balik LPNSPIOCTL (ws2spi.h)

Artikel
08/28/2023

Fungsi NSPIoctl mengirimkan IOCTL ke penyedia layanan namespace.

Sintaks

LPNSPIOCTL Lpnspioctl;

INT Lpnspioctl(
  [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,
  [in]      LPWSATHREADID lpThreadId
)
{...}

Parameter

[in] hLookup

Handel pencarian dikembalikan dari panggilan sebelumnya ke fungsi NSPLookupServiceBegin .

[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
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 NSPLookupServiceBegin untuk mengambil parameter hLookup . Panggilan sebelumnya ini juga dapat mencakup panggilan ke fungsi NSPLookupServiceNext 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.

[in] lpThreadId

Penunjuk ke struktur WSATHREADID yang akan digunakan oleh penyedia dalam panggilan berikutnya ke WPUQueueApc. Penyedia harus menyimpan struktur WSATHREADID yang direferensikan (bukan penunjuk) sampai setelah fungsi WPUQueueApc kembali.

Nilai kembali

Jika tidak ada kesalahan yang terjadi dan operasi telah selesai segera, fungsi NSPIoctl harus mengembalikan NO_ERROR (nol). Perhatikan bahwa dalam hal ini rutinitas penyelesaian, jika ditentukan, akan telah diantrekan.

Fungsi NSPIoctl harus mengembalikan SOCKET_ERROR (yaitu, 1) jika rutinitas gagal dan harus mengatur kode kesalahan yang sesuai menggunakan WSASetLastError.

Kode kesalahan WSA_IO_PENDING menunjukkan bahwa operasi yang tumpang tindih telah berhasil dimulai dan penyelesaian tersebut akan ditunjukkan di lain waktu. Kode kesalahan lainnya menunjukkan bahwa tidak ada operasi yang tumpang tindih yang dimulai dan tidak ada indikasi penyelesaian yang akan terjadi.

Kode kesalahan	Deskripsi
WSA_INVALID_HANDLE	Parameter hLookup bukan handel kueri valid yang dikembalikan oleh NSPLookupServiceBegin.
WSA_IO_PENDING	Operasi yang tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu.
WSAEFAULT	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.
WSAEINVAL	Parameter yang disediakan tidak dapat diterima, atau operasi secara tidak tepat mengembalikan hasil dari beberapa namespace ketika tidak masuk akal untuk operasi yang ditentukan.
WSAENETDOWN	Subsistem jaringan gagal.
WSAEOPNOTSUPP	Operasi tidak didukung. Kesalahan ini dikembalikan jika penyedia namespace tidak menerapkan fungsi ini. Kesalahan ini juga dapat dikembalikan jika dwControlCode yang ditentukan adalah perintah yang tidak dikenali.
WSAEWOULDBLOCK	Sumber daya untuk sementara tidak tersedia. 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 NSPIoctl digunakan untuk mengirim kode kontrol I/O ke penyedia namespace untuk mengatur atau mengambil parameter operasi yang terkait dengan handel kueri. Parameter hLookup adalah handel ke kueri penyedia namespace yang sebelumnya dikembalikan oleh fungsi NSPLookupServiceBegin (bukan handel soket).

Setiap IOCTL yang dikirim ke penyedia namespace layanan dapat memblokir tanpa batas waktu, tergantung pada implementasi namespace layanan. Jika aplikasi tidak dapat mentolerir pemblokiran dalam panggilan fungsi NSPIoctl , I/O yang tumpang tindih harus digunakan dan parameter lpCompletion harus menunjuk ke struktur WSACOMPLETION . Untuk membuat fungsi NSPIoctl memanggil nonblocking dan segera kembali, atur jenis anggota struktur WSACOMPLETION ke NSP_NOTIFY_IMMEDIATELY.

Jika lpCompletion adalah NULL, fungsi NSPIoctl dijalankan sebagai panggilan pemblokiran. Penyedia namespace harus segera kembali dan tidak boleh memblokir. Tetapi setiap penyedia namespace bertanggung jawab untuk menegakkan perilaku ini.

Kode IOCTL berikut didukung oleh beberapa penyedia namespace 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 NSPLookupServiceBegin untuk mengambil parameter hLookup . Panggilan sebelumnya ini juga dapat mencakup panggilan ke fungsi NSPLookupServiceNext menggunakan parameter hLookup .

Penyedia namespace Microsoft yang mendukung IOCTL ini mencakup hal berikut:

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 mungkin diinstal yang juga mendukung IOCTL ini.

Ketika parameter lpCompletion adalah 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 NSPIoctl 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 NSPIoctl adalah sebagai berikut. Panggil fungsi NSPIoctl dengan parameter dwControlCode yang diatur ke SIO_NSP_NOTIFY_CHANGE tanpa rutinitas penyelesaian (parameter lpCompletion diatur ke NULL) setelah setiap panggilan fungsi NSPLookupServiceNext untuk memastikan data kueri masih valid. Jika data menjadi tidak valid, panggil fungsi NSPLookupServiceEnd untuk menutup handel kueri. Panggil fungsi NSPLookupServiceBegin untuk mengambil handel kueri baru dan mulai kueri lagi.

Untuk aplikasi multithread, metode umum untuk menggunakan fungsi NSPIoctl adalah sebagai berikut. Panggil fungsi NSPIoctl dengan parameter dwControlCode yang diatur ke SIO_NSP_NOTIFY_CHANGE dengan rutinitas penyelesaian setelah panggilan awal ke fungsi NSPLookupServiceBegin . 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 NSPLookupServiceEnd untuk menutup handel kueri. Panggil fungsi NSPLookupServiceBegin dan NSPIoctl 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 mungkin dikeluarkan untuk menunjukkan cache lokal telah tidak valid.

Untuk protokol resolusi nama di mana perubahan jarang terjadi, dimungkinkan bagi penyedia namespace layanan untuk menunjukkan peristiwa perubahan global yang mungkin tidak berlaku untuk kueri tempat pemberitahuan perubahan diminta dan dikeluarkan.

Operasi polling langsung biasanya jauh lebih sedikit sumber daya intensif 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, 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 NSPLookupServiceEnd pada handel kueri yang terpengaruh. Membatalkan pemberitahuan asinkron untuk LUP_NOTIFY_HWND tidak akan memposting pesan apa pun, namun, operasi yang tumpang tindih akan diselesaikan dan pemberitahuan akan dikirimkan dengan kesalahan WSA_OPERATION_ABORTED.

**Catatan** Semua I/O yang dimulai oleh utas tertentu dibatalkan ketika utas tersebut keluar. Untuk soket yang tumpang tindih, operasi asinkron yang tertunda dapat gagal jika utas ditutup sebelum operasi selesai. Lihat ExitThread untuk informasi selengkapnya.

Persyaratan


Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	ws2spi.h