LPNSPV2LOOKUPSERVICENEXTEX fungsi panggilan balik (ws2spi.h)

Artikel
07/16/2024

Fungsi NSPv2LookupServiceNextEx dipanggil setelah mendapatkan handel dari panggilan sebelumnya ke NSPv2LookupServiceBegin untuk mengambil informasi yang diminta dari penyedia layanan namespace versi-2.

Sintaksis

LPNSPV2LOOKUPSERVICENEXTEX Lpnspv2lookupservicenextex;

void Lpnspv2lookupservicenextex(
  [in]      HANDLE hAsyncCall,
  [in]      HANDLE hLookup,
  [in]      DWORD dwControlFlags,
  [in, out] LPDWORD lpdwBufferLength,
  [out]     LPWSAQUERYSET2W lpqsResults
)
{...}

Parameter

[in] hAsyncCall

Handel yang dikembalikan dari panggilan sebelumnya ke NSPv2LookupServiceBegin digunakan untuk panggilan asinkron.

[in] hLookup

Handel yang dikembalikan dari panggilan sebelumnya ke NSPv2LookupServiceBegin.

[in] dwControlFlags

Bendera yang digunakan untuk mengontrol operasi berikutnya. Saat ini, hanya LUP_FLUSHPREVIOUS yang didefinisikan sebagai sarana untuk menangani tataan hasil yang terlalu besar. Jika aplikasi tidak dapat menyediakan buffer yang cukup besar, pengaturan LUP_FLUSHPREVIOUS menginstruksikan penyedia untuk membuang tataan hasil terakhir, yang terlalu besar, dan pindah ke set berikutnya untuk panggilan ini.

[in, out] lpdwBufferLength

Ukuran, dalam byte, pada input, yang terkandung dalam buffer yang diarahkan oleh lpqsResults. Pada output, jika fungsi gagal dan kesalahannya adalah WSAEFAULT, maka berisi ukuran minimum, dalam byte yang akan diteruskan untuk lpqsResults untuk mengambil rekaman.

[out] lpqsResults

Pointer ke blok memori yang akan berisi, saat dikembalikan, satu hasil diatur dalam struktur WSAQUERYSET2.

Mengembalikan nilai

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

Kode kesalahan	Arti
WSA_E_CANCELLED	Panggilan ke NSPv2LookupServiceEnd dilakukan saat panggilan ini masih diproses. Panggilan telah dibatalkan. Data dalam lpqsResults buffer tidak terdefinisi. Di Windows Sockets 2, kode kesalahan yang bertentangan didefinisikan untuk WSAECANCELLED (10103) dan WSA_E_CANCELLED (10111). Kode kesalahan WSAECANCELLED akan dihapus dalam versi mendatang dan hanya WSA_E_CANCELLED yang akan tetap ada. Penyedia namespace harus menggunakan kode kesalahan WSA_E_CANCELLED untuk mempertahankan kompatibilitas dengan berbagai aplikasi seluas mungkin.
WSA_E_NO_MORE	Tidak ada lagi data yang tersedia. Di Windows Sockets 2, kode kesalahan yang bertentangan didefinisikan untuk WSAENOMORE (10102) dan WSA_E_NO_MORE (10110). Kode kesalahan WSAENOMORE akan dihapus dalam versi mendatang dan hanya WSA_E_NO_MORE yang akan tetap ada. Penyedia namespace harus menggunakan kode kesalahan WSA_E_NO_MORE untuk mempertahankan kompatibilitas dengan berbagai aplikasi seluas mungkin.
WSAEFAULT	Buffer lpqsResults terlalu kecil untuk berisi WSAQUERYSET.
WSAEINVAL	Satu atau beberapa parameter tidak valid, atau hilang, untuk penyedia ini.
WSA_INVALID_HANDLE	Handel pencarian yang ditentukan tidak valid.
WSANO_DATA	Nama ditemukan dalam database, tetapi tidak ada data, yang cocok dengan batasan yang diberikan, ditemukan.
WSASERVICE_NOT_FOUND	Layanan ini tidak diketahui. Layanan tidak dapat ditemukan di namespace yang ditentukan.
WSA_NOT_ENOUGH_MEMORY	Tidak tersedia cukup memori untuk melakukan operasi ini.

Komentar

Fungsi NSPv2LookupServiceNextEx digunakan sebagai bagian dari arsitektur penyedia layanan namespace versi-2 (NSPv2) yang tersedia di Windows Vista dan yang lebih baru.

Pada Windows Vista dan Windows Server 2008, fungsi NSPv2LookupServiceNextEx hanya dapat digunakan untuk operasi pada penyedia namespace NS_EMAIL.

Penyedia akan melewati struktur WSAQUERYSET2 di lpqsResults buffer. Klien harus memanggil fungsi NSPv2LookupServiceNextEx hingga mengembalikan WSA_E_NOMORE, menunjukkan bahwa semua struktur WSAQUERYSET2 telah dikembalikan.

dwControlFlags ditentukan dalam fungsi ini dan yang ditentukan pada saat NSPv2LookupServiceBegin ditangani sebagai "pembatasan" untuk tujuan kombinasi. Pembatasan digabungkan antara yang NSPv2LookupServiceBegin waktu dan yang waktu NSPv2LookupServiceNextEx. Oleh karena itu, bendera di NSPv2LookupServiceNextEx tidak pernah dapat meningkatkan jumlah data yang dikembalikan melebihi apa yang diminta di NSPv2LookupServiceBegin, meskipun bukan kesalahan untuk menentukan lebih banyak atau kurang bendera. Bendera yang ditentukan pada tertentu NSPv2LookupServiceNextEx hanya berlaku untuk panggilan tersebut.

dwControlFlagsLUP_FLUSHPREVIOUS dan LUP_RES_SERVICE adalah pengecualian untuk aturan pembatasan gabungan (karena merupakan bendera perilaku alih-alih bendera "pembatasan"). Jika salah satu bendera digunakan dalam NSPv2LookupServiceNextEx, bendera tersebut memiliki efek yang ditentukan terlepas dari pengaturan bendera yang sama di NSPv2LookupServiceBegin.

Misalnya, jika LUP_RETURN_VERSION ditentukan di NSPv2LookupServiceBegin, penyedia layanan mengambil rekaman termasuk versi . Jika LUP_RETURN_VERSION tidak ditentukan di NSPv2LookupServiceNextEx, informasi yang dikembalikan tidak menyertakan versi, meskipun tersedia. Tidak ada kesalahan yang dihasilkan.

Juga misalnya, jika LUP_RETURN_BLOB tidak ditentukan di NSPv2LookupServiceBegin, tetapi ditentukan pada NSPv2LookupServiceNextEx, informasi yang dikembalikan tidak menyertakan data privat. Tidak ada kesalahan yang dihasilkan.

Fungsi NSPv2LookupServiceNextEx biasanya disebut setidaknya dua kali. Pertama kali untuk mendapatkan ukuran buffer yang diperlukan untuk menerima WSAQUERYSET2 yang ditunjukkan oleh parameter lpqsResults, dan kedua kalinya untuk mendapatkan kumpulan hasil kueri yang sebenarnya. Pada panggilan pertama, penyedia NSPv2 harus mengembalikan ukuran yang diperlukan untuk hasil WSAQUERYSET2.

Struktur WSAQUERYSET2 yang diarahkan oleh parameter lpqsResults yang dikembalikan hanya berguna dalam konteks proses yang sama, karena beberapa anggota dalam struktur WSAQUERYSET2 berisi penunjuk ke data aktual yang dikembalikan. Jika hasil kueri perlu diteruskan ke proses lain (menggunakan RPC, misalnya), maka perlu untuk membuat serialisasi dan marshal data yang dikembalikan dalam struktur WSAQUERYSET2 yang ditunjukkan oleh parameter lpqsResults termasuk data yang diarahkan oleh anggota dalam struktur WSAQUERYSET2. Data perlu diserialisasikan dalam bentuk yang dapat diteruskan di seluruh batas proses. Hanya meneruskan salinan struktur WSAQUERYSET2 tidak mencukupi, karena hanya pointer ke data yang akan diteruskan dan data aktual tidak akan tersedia untuk proses lain.

Hasil Kueri

Tabel berikut ini mencantumkan WSAQUERYSET2 dan menjelaskan bagaimana hasil kueri diwakili dalam struktur **WSAQUERYSET2**. Untuk informasi selengkapnya, lihat Query-Related Struktur Data.

nama anggota WSAQUERYSET2	Interpretasi hasil
dwSize	Ukurannya, dalam byte, dari struktur WSAQUERYSET2. Ini digunakan sebagai mekanisme penerapan versi.
lpszServiceInstanceName	String yang berisi nama layanan.
lpVersion	Mereferensikan nomor versi instans layanan tertentu.
lpszComment	String komentar yang disediakan oleh instans layanan. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2.
dwNameSpace	Pengidentifikasi namespace tempat nama atau instans layanan ditemukan.
lpNSProviderId	Penyedia namespace khusus yang menyediakan hasil kueri ini.
lpszContext	Titik konteks dalam namespace hierarkis tempat layanan berada.
dwNumberOfProtocols	Anggota ini tidak ditentukan untuk hasil.
lpafpProtocols	Anggota ini tidak ditentukan untuk hasil. Semua informasi protokol yang diperlukan ada dalam struktur CSADDR_INFO.
lpszQueryString	Saat dwControlFlags menyertakan LUP_RETURN_QUERY_STRING, anggota ini mengembalikan sisa lpszServiceInstanceName yang ditentukan dalam kueri asli. Misalnya, di namespace layanan yang mengidentifikasi layanan dengan nama hierarkis yang menentukan nama host dan jalur file dalam host tersebut, alamat yang dikembalikan mungkin alamat host dan sisa yang tidak dipisahkan mungkin merupakan jalur file. Jika lpszServiceInstanceName sepenuhnya diurai dan LUP_RETURN_QUERY_STRING digunakan, anggota ini null atau menunjuk ke string panjang nol.
dwNumberOfCsAddrs	Jumlah elemen dalam array struktur CSADDR_INFO.
lpcsaBuffer	Penunjuk ke array struktur CSADDR_INFO, dengan satu alamat transportasi lengkap yang terkandung dalam setiap elemen.
dwOutputFlags	Bendera RESULT_IS_ALIAS menunjukkan ini adalah hasil alias.
lpBlob	Penunjuk ke entitas khusus penyedia. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Platform Target	Windows
Header	ws2spi.h

Lihat juga

CSADDR_INFO

NSPV2_ROUTINE

NSPv2Cleanup

NSPv2ClientSessionRundown

NSPv2LookupServiceBegin

NSPv2LookupServiceEnd

nama anggota WSAQUERYSET2	Interpretasi hasil
dwSize	Ukurannya, dalam byte, dari struktur WSAQUERYSET2. Ini digunakan sebagai mekanisme penerapan versi.
lpszServiceInstanceName	String yang berisi nama layanan.
lpVersion	Mereferensikan nomor versi instans layanan tertentu.
lpszComment	String komentar yang disediakan oleh instans layanan. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2.
dwNameSpace	Pengidentifikasi namespace tempat nama atau instans layanan ditemukan.
lpNSProviderId	Penyedia namespace khusus yang menyediakan hasil kueri ini.
lpszContext	Titik konteks dalam namespace hierarkis tempat layanan berada.
dwNumberOfProtocols	Anggota ini tidak ditentukan untuk hasil.
lpafpProtocols	Anggota ini tidak ditentukan untuk hasil. Semua informasi protokol yang diperlukan ada dalam struktur CSADDR_INFO.
lpszQueryString	Saat dwControlFlags menyertakan LUP_RETURN_QUERY_STRING, anggota ini mengembalikan sisa lpszServiceInstanceName yang ditentukan dalam kueri asli. Misalnya, di namespace layanan yang mengidentifikasi layanan dengan nama hierarkis yang menentukan nama host dan jalur file dalam host tersebut, alamat yang dikembalikan mungkin alamat host dan sisa yang tidak dipisahkan mungkin merupakan jalur file. Jika lpszServiceInstanceName sepenuhnya diurai dan LUP_RETURN_QUERY_STRING digunakan, anggota ini null atau menunjuk ke string panjang nol.
dwNumberOfCsAddrs	Jumlah elemen dalam array struktur CSADDR_INFO.
lpcsaBuffer	Penunjuk ke array struktur CSADDR_INFO, dengan satu alamat transportasi lengkap yang terkandung dalam setiap elemen.
dwOutputFlags	Bendera RESULT_IS_ALIAS menunjukkan ini adalah hasil alias.
lpBlob	Penunjuk ke entitas khusus penyedia. Anggota ini bersifat opsional, tergantung pada persyaratan penyedia layanan NSPv2.

Bagikan melalui